containers.podman.podman_image module – Pull images for use by podman¶
Note
This module is part of the containers.podman collection (version 1.11.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: 
 | |
| 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. | |
| 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: 
 | |
| 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. | |
| 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: 
 | |
| 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
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:  |