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

Note

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

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
Parameters
Examples
Return Values

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.
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.
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"` `"docker-archive"` `"docker-daemon"` `"oci-archive"` `"ostree"`
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_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: Pull an image for a specific CPU architecture
  containers.podman.podman_image:
    name: nginx
    arch: 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_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}]

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

Sam Doran (@samdoran)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/containers/podman/podman_image_module.html