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

Note

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

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

Comments

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.

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:

  • no

  • yes ← (default)

extra_args

string

Extra args to pass to build, if executed. Does not idempotently check for new build args.

force_rm

boolean

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

Choices:

  • no ← (default)

  • yes

format

string

Format of the built image.

Choices:

  • docker

  • oci ← (default)

rm

boolean

Remove intermediate containers after a successful build

Choices:

  • no

  • yes ← (default)

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:

  • no ← (default)

  • yes

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

Whether or not to pull the image.

Choices:

  • no

  • yes ← (default)

push

boolean

Whether or not to push an image.

Choices:

  • no ← (default)

  • yes

push_args

dictionary

Arguments that control pushing images.

compress

boolean

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

Choices:

  • no

  • yes

dest

aliases: destination

string

Path or URL where image will be pushed.

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:

  • no

  • yes

sign_by

string

Path to a key file to use to sign the image.

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

state

string

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

Choices:

  • present ← (default)

  • absent

  • build

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:

  • no

  • yes

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

Description

image

dictionary

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

Returned: success

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 \u003ccontainers@bitnami.com\u003e”}, “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 \u003ccontainers@bitnami.com\u003e”, “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 \u003ccontainers@bitnami.com\u003e”}, “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)