containers.podman.podman_quadlet module – Install or remove Podman Quadlets

Note

This module is part of the containers.podman collection (version 1.21.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. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: containers.podman.podman_quadlet.

Synopsis

  • Install or remove Podman Quadlets using podman quadlet install and podman quadlet rm.

  • Creation of quadlet files is handled by resource modules with state=quadlet.

  • Updates are handled by removing the existing quadlet and installing the new one.

  • Idempotency for ordinary local files and directories uses content comparison.

  • For remote URLs, the module always reinstalls to ensure the host matches the configured source (reports changed=true).

  • .quadlets files are passed directly to Podman 6.0+ and always report changed=true. Generated units removed from a later version of the file must be removed explicitly with state=absent.

  • Directory installs on Podman 6.0+ support nested subdirectories.

Requirements

The below requirements are needed on the host that executes this module.

  • podman

Parameters

Parameter

Comments

all

boolean

Remove all installed quadlets when state=absent (maps to podman quadlet rm --all).

Choices:

  • false ← (default)

  • 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.

debug

boolean

Return additional information which can be helpful for investigations.

Choices:

  • false ← (default)

  • true

executable

string

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

Default: "podman"

files

list / elements=string

Additional non-quadlet files or URLs to install along with the primary src (quadlet application use-case).

Passed positionally to podman quadlet install after src when supported.

On Podman 6.0 or later, local non-quadlet files require a directory src. The module fails with an explanatory message when they are supplied with a file or URL src.

Content changes to local files are detected. Previously installed files that are later omitted from this option must be removed explicitly with state=absent.

If any file is a URL, the entire install always reports changed=true since remote content cannot be verified.

force

boolean

Force removal when state=absent (maps to podman quadlet rm --force).

Choices:

  • false

  • true ← (default)

name

list / elements=string

Name (filename without path) of an installed quadlet to remove when state=absent.

If the name does not include the type suffix (e.g. .container), the module will attempt to find a matching quadlet file. When exactly one match is found it is used; when multiple suffixes match, all are removed.

quadlet_dir

path

Override the target quadlet directory used for idempotency checks.

By default it follows Podman defaults.

/etc/containers/systemd/ for root, ~/.config/containers/systemd/ for non-root.

Note this is used for content comparison only and is not passed to Podman.

reload_systemd

boolean

Control systemd reload behavior in Podman. When true, pass --reload-systemd.

When false, pass --reload-systemd=false.

Choices:

  • false

  • true ← (default)

src

string

Path to a quadlet file, a directory containing a quadlet application, or a URL to install when state=present.

Except for .quadlets, local files and directories provide idempotency through content comparison.

For remote URLs, the module always installs fresh and reports changed=true since content cannot be verified.

Directory installs on Podman 6.0+ support nested subdirectories.

Directory installs on Podman < 6.0 require a flat directory (no subdirectories).

state

string

Desired state of quadlet(s).

Choices:

  • "present" ← (default)

  • "absent"

Examples

- name: Install a simple quadlet file
  containers.podman.podman_quadlet:
    state: present
    src: /tmp/myapp.container

- name: Install a directory application with additional config files
  containers.podman.podman_quadlet:
    state: present
    src: /tmp/myapp_dir/
    files:
      - /tmp/myapp.conf
      - /tmp/secrets.env

- name: Install quadlet application from a directory
  containers.podman.podman_quadlet:
    state: present
    src: /tmp/myapp_dir/

- name: Install with custom quadlet directory (e.g. for system-wide install)
  containers.podman.podman_quadlet:
    state: present
    src: /tmp/myapp.container
    quadlet_dir: /etc/containers/systemd
  become: true

- name: Remove a specific quadlet
  containers.podman.podman_quadlet:
    state: absent
    name:
      - myapp.container

- name: Remove multiple quadlets
  containers.podman.podman_quadlet:
    state: absent
    name:
      - myapp.container
      - database.container
      - cache.container

- name: Remove quadlet without suffix (module resolves to .container, .pod, etc.)
  containers.podman.podman_quadlet:
    state: absent
    name:
      - myapp

- name: Remove all quadlets (use with caution)
  containers.podman.podman_quadlet:
    state: absent
    all: true

- name: Install quadlet from a URL (always reports changed=true)
  containers.podman.podman_quadlet:
    state: present
    src: https://example.com/myapp.container

- name: Install multi-quadlet application from .quadlets file (Podman 6.0+)
  containers.podman.podman_quadlet:
    state: present
    src: /tmp/webapp.quadlets

Return Values

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

Key

Description

_debug_installed_files

list / elements=string

List of currently installed files detected for content comparison

Returned: when debug=true and state=present and the source supports content comparison

_debug_spec

dictionary

Internal specification used for idempotency detection

Returned: when debug=true and state=present

desired_files

list / elements=string

List of filenames that should be installed

Returned: success

marker_name

string

Podman tracking filename, when applicable

Returned: success

mode

string

Install mode (dir_app, quadlets_file, single_file, or remote)

Returned: success

removal_target

string

What will be passed to ‘podman quadlet rm’ for updates

Returned: success

actions

list / elements=string

Human-readable actions performed

Returned: always

changed

boolean

Whether any change was made

Returned: always

podman_actions

list / elements=string

Executed podman command lines

Returned: always

quadlets

list / elements=string

List of affected quadlets with name, path, and scope

Returned: always

stderr

string

podman stderr

Returned: when debug=true

stdout

string

podman stdout

Returned: when debug=true

Authors

  • Sagi Shnaidman (@sshnaidm)