containers.podman.podman_image module – Pull images for use by podman
Note
This module is part of the containers.podman collection (version 1.16.2).
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 |
|---|---|
CPU architecture for the container image |
|
Path to file containing authorization credentials to the remote registry. |
|
Arguments that control image build. Default: |
|
Dictionary of key=value pairs to add to the image. Only works with OCI images. Ignored for Docker containers. |
|
Whether or not to use cached layers when building an image Choices:
|
|
Content of the Containerfile to use for building the image. Mutually exclusive with the |
|
Extra args to pass to build, if executed. Does not idempotently check for new build args. |
|
Path to the Containerfile if it is not in the build context directory. Mutually exclusive with the |
|
Always remove intermediate containers after a build, even if the build is unsuccessful. Choices:
|
|
Format of the built image. Choices:
|
|
Remove intermediate containers after a successful build Choices:
|
|
Specify the target build stage to build. |
|
Specify multiple volume / mount options to mount one or more mounts to a container. |
|
Path to directory containing TLS certificates and keys to use. |
|
Path to Default: |
|
Whether or not to force push or pull an image. When building, force the build even if the image already exists. Choices:
|
|
Name of the image to pull, push, or delete. It may contain a tag using the format |
|
Password to use when authenticating to remote registries. |
|
Path to the build context directory. |
|
Whether or not to pull the image. Choices:
|
|
Extra arguments to pass to the pull command. |
|
Whether or not to push an image. Choices:
|
|
Arguments that control pushing images. Default: |
|
Compress tarball image layers when pushing to a directory using the ‘dir’ transport. Choices:
|
|
Path or URL where image will be pushed. |
|
Extra args to pass to push, if executed. Does not idempotently check for new push args. |
|
Manifest type to use when pushing an image using the ‘dir’ transport (default is manifest type of source) Choices:
|
|
Discard any pre-existing signatures in the image Choices:
|
|
Path to a key file to use to sign the image. |
|
Transport to use when pushing in image. If no transport is set, will attempt to push to a remote registry Choices:
|
|
Path to the directory to write quadlet file in. By default, it will be set as |
|
The permissions of the quadlet file. The If If Specifying |
|
Name of quadlet file to write. By default it takes image name without prefixes and tags. |
|
Options for the quadlet file. Provide missing in usual network args options as a list of lines to add. |
|
Whether an image should be present, absent, or built. Choices:
|
|
Tag of the image to pull, push, or delete. Default: |
|
username to use when authenticating to remote registries. |
|
Require HTTPS and validate certificates when pulling or pushing. Also used during build if a pull or push is necessary. Choices:
|
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_file_mode: '0640'
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 inspection results for the image that was pulled, pushed, or built. Returned: success Sample: |