# 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.
dns_search 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)

### Collection links

- Issue Tracker
- Repository (Sources)