containers.podman.podman_quadlet_build module – Build images for use by Podman Quadlets

Note

This module is part of the containers.podman collection (version 1.20.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_quadlet_build.

Synopsis

  • Build images using Quadlet.

Parameters

Parameter

Comments

annotation

dictionary

Dictionary of key=value pairs to add to the image. Only works with OCI images. Ignored for Docker containers.

arch

string

CPU architecture for the container image

authfile

aliases: auth_file

path

Path to file containing authorization credentials to the remote registry.

build_args

aliases: buildargs

dictionary

Dictionary of key=value pairs to add as build argument.

ca_cert_dir

path

Path to directory containing TLS certificates and keys to use.

cache

boolean

Whether or not to use cached layers when building an image

Choices:

  • false

  • true

cmd_args

list / elements=string

Extra global arguments to pass to the podman command (e.g., --log-level=debug).

These are placed after the executable and before the subcommand.

dns

list / elements=string

Set custom DNS servers in the /etc/resolv.conf file that will be shared between all containers in the pod. A special option, “none” is allowed which disables creation of /etc/resolv.conf for the pod.

dns_opt

aliases: dns_option

list / elements=string

Set custom DNS options in the /etc/resolv.conf file that will be shared between all containers in the pod.

list / elements=string

Set custom DNS search domains in the /etc/resolv.conf file that will be shared between all containers in the pod.

env

dictionary

Dictionary of key=value pairs to add as environment variable.

executable

string

Path to podman executable if it is not in the $PATH on the machine running podman.

Default: "podman"

file

path

Path to the Containerfile if it is not in the build context directory.

force_rm

boolean

Always remove intermediate containers after a build, even if the build is unsuccessful.

Choices:

  • false

  • true

group_add

aliases: groups

list / elements=string

Add additional groups to run as

ignore_file

aliases: ignorefile

path

Path to an alternate .containerignore file to use when building the image.

labels

dictionary

Labels to set on the image.

name

string / required

Name of the image to build. It may contain a tag using the format image:tag.

network

aliases: net, network_mode

list / elements=string

List of the names of CNI networks the build should join during the RUN instructions.

password

string

Password to use when authenticating to remote registries.

pull

string

Pull image policy. The default is ‘missing’.

Choices:

  • "missing"

  • "always"

  • "never"

  • "newer"

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_file_mode

any

The permissions of the quadlet file.

The quadlet_file_mode can be specified as octal numbers or as a symbolic mode (for example, u+rwx or u=rw,g=r,o=r). For octal numbers format, you must either add a leading zero so that Ansible’s YAML parser knows it is an octal number (like 0644 or 01777) or quote it (like '644' or '1777') so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results.

If quadlet_file_mode is not specified and the quadlet file does not exist, the default '0640' mask will be used when setting the mode for the newly created file.

If quadlet_file_mode is not specified and the quadlet file does exist, the mode of the existing file will be used.

Specifying quadlet_file_mode is the best way to ensure files are created with the correct permissions.

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 build args options as a list of lines to add.

retry

integer

Number of times to retry pulling or pushing images between the registry and local storage in case of failure. Default is 3.

retry_delay

aliases: retrydelay

string

Duration of delay between retry attempts when pulling or pushing images between the registry and local storage in case of failure.

secret

list / elements=string

Pass secret information used in Containerfile build stages in a safe way. Generally has the form secret[,opt=opt ...]. Can be specified multiple times.

set_working_directory

aliases: setworkingdirectory

string

Provide context (a working directory) to podman build.

target

string

Specify the target build stage to build.

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

variant

string

Override the default architecture variant of the container image to be built.

volume

list / elements=string

Specify multiple volume / mount options to mount one or more mounts to a container.

Examples

- name: Build an image
  containers.podman.podman_quadlet_build:
    name: myimage
    file: /tmp/Containerfile

- name: Build an image
  containers.podman.podman_quadlet_build:
    name: myimage
    set_working_directory: /tmp/context

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

changed

boolean

Whether any change was made

Returned: always

Authors

  • Benjamin Vouillaume (@BenjaminVouillaume)