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

Note

This module is part of the containers.podman collection (version 1.19.0).

You might already have this collection installed if you are using the ansible package. 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 local sources uses Podman’s .app/.asset manifest files and direct content comparison.

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

  • Supports .quadlets files containing multiple quadlet sections separated by --- delimiter (requires Podman 6.0+).

  • Each section in a .quadlets file must include a # FileName=<name> comment to specify the output filename.

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.

For local files, full idempotency is provided.

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.

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.

For local files and directories, full idempotency is provided (content comparison).

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

Directory installs support only top-level files; nested subdirectories will cause an error.

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 quadlet application with additional config files
  containers.podman.podman_quadlet:
    state: present
    src: /tmp/myapp.container
    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 from Podman manifests

Returned: when debug=true and state=present and mode is not remote

_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

The .app or .asset marker filename used by Podman

Returned: success

mode

string

Install mode (dir_app, quadlets_app, 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)