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

Note

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

Collection links

• Issue Tracker
• Repository (Sources)