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

Note

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

You might already have this collection installed if you are using the ansible package. 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 Choices/Defaults Comments
auth_file
path
Path to file containing authorization credentials to the remote registry.

aliases: authfile
build
dictionary
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.
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 directory containing the build file.
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
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: 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

- 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 <[email protected]>'}, '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 <[email protected]>', '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 <[email protected]>'}, 'ManifestType': 'application/vnd.docker.distribution.manifest.v1+prettyjws', 'Os': 'linux', 'Parent': '', 'RepoDigests': ['quay.io/bitnami/[email protected]: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)