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

Note

This plugin is part of the containers.podman collection (version 1.10.1).

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

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

- Synopsis

- Parameters

- Examples

- Return Values

## Synopsis

- Build, pull, or push images using Podman.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
auth_file path |  | Path to file containing authorization credentials to the remote registry. aliases: authfile
build dictionary | Default: {} | Arguments that control image build. aliases: build_args, buildargs
| annotation dictionary |  | Dictionary of key=value pairs to add to the image. Only works with OCI images. Ignored for Docker containers.
| cache boolean | Choices: no yes ← | Whether or not to use cached layers when building an image
| 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.
| force_rm boolean | Choices: no ← yes | Always remove intermediate containers after a build, even if the build is unsuccessful.
| format string | Choices: docker oci ← | Format of the built image.
| rm boolean | Choices: no yes ← | Remove intermediate containers after a successful 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 | Default: "podman" | Path to `podman` executable if it is not in the `$PATH` on the machine running `podman`.
force boolean | Choices: no ← yes | Whether or not to force push or pull an image. When building, force the build even if the image already exists.
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.
pull boolean | Choices: no yes ← | Whether or not to pull the image.
push boolean | Choices: no ← yes | Whether or not to push an image.
push_args dictionary | Default: {} | Arguments that control pushing images.
| compress boolean | Choices: no yes | Compress tarball image layers when pushing to a directory using the 'dir' transport.
| dest string |  | Path or URL where image will be pushed. aliases: destination
| format string | Choices: oci v2s1 v2s2 | Manifest type to use when pushing an image using the 'dir' transport (default is manifest type of source).
| remove_signatures boolean | Choices: no yes | Discard any pre-existing signatures in the image
| sign_by string |  | Path to a key file to use to sign the image.
| transport string | Choices: dir docker-archive docker-daemon oci-archive ostree | Transport to use when pushing in image. If no transport is set, will attempt to push to a remote registry.
state string | Choices: present ← absent build | Whether an image should be present, absent, or built.
tag string | Default: "latest" | Tag of the image to pull, push, or delete.
username string |  | username to use when authenticating to remote registries.
validate_certs boolean | Choices: no yes | Require HTTPS and validate certificates when pulling or pushing. Also used during build if a pull or push is necessary. aliases: tlsverify, tls_verify

## 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: yes
          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: yes
        push_args:
          dest: quay.io/acme

    - name: Build and push an image using an auth file
      containers.podman.podman_image:
        name: nginx
        push: yes
        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: yes
        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: yes
        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: yes
        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

## Return Values

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

Key | Returned | Description
--- | --- | ---
image dictionary | success | Image inspection results for the image that was pulled, pushed, or built. Sample: [{'Annotations': {}, 'Architecture': 'amd64', 'Author': '', 'Comment': 'from Bitnami with love', 'ContainerConfig': {'Cmd': ['/run.sh'], 'Entrypoint': ['/app-entrypoint.sh'], 'Env': ['PATH=/opt/bitnami/java/bin:/opt/bitnami/wildfly/bin:/opt/bitnami/nami/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', 'IMAGE_OS=debian-9', 'NAMI_VERSION=1.0.0-1', 'GPG_KEY_SERVERS_LIST=ha.pool.sks-keyservers.net', 'TINI_VERSION=v0.13.2', 'TINI_GPG_KEY=595E85A6B1B4779EA4DAAEC70B588DFF0527A9B7', 'GOSU_VERSION=1.10', 'GOSU_GPG_KEY=B42F6819007F00F88E364FD4036A9C25BF357DD4', 'BITNAMI_IMAGE_VERSION=16.0.0-debian-9-r27', 'BITNAMI_PKG_CHMOD=-R g+rwX', 'BITNAMI_PKG_EXTRA_DIRS=/home/wildfly', 'HOME=/', 'BITNAMI_APP_NAME=wildfly', 'NAMI_PREFIX=/.nami', 'WILDFLY_HOME=/home/wildfly', 'WILDFLY_JAVA_HOME=', 'WILDFLY_JAVA_OPTS=', 'WILDFLY_MANAGEMENT_HTTP_PORT_NUMBER=9990', 'WILDFLY_PASSWORD=bitnami', 'WILDFLY_PUBLIC_CONSOLE=true', 'WILDFLY_SERVER_AJP_PORT_NUMBER=8009', 'WILDFLY_SERVER_HTTP_PORT_NUMBER=8080', 'WILDFLY_SERVER_INTERFACE=0.0.0.0', 'WILDFLY_USERNAME=user', 'WILDFLY_WILDFLY_HOME=/home/wildfly', 'WILDFLY_WILDFLY_OPTS=-Dwildfly.as.deployment.ondemand=false'], 'ExposedPorts': {'8080/tcp': {}, '9990/tcp': {}}, 'Labels': {'maintainer': 'Bitnami <containers@bitnami.com>'}, 'User': '1001'}, 'Created': '2019-04-10T05:48:03.553887623Z', 'Digest': 'sha256:5a8ab28e314c2222de3feaf6dac94a0436a37fc08979d2722c99d2bef2619a9b', 'GraphDriver': {'Data': {'LowerDir': '/var/lib/containers/storage/overlay/142c1beadf1bb09fbd929465ec98c9dca3256638220450efb4214727d0d0680e/diff:/var/lib/containers/s', 'MergedDir': '/var/lib/containers/storage/overlay/9aa10191f5bddb59e28508e721fdeb43505e5b395845fa99723ed787878dbfea/merged', 'UpperDir': '/var/lib/containers/storage/overlay/9aa10191f5bddb59e28508e721fdeb43505e5b395845fa99723ed787878dbfea/diff', 'WorkDir': '/var/lib/containers/storage/overlay/9aa10191f5bddb59e28508e721fdeb43505e5b395845fa99723ed787878dbfea/work'}, 'Name': 'overlay'}, 'History': [{'comment': 'from Bitnami with love', 'created': '2019-04-09T22:27:40.659377677Z'}, {'created': '2019-04-09T22:38:53.86336555Z', 'created_by': '/bin/sh -c #(nop) LABEL maintainer=Bitnami <containers@bitnami.com>', 'empty_layer': True}, {'created': '2019-04-09T22:38:54.022778765Z', 'created_by': '/bin/sh -c #(nop) ENV IMAGE_OS=debian-9', 'empty_layer': True}], 'Id': 'ace34da54e4af2145e1ad277005adb235a214e4dfe1114c2db9ab460b840f785', 'Labels': {'maintainer': 'Bitnami <containers@bitnami.com>'}, 'ManifestType': 'application/vnd.docker.distribution.manifest.v1+prettyjws', 'Os': 'linux', 'Parent': '', 'RepoDigests': ['quay.io/bitnami/wildfly@sha256:5a8ab28e314c2222de3feaf6dac94a0436a37fc08979d2722c99d2bef2619a9b'], 'RepoTags': ['quay.io/bitnami/wildfly:latest'], 'RootFS': {'Layers': ['', '', '', '', '', '', '', '', '', '', '', ''], 'Type': 'layers'}, 'Size': 466180019, 'User': '1001', 'Version': '18.09.3', 'VirtualSize': 466180019}]

### Authors

- Sam Doran (@samdoran)