# containers.podman.podman_image module – Pull images for use by podman

Note

This module is part of the containers.podman collection (version 1.20.0).

It is not included in `ansible-core`. To check whether it is installed, run `ansible-galaxy collection list`.

To install it, use: `ansible-galaxy collection install containers.podman`.

To use it in a playbook, specify: `containers.podman.podman_image`.

## Synopsis

- Build, pull, or push images using Podman.

## Parameters

Parameter | Comments
--- | ---
arch string | CPU architecture for the container image
auth_file aliases: authfile path | Path to file containing authorization credentials to the remote registry.
build aliases: build_args, buildargs dictionary | Arguments that control image build. Default: `{}`
annotation dictionary | Dictionary of key=value pairs to add to the image. Only works with OCI images. Ignored for Docker containers.

cache

boolean

Whether or not to use cached layers when building an image

Choices:

- `false`

- `true` ← (default)

container_file string | Content of the Containerfile to use for building the image. Mutually exclusive with the `file` option which is path to the existing Containerfile.
extra_args string | Extra args to pass to build, if executed. Does not idempotently check for new build args.
file path | Path to the Containerfile if it is not in the build context directory. Mutually exclusive with the `container_file` option.

force_rm

boolean

Always remove intermediate containers after a build, even if the build is unsuccessful.

Choices:

- `false` ← (default)

- `true`

format

string

Format of the built image.

Choices:

- `"docker"`

- `"oci"` ← (default)

rm

boolean

Remove intermediate containers after a successful build

Choices:

- `false`

- `true` ← (default)

target string | Specify the target build stage to build.
volume list / elements=string | Specify multiple volume / mount options to mount one or more mounts to a container.
ca_cert_dir path | Path to directory containing TLS certificates and keys to use.
executable string | Path to `podman` executable if it is not in the `$PATH` on the machine running `podman`. Default: `"podman"`

force

boolean

Whether or not to force push or pull an image.

When building, force the build even if the image already exists.

Choices:

- `false` ← (default)

- `true`

name string / required | Name of the image to pull, push, or delete. It may contain a tag using the format `image:tag`.
password string | Password to use when authenticating to remote registries.
path string | Path to the build context directory.
platform string | Platform for the container image (e.g. `linux/amd64`, `linux/arm64`). Specify the platform for selecting the image when pulling or building. Mutually exclusive with `arch`.

pull

boolean

Whether or not to pull the image.

Choices:

- `false`

- `true` ← (default)

pull_extra_args string | Extra arguments to pass to the pull command.

push

boolean

Whether or not to push an image.

Choices:

- `false` ← (default)

- `true`

push_args dictionary | Arguments that control pushing images. Default: `{}`

compress

boolean

Compress tarball image layers when pushing to a directory using the ‘dir’ transport.

Choices:

- `false`

- `true`

dest aliases: destination string | Path or URL where image will be pushed.
extra_args string | Extra args to pass to push, if executed. Does not idempotently check for new push args.

format

string

Manifest type to use when pushing an image using the ‘dir’ transport (default is manifest type of source)

Choices:

- `"oci"`

- `"v2s1"`

- `"v2s2"`

remove_signatures

boolean

Discard any pre-existing signatures in the image

Choices:

- `false`

- `true`

sign_by string | Path to a key file to use to sign the image.
ssh string | SSH options to use when pushing images with SCP transport.

transport

string

Transport to use when pushing in image. If no transport is set, will attempt to push to a remote registry

Choices:

- `"dir"`

- `"docker-archive"`

- `"docker-daemon"`

- `"oci-archive"`

- `"ostree"`

- `"docker"`

- `"scp"`

quadlet_dir path | Path to the directory to write quadlet file in. By default, it will be set as `/etc/containers/systemd/` for root user, `~/.config/containers/systemd/` for non-root users.

quadlet_file_mode

any

The permissions of the quadlet file.

The `quadlet_file_mode` can be specified as octal numbers or as a symbolic mode (for example, `u+rwx` or `u=rw,g=r,o=r`). For octal numbers format, you must either add a leading zero so that Ansible’s YAML parser knows it is an octal number (like `0644` or `01777`) or quote it (like `'644'` or `'1777'`) so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results.

If `quadlet_file_mode` is not specified and the quadlet file does not exist, the default `'0640'` mask will be used when setting the mode for the newly created file.

If `quadlet_file_mode` is not specified and the quadlet file does exist, the mode of the existing file will be used.

Specifying `quadlet_file_mode` is the best way to ensure files are created with the correct permissions.

quadlet_filename string | Name of quadlet file to write. By default it takes image name without prefixes and tags.
quadlet_options list / elements=string | Options for the quadlet file. Provide missing in usual network args options as a list of lines to add.

state

string

Whether an image should be present, absent, or built.

Choices:

- `"present"` ← (default)

- `"absent"`

- `"build"`

- `"quadlet"`

tag string | Tag of the image to pull, push, or delete. Default: `"latest"`
username string | username to use when authenticating to remote registries.

validate_certs

aliases: tlsverify, tls_verify

boolean

Require HTTPS and validate certificates when pulling or pushing. Also used during build if a pull or push is necessary.

Choices:

- `false`

- `true`

## Examples

    - name: Pull an image
      containers.podman.podman_image:
        name: quay.io/bitnami/wildfly

    - name: Remove an image
      containers.podman.podman_image:
        name: quay.io/bitnami/wildfly
        state: absent

    - name: Remove an image with image id
      containers.podman.podman_image:
        name: 0e901e68141f
        state: absent

    - name: Pull a specific version of an image
      containers.podman.podman_image:
        name: redis
        tag: 4

    - name: Build a basic OCI image
      containers.podman.podman_image:
        name: nginx
        path: /path/to/build/dir

    - name: Build a basic OCI image with advanced parameters
      containers.podman.podman_image:
        name: nginx
        path: /path/to/build/dir
        build:
          cache: no
          force_rm: true
          format: oci
          annotation:
            app: nginx
            function: proxy
            info: Load balancer for my cool app
          extra_args: "--build-arg KEY=value"

    - name: Build a Docker formatted image
      containers.podman.podman_image:
        name: nginx
        path: /path/to/build/dir
        build:
          format: docker

    - name: Build and push an image using existing credentials
      containers.podman.podman_image:
        name: nginx
        path: /path/to/build/dir
        push: true
        push_args:
          dest: quay.io/acme

    - name: Build and push an image using an auth file
      containers.podman.podman_image:
        name: nginx
        push: true
        auth_file: /etc/containers/auth.json
        push_args:
          dest: quay.io/acme

    - name: Build and push an image using username and password
      containers.podman.podman_image:
        name: nginx
        push: true
        username: bugs
        password: "{{ vault_registry_password }}"
        push_args:
          dest: quay.io/acme

    - name: Build and push an image to multiple registries
      containers.podman.podman_image:
        name: "{{ item }}"
        path: /path/to/build/dir
        push: true
        auth_file: /etc/containers/auth.json
      loop:
        - quay.io/acme/nginx
        - docker.io/acme/nginx

    - name: Build and push an image to multiple registries with separate parameters
      containers.podman.podman_image:
        name: "{{ item.name }}"
        tag: "{{ item.tag }}"
        path: /path/to/build/dir
        push: true
        auth_file: /etc/containers/auth.json
        push_args:
          dest: "{{ item.dest }}"
      loop:
        - name: nginx
          tag: 4
          dest: docker.io/acme

        - name: nginx
          tag: 3
          dest: docker.io/acme

    - name: Push image to a remote host via scp transport
      containers.podman.podman_image:
        name: testimage
        pull: false
        push: true
        push_args:
          dest: user@server
          transport: scp

    - name: Pull an image for a specific CPU architecture
      containers.podman.podman_image:
        name: nginx
        arch: amd64

    - name: Pull an image for a specific platform (e.g. x86 on M-series Mac)
      containers.podman.podman_image:
        name: nginx
        platform: linux/amd64

    - name: Build a container from file inline
      containers.podman.podman_image:
        name: mycustom_image
        state: build
        build:
          container_file: |-
            FROM alpine:latest
            CMD echo "Hello, World!"

    - name: Create a quadlet file for an image
      containers.podman.podman_image:
        name: docker.io/library/alpine:latest
        state: quadlet
        quadlet_dir: /etc/containers/systemd
        quadlet_filename: alpine-latest
        quadlet_file_mode: '0640'
        quadlet_options:
          - Variant=arm/v7
          - |
            [Install]
            WantedBy=default.target

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Description
--- | ---

image

dictionary

Image inspection results for the image that was pulled, pushed, or built.

Returned: success

Sample: `[{"Annotations": {}, "Architecture": "amd64", "Author": "", "Comment": "", "Config": {"ArgsEscaped": true, "Cmd": ["/bin/sh"], "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"]}, "Created": "2019-03-07T22:19:53.447205048Z", "Digest": "sha256:8421d9a84432575381bfabd248f1eb56f3aa21d9d7cd2511583c68c9b7511d10", "GraphDriver": {"Data": {"UpperDir": "/home/user/.local/share/containers/storage/overlay/3fc6.../diff", "WorkDir": "/home/user/.local/share/containers/storage/overlay/3fc6.../work"}, "Name": "overlay"}, "History": [{"created": "2019-03-07T22:19:53.313789681Z", "created_by": "/bin/sh -c #(nop) ADD file:aa17928... in / "}, {"created": "2019-03-07T22:19:53.447205048Z", "created_by": "/bin/sh -c #(nop) CMD [\"/bin/sh\"]", "empty_layer": true}], "Id": "6d1ef012b5674ad8a127ecfa9b5e6f5178d171b90ee462846974177fd9bdd39f", "Labels": null, "ManifestType": "application/vnd.docker.distribution.manifest.v2+json", "NamesHistory": ["docker.io/library/alpine:3.7"], "Os": "linux", "Parent": "", "RepoDigests": ["docker.io/library/alpine@sha256:8421...", "docker.io/library/alpine@sha256:9225..."], "RepoTags": ["docker.io/library/alpine:3.7"], "RootFS": {"Layers": ["sha256:3fc6..."], "Type": "layers"}, "Size": 4467084, "User": "", "Version": "18.06.1-ce", "VirtualSize": 4467084}]`

### Authors

- Sagi Shnaidman (@sshnaidm)

### Collection links

- Issue Tracker
- Repository (Sources)