containers.podman.podman_image module – Pull images for use by podman
Note
This module is part of the containers.podman collection (version 1.18.0).
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. |
|
SSH options to use when pushing images with SCP transport. |
|
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: Push image to a remote host via scp transport
containers.podman.podman_image:
name: testimage
pull: false
push: true
push_args:
dest: user@server
transport: scp
- 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: |