podman_image – Pull images for use by podman

New in version 2.8.

Synopsis
Parameters
Examples
Return Values
Status

Synopsis

Build, pull, or push images using Podman.

Parameters

Parameter		Choices/Defaults	Comments
auth_file -			Path to file containing authorization credentials to the remote registry aliases: authfile
build -			Arguments that control image build. aliases: build_args, buildargs
	annotation string		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
	force_rm boolean	Choices: no ← yes	Always remove intermediate containers after a build, even if the build is unsuccessful.
	format -	Choices: docker oci ←	Format of the built image.
	rm boolean	Choices: no yes ←	Remove intermediate containers after a successful build
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 -			Whether or not to force push or pull an image. When building, force the build even if the image already exists.
name - / 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 -			Path to directory containing the build file.
pull -		Default: "yes"	Whether or not to pull the image.
push -		Default: "no"	Whether or not to push an image.
push_args -			Arguments that control pushing images.
	compress boolean	Choices: no yes	Compress tarball image layers when pushing to a directory using the 'dir' transport.
	dest -		Path or URL where image will be pushed.
	format -	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 -		Path to a key file to use to sign the image.
	transport -	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 -		Choices: present ← absent build	Whether an image should be present, absent, or built.
tag -		Default: "latest"	Tag of the image to pull, push, or delete.
username string			username to use when authenticating to remote registries.
validate_certs -		Default: "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
  podman_image:
    name: quay.io/bitnami/wildfly

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

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

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

- name: Build a basic OCI image with advanced parameters
  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
  podman_image:
    name: nginx
    path: /path/to/build/dir
    build:
      format: docker

- name: Build and push an image using existing credentials
  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
  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
  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
  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
  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/wildfly@sha256:5a8ab28e314c2222de3feaf6dac94a0436a37fc08979d2722c99d2bef2619a9b'], 'RepoTags': ['quay.io/bitnami/wildfly:latest'], 'RootFS': {'Layers': ['', '', '', '', '', '', '', '', '', '', '', ''], 'Type': 'layers'}, 'Size': 466180019, 'User': '1001', 'Version': '18.09.3', 'VirtualSize': 466180019}]

Status

This module is not guaranteed to have a backwards compatible interface. [preview]
This module is maintained by the Ansible Community. [community]

Authors

Sam Doran (@samdoran)

Hint

If you notice any issues in this documentation you can edit this document to improve it.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/podman_image_module.html