podman_quadlet
podman_quadlet installs one Quadlet file on the node: a small file in
systemd's unit syntax that describes a container, or a volume, network, or
pod. A pod is a group of containers that share a network.
Podman runs containers without a daemon. At each systemd reload,
Podman's generator turns every Quadlet file into a systemd service. The
container then is an ordinary systemd service: systemd starts it at boot,
restarts it, and stops it.
- podman_quadlet:
name: shop-web.container
content: |
[Container]
ContainerName=shop-web
Image=registry.example.com/shop/web:2.4
[Install]
WantedBy=multi-user.target
So Podman needs less from MMX than Docker does. Three things do the work on a node:
podman_imagepulls one image from a registry (the server that images are pulled from) into the node's image store.podman_quadletinstalls the Quadlet file and reloads systemd.- The
systemd_servicetask that you already know starts the generated service and restarts it when something it runs with has changed, with the same records as for any service.
wait_for has a form that waits until a Podman container is healthy; see
Wait until a Podman container is healthy.
The module runs the node's installed podman command.
Quadlet needs Podman 4.4 or newer. MMX does not drive
podman compose: a project that has a Compose file and wants Podman
translates each service into a Quadlet file. Docker's containers are written
with docker_compose_project.
Set up
This section is also the setup of podman_image.
Install Podman first with a package task. MMX has no module that installs
Podman. On a node without the podman program, a podman_image task and a
podman_quadlet task that installs a Quadlet file fail with a message that
says to install Podman, and a dryrun reports the task not_checked. A removal needs
podman only to delete a volume or a network: the removal of a .network
file, or of a .volume file with state: volume_and_its_data_removed, when
the file or MMX's record names that volume or network. Every other removal
works without podman. Debian 12 ships Podman 4.3, older than 4.4, so
podman_quadlet fails there and names both versions; podman_image works.
On Debian 12, write the container's unit file yourself with systemd_unit,
with ExecStart=/usr/bin/podman run ..., and start it with
systemd_service. The docker_image page
shows a systemd_unit task that runs docker run, followed by a
systemd_service task. Use podman_image to supply the Podman image.
A complete node task list for a Rocky Linux or AlmaLinux server,
which the container shop-web of
Run a container from a Quadlet file
follows:
- dnf_package:
packages:
- {name: podman, version: newest_when_first_installed}
- {name: skopeo, version: newest_when_first_installed}
- task_block:
id: podman_registries
changes:
- file:
path: /etc/containers/registries.conf.d/50-shop.conf
permissions_mode: "0644"
content: |
[[registry]]
location = "registry.example.com"
blocked = false
- task_block:
id: podman_image_cleanup
changes:
- systemd_unit:
name: podman-image-cleanup.service
content: |
[Service]
Type=oneshot
ExecStart=/usr/bin/podman image prune --all --force --filter until=168h
- systemd_unit:
name: podman-image-cleanup.timer
content: |
[Timer]
OnCalendar=Sun 04:00
Persistent=true
[Install]
WantedBy=timers.target
activate:
- systemd_service:
name: podman-image-cleanup.timer
state: running
start_at_boot: true
Podman has no daemon to configure or start. Its settings are drop-in files
under /etc/containers/, written with file. skopeo is there for the
dryrun of a podman_image task with pull_image: always. The cleanup timer
deletes, every Sunday at 04:00, the images in the system's store that no
container uses and that are older than seven days. Each ordinary account
that runs containers has its own image store. To clean it, add the same two
systemd_unit tasks and the systemd_service task once more, each with
in_systemd_of_user_account: <account>; that timer runs as the account and
cleans the account's store.
On the Red Hat family, Podman's package requires all the programs that
Podman's features need itself (measured with dnf on Rocky Linux 9 and
AlmaLinux 10); name podman and skopeo there.
On Debian and Ubuntu, name more packages than podman. There, Podman's
package requires only what a container of root needs. The programs for pods,
for the containers of an ordinary account, and for Podman's own networks are
"recommended" packages. apt installs recommended packages by default, but
many servers disable recommended package installation
(APT::Install-Recommends "false").
Some server providers supply operating system images with recommended
packages turned off. The providers' Debian 12 and Debian 13 operating system
images carry
/etc/apt/apt.conf.d/00InstallRecommends containing
APT::Install-Recommends "false". The providers' Ubuntu operating system
images keep apt's default (measured).
apt_package follows the node's own apt settings, and MMX does not force
recommended packages onto a node.
When apt disables recommended packages, installing podman omits the
programs for pods, ordinary accounts' containers, and Podman's networks.
A pod then does not start
(exec: "catatonit": executable file not found), and an ordinary account
cannot run a container (exec: "newuidmap": executable file not found).
Name the packages explicitly, so the listed packages are installed whether
APT::Install-Recommends is true or false:
- when: {equals: ["{{ .node.package_manager }}", apt]}
apt_package:
packages:
- {name: podman, version: newest_when_first_installed}
- {name: skopeo, version: newest_when_first_installed}
- {name: catatonit, version: newest_when_first_installed}
- {name: uidmap, version: newest_when_first_installed}
- {name: slirp4netns, version: newest_when_first_installed}
- {name: dbus-user-session, version: newest_when_first_installed}
- {name: netavark, version: newest_when_first_installed}
- {name: aardvark-dns, version: newest_when_first_installed}
- {name: nftables, version: newest_when_first_installed}
- {name: passt, version: newest_when_first_installed}
| Package | What needs the package |
|---|---|
catatonit |
Pods. |
uidmap |
Containers of an ordinary account. |
slirp4netns, passt |
The network of an ordinary account's containers: slirp4netns with Podman 4 and older, passt with Podman 5. |
dbus-user-session |
Lets an ordinary account's Podman hand its containers to the account's own systemd. Without it, every Podman command of the account warns and falls back to another way. |
netavark, aardvark-dns |
Podman's networks for containers, and the names of the containers on one network. Without them, Podman 4 falls back to older network programs. |
nftables |
The firewall program that netavark runs on Debian 13. |
skopeo |
The dryrun of a podman_image task with pull_image: always, on every distribution. |
The example project examples/podman-host
prepares a server with these tasks, and
examples/deploy-with-podman-quadlet
is the deployment of the next section as a whole project.
Inputs
name(string; required): the Quadlet filename; its ending says what the file declares: .container, .volume, .network, .pod, .kube, .image, or .build; the system's files go to /etc/containers/systemd/, root, 0644content(string; optional): inline text in Quadlet's unit syntax; exactly one of content or template with state: present; keep secret values in a separate private file that the Quadlet file names with EnvironmentFile=template(string; optional): local Go template, relative to the project root, or to the role's directory inside a role; exactly one of content or template with state: presentin_systemd_of_user_account(string; optional): an account other than root: the file goes to<home>/.config/containers/systemd/owned by the account, the container runs as that account under its own systemd, and MMX turns on lingering for the account so that its services start at boot and keep running after logout; the account needs a home directory and ranges of sub-user and sub-group IDsstate(present,file_and_service_removed_named_volumes_kept, orvolume_and_its_data_removed; defaultpresent): file_and_service_removed_named_volumes_kept stops the generated service if it runs, deletes the file, reloads systemd, and for a .network file removes the Podman network; named volumes, images, and mounted directories stay; volume_and_its_data_removed is only for a .volume file and also deletes the named volume with the data in it, also when file_and_service_removed_named_volumes_kept removed the file before; both accept only name, in_systemd_of_user_account, and state
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangereasonvalue.generated_service
What a dryrun reports
Supported; previews the file's contents and writes nothing; the generator's check of a changed file is not checked; reports would_change for an unchanged file that systemd has not read yet; a removal says in reason what it would delete and every service it would stop.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Run a container from a Quadlet file
- selinux_file_context:
path: /etc/shop-web
also_apply_to_everything_inside: true
selinux_type: container_file_t
- directory:
path: /etc/shop-web
permissions_mode: "0755"
- task_block:
id: shop_web
changes:
- file:
path: /etc/shop-web/configuration
permissions_mode: "0644"
content: |
greeting = {{ .vars.shop_web_greeting }}
- podman_image:
image: registry.example.com/shop/web:2.4
pull_image: when_missing
- podman_quadlet:
name: shop-web-data.volume
content: |
[Volume]
VolumeName=shop-web-data
- podman_quadlet:
name: shop-web.container
content: |
[Unit]
Description=Shop web application
[Container]
ContainerName=shop-web
Image=registry.example.com/shop/web:2.4
PublishPort=127.0.0.1:8080:8080
Volume=shop-web-data.volume:/var/lib/shop-web
Volume=/etc/shop-web:/etc/shop-web:ro
HealthCmd=["/usr/local/bin/shop-web", "check-health"]
[Service]
Restart=always
ExecReload=/usr/bin/podman exec shop-web /usr/local/bin/shop-web reload-configuration
[Install]
WantedBy=multi-user.target
activate:
- systemd_service:
name: shop-web.service
state: running
refresh: reload
verify:
- wait_for:
podman_container_is_healthy: shop-web
wait_at_most: 2m
On the node, in order: MMX writes the application's configuration file.
MMX pulls the image if the node does not have the image.
MMX installs the two Quadlet files under /etc/containers/systemd/ and
reloads systemd. Podman's generator makes shop-web-data-volume.service
and shop-web.service. The
systemd_service task starts shop-web.service, which creates the volume and
the container. wait_for waits until the container's own health check reports
healthy. A second run changes nothing.
The volume's file comes before the container's file, which names it; see
the rules for the files. When the configuration file
changes later, the systemd_service task reloads the service with the
ExecReload= line, because the task says refresh: reload; see
What restarts a Podman container.
Containers of an ordinary account
Podman can run a container as an ordinary account, without root:
- user:
name: shop
system: false
home: /home/shop
create_home_directory: true
- task_block:
id: shop_web
changes:
- podman_image:
image: registry.example.com/shop/web:2.4
pull_image: when_missing
in_image_store_of_user_account: shop
- podman_quadlet:
name: shop-web.container
in_systemd_of_user_account: shop
content: |
[Container]
ContainerName=shop-web
Image=registry.example.com/shop/web:2.4
PublishPort=8080:8080
HealthCmd=["/usr/local/bin/shop-web", "check-health"]
[Service]
Restart=always
[Install]
WantedBy=default.target
activate:
- systemd_service:
name: shop-web.service
in_systemd_of_user_account: shop
state: running
verify:
- wait_for:
podman_container_is_healthy: shop-web
podman_container_of_user_account: shop
wait_at_most: 2m
The image goes into the image store of shop, which is separate from
root's. The Quadlet file is installed as
/home/shop/.config/containers/systemd/shop-web.container, owned by shop.
MMX reloads the systemd of the account shop, and the systemd_service task
starts shop-web.service there. The container's process runs as shop.
The account's own systemd says what the account
needs.
Wait until a Podman container is healthy
A container's health check is a command, declared with the container, that Podman runs again and again to learn whether the application inside works.
verify:
- wait_for:
podman_container_is_healthy: shop-web
wait_at_most: 2m
podman_container_is_healthy: <container name> is the Podman form of
wait_for. It waits until Podman reports that container
healthy by the container's own health check, which its Quadlet file declares
with HealthCmd=. The name is the ContainerName= of the Quadlet file.
Without that line Podman names the container systemd- and the file's base
name, such as systemd-shop-web; set ContainerName= so the name in the
playbook is the name on the page.
podman_container_of_user_account: <account> is allowed only with
podman_container_is_healthy and names the account whose container it is.
Without podman_container_of_user_account, MMX looks at the system's
(root's) containers.
- A container that declares no health check fails the task at once, because no answer would ever come.
- When the wait ends without health, the task fails with the container's status and with the exit code and the output of its last health check.
- Like every
wait_for, it useswait_at_most, changes nothing, checks once in a dryrun, and belongs inverify, as the Docker forms do.
Podman calls a container unhealthy only after several failed checks in a
row (HealthRetries=, three by default). Until then a container that was
healthy before still counts as healthy.
Remove a Podman container and its data
Remove the container's file before the volume's file:
- podman_quadlet:
name: shop-web.container
state: file_and_service_removed_named_volumes_kept
- podman_quadlet:
name: shop-web-data.volume
state: volume_and_its_data_removed
The first MMX task stops shop-web.service, so Podman removes the container.
Then MMX deletes shop-web.container and reloads systemd.
The second task deletes the
named volume shop-web-data with the data in it, then its Quadlet file.
Removal says what each state keeps.
To stop a container for other work, such as a backup, and start it again,
use systemd_service with state: stopped and then state: running. The
named volume keeps its data.
How it works
Where the file goes
| Owner of the container | Directory on the node | File owner and mode |
|---|---|---|
| The system (root) | /etc/containers/systemd/ |
root, 0644 |
The account in in_systemd_of_user_account |
<that account's home>/.config/containers/systemd/ |
The account named by in_systemd_of_user_account, 0644 |
MMX creates the directory when it is missing.
The service that Podman generates
The result's value.generated_service holds the name of the service that
Podman makes from the file. By kind of file:
| File | Generated service | What starting the generated service does | First Podman version |
|---|---|---|---|
shop-web.container |
shop-web.service |
Runs the container. | 4.4 |
shop-web-data.volume |
shop-web-data-volume.service |
Creates the named volume if it is missing. | 4.4 |
shop.network |
shop-network.service |
Creates the network if it is missing. | 4.4 |
shop.kube |
shop.service |
Runs the containers a Kubernetes YAML file describes. Install the Kubernetes YAML file with a file task in the podman_quadlet task's node task block. |
4.4 |
shop-web.image |
shop-web-image.service |
Pulls the image. | 4.8 |
shop.pod |
shop-pod.service |
Runs the pod (a group of containers that share a network). | 5.0 |
shop-web.build |
shop-web-build.service |
Builds an image from a Containerfile. | 5.2 |
The versions are those of Podman's manual page of each release. A container
that names a volume, network, pod, image, or build file (as
Volume=shop-web-data.volume above) makes systemd start that file's service
first, so a playbook needs a systemd_service task only for the container,
pod, or kube service.
What podman_quadlet does on each run
- It checks a new file before it installs it. MMX runs Podman's own
generator in its check-only mode on the new file together with the Quadlet
files that are already installed, as
systemd_unitrunssystemd-analyze verify. When the generator makes no service from the new file, the file is not installed, the installed file stays, and the task fails with the generator's message. The file is accepted when the generator prints the service it would make from it, never by the exit code alone. - The service must come from the new file itself. The generator gets three directories and makes a service from the first file of each name that it can read: a copy of the new file, then a stand-in file of the same name that MMX writes, then the installed files. The stand-in carries a mark, so MMX sees which file the service comes from. A new file that the generator cannot read does not pass because a good file of the same name is installed.
- For an account's file, that account runs the generator, as its own systemd does. The copy and the stand-in are in the node task's private directory, which belongs to the account for the check (execution design). The generator waits without end on a file that is not a regular file, such as a named pipe, so MMX ends it after one minute and says so.
- It refuses a file kind that the node's Podman does not know. The task
fails before it writes anything and names the installed version and the
version that the kind needs; a dryrun reports
not_checked. The same holds for Podman older than 4.4. - Unchanged means that the installed file has the same bytes, owner, and mode.
- It reloads systemd after a changed file (the system's, or the account's), after it replaced the file atomically. MMX also checks systemd's own "reload needed" flag on an unchanged file, so a systemd reload that an interrupted run missed is done on the next run.
- With
state: present, it starts, restarts, and stops nothing. That is thesystemd_servicetask's work. - A dryrun shows the file's difference and writes nothing. It reports
the generator's check of a changed file as not checked. For an unchanged
file that systemd has not read yet, it reports
would_change, assystemd_unitdoes, because a run would reload systemd.
Rules for the files
-
Install a file before the file that names it. The container's file in Run a container from a Quadlet file names
shop-web-data.volume. Podman's generator rejects a container file that names a Quadlet file it cannot find, and MMX installs no file that the generator rejects, so the volume's task comes first. Remove a referenced Quadlet file after the Quadlet files that name the referenced file. -
No
start_at_booton the service task. systemd cannot enable a service that Podman's generator made. Whether the container starts at boot is the[Install]section of the Quadlet file:WantedBy=multi-user.targetfor the system,WantedBy=default.targetfor an account. So thesystemd_servicetask for a generated service hasstateand nostart_at_boot. MMX refusesstart_at_bootthere in two places:- When the project loads, for a
systemd_servicetask whose unit is the generated service of apodman_quadlettask among the node tasks of the same fleet stage, in the same systemd, before anything runs. - On the node, for every unit that systemd reports as generated. The
failure names the file that the unit comes from (the unit's
SourcePath), and gives the[Install]advice when that is a Quadlet file.
One kind of generated unit can be enabled: the unit that systemd makes from an
/etc/init.dscript.systemctl enabledelegates enabling the init-script unit to the distribution's own tool. MMX readssystemctl is-enabledfor generated init-script units and managesstart_at_bootas for ordinary units (measured on Debian 13). - When the project loads, for a
-
Keep secret values out of the Quadlet file. Put secret values into a separate private file that the Quadlet file names with
EnvironmentFile=.
What restarts a Podman container
A Quadlet container is a systemd service, so the ordinary records apply
(execution design).
The systemd_service task in activate looks at what the node task block's
changes declare:
| What changed | What the systemd_service task does |
|---|---|
| The container's Quadlet file | Restarts the service, also with refresh: reload. A Quadlet file counts as the service's definition, like a systemd_unit file. |
The image ID from a podman_image task |
Restarts the service, also with refresh: reload. Podman makes the container new at each start, so the restart uses the new image. |
A file written by file, such as the configuration file above |
Applies the task's refresh: restart by default, or reload when the Quadlet file's [Service] section has an ExecReload= line. |
Each of these still happens when a run stopped between the change and the
restart: the next run compares what the service last loaded with what is on
the node, and restarts or reloads once. No shell task is needed for a
mounted file, unlike with Docker Compose, because here systemd and MMX's
service record know the service.
Name in activate each service that must load a change. A changed .volume
or .network file changes nothing on a volume or network that exists;
Podman creates volumes and networks only when the volumes or networks are
missing.
Podman can also update images by itself between MMX runs: a container with
AutoUpdate=registry in its Quadlet file is replaced by Podman's own
podman-auto-update.timer when the image's registry tag refers to a
different image. Enable podman-auto-update.timer with a systemd_service
task. MMX neither prevents nor records Podman's automatic image and
container updates.
A project that wants every image change to come from an MMX run leaves
podman-auto-update.timer off and uses podman_image.
Mounted files and SELinux
Mount a directory, not a single file, for configuration that is reloaded. MMX replaces a file by writing a new one and renaming it over the old one. A container that mounts the single file keeps the old one until it restarts. A container that mounts the directory sees the new file at once.
On a node with SELinux, a container may read only files with a
container label. The selinux_file_context task of
Run a container from a Quadlet file
gives the directory and everything inside it the label container_file_t,
also the files that MMX writes there later. On a node without SELinux the
task reports skipped. A mount can also end with :Z, such as
Volume=/srv/shop/uploads:/var/lib/shop/uploads:Z in the Quadlet file, and
Podman then sets the label. For a directory whose files MMX writes and the
container reads again on a reload, use the selinux_file_context task
instead: the files that MMX writes later then carry the label too.
The account's own systemd
With in_systemd_of_user_account, the Quadlet file belongs to that
account's own systemd, and the container runs as that account. Normally an
account's services stop when the account's last login session ends and do
not start at boot. The first task that needs the account's systemd therefore
makes the account's services start at boot and keep running after logout
(systemd calls this "lingering"), and says so in its result: Enabled lingering for account shop, so its services start at boot and keep running after logout. MMX has no setting to choose whether to enable lingering.
podman_quadlet enables lingering for the account named by
in_systemd_of_user_account after Podman's check accepts the Quadlet file.
A rejected Quadlet file leaves the account unchanged.
Podman needs the account, home directory, and ID ranges listed below.
When a requirement is missing, the task fails and names the missing
requirement. When an account requirement is missing, a dryrun reports
not_checked, because an earlier task in the run can still provide the
missing requirement:
- The account exists.
- It has a home directory, where Podman keeps the account's containers and images.
- The account named by
in_systemd_of_user_accounthas its own ranges of additional user and group IDs for Podman's container processes. The ranges are called sub-user and sub-group IDs./etc/subuidand/etc/subgidmust each contain a line for the account. The system's account tools add the account's/etc/subuidand/etc/subgidlines when creating an ordinary account. The account tools add no sub-user or sub-group ID ranges for a system account, so create the account withsystem: false.
An ordinary account cannot publish a port below 1024 unless the node's
kernel setting net.ipv4.ip_unprivileged_port_start allows it.
Removal
state says what is removed and whether data stays:
state |
Allowed on | What MMX does | What stays |
|---|---|---|---|
file_and_service_removed_named_volumes_kept |
every kind | Stops the generated service if it runs, deletes the Quadlet file, and reloads systemd. For a .network file MMX first removes the Podman network. |
Named volumes with their data, images, and every directory of the node that was mounted into the container. |
volume_and_its_data_removed |
.volume only |
First deletes the named volume with the data in it (podman volume rm). Then stops the generated service if running, deletes the Quadlet file, and reloads systemd. |
Images. |
file_and_service_removed_named_volumes_kept and
volume_and_its_data_removed accept only name,
in_systemd_of_user_account, and state. Podman
removes a Quadlet container when its service stops, so stopping the service
removes the container. Both states report unchanged when everything is
already gone (the file and, for the second, the volume too), so a removal
playbook reruns unchanged.
The volume or network goes before anything is stopped. While a container still uses a volume or a network, Podman refuses to remove it: the task fails with Podman's message and changes nothing, and the Quadlet file stays for the next run.
systemd stops a container together with the service of a volume file or a
network file that the container's file names. So removing such a file while
its container runs also stops the container. The result's reason names
what the task deleted and every service it stopped, the container's service
among them; in a dryrun it names what a run would delete and stop. Remove
the container's file first.
Data can be kept first and deleted later. A playbook may remove
shop-web-data.volume with file_and_service_removed_named_volumes_kept.
A later run may remove shop-web-data.volume with
volume_and_its_data_removed. The second task still deletes the volume.
After deleting a .volume file, MMX cannot read
the file's VolumeName= to find the retained volume.
Podman has no record linking a volume to the Quadlet file whose service
created the volume.
The generated service runs podman volume create with the volume's name
and only the labels declared in the .volume file.
When file_and_service_removed_named_volumes_kept removes a .volume file,
MMX records the volume's name on the node, in
/var/lib/mmx/podman_volumes_of_removed_quadlet_files/, in a file named for
the Quadlet file, below system or account_<account>. The second task
finds the volume by that record, deletes it, and removes the record. A task
that installs the file again removes the record too, because the installed
file names its volume.
When the file is gone and MMX has no record, because somebody deleted the
file by hand, MMX can check only the name that Podman gives a volume without
VolumeName=: systemd- and the file's base name. The reason then says
that only this name was checked.
Errors and what they mean
Every reason starts with podman_quadlet, except the failure of a
systemd_service task with start_at_boot.
| The reason holds | What the reason means, and what to do |
|---|---|
the program podman is not installed; install Podman in an earlier node task |
See Set up. A dryrun reports the task not_checked. |
Podman 4.3.1 is installed, and Quadlet files need Podman 4.4 or newer |
The node's Podman has no Quadlet, as on Debian 12. Install a newer Podman in an earlier node task. |
Podman 4.9.3 is installed, and .pod Quadlet files need Podman 5.0 or newer; Podman 4.9.3 would ignore ... without a word |
The node's Podman does not know .pod files. Nothing was written. Use another kind, or a newer Podman. |
Podman's Quadlet generator ... is missing; install the podman package in an earlier node task |
Install the package podman. |
Podman's check of the new Quadlet file failed: the Quadlet generator of Podman ... makes no ... from ... |
The generator rejected the new file; the message ends with its own words. The installed file stays. Correct the file. A file that names another Quadlet file needs that file installed first. |
podman_quadlet requires exactly one of content or template |
With state: present, write content or template, not both. |
state: volume_and_its_data_removed is only for a .volume file; remove ... with state: file_and_service_removed_named_volumes_kept |
Another kind of file has no volume to delete. |
account shop has no home directory at /home/shop |
Create the account with a user task that says create_home_directory: true. |
account shop has no range of sub-user IDs in /etc/subuid |
Create the account with a user task that says system: false, or add the range to an existing account with usermod --add-subuids and --add-subgids. |
the systemd of account shop does not run, so Podman cannot be asked about the account's ... |
Start account shop's systemd with systemctl start user@<uid>.service, as the message says. |
From systemd_service: unit shop-web.service is generated from the Quadlet file ..., so systemd can neither enable nor disable it; remove start_at_boot from this task |
See Rules for the files. |
... uses a systemd specifier, so MMX cannot tell the volume's name; remove the volume with a shell task that runs podman volume rm |
The .volume or .network file names its volume or network with a systemd specifier, a placeholder that systemd replaces. For example, %i represents the instance name between @ and .service in a service name. Remove the Podman volume or network with a shell task. |
From wait_for: the container shop-web declares no health check, so Podman never reports it healthy |
Declare a health check with HealthCmd= in container shop-web's Quadlet file. Alternatively, wait for a port or a url. |
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The suite tests/integration/podman_containers.py runs in system containers on Debian 12 and 13 and Ubuntu 24.04 and 26.04,
and in virtual machines on Rocky Linux 9 and AlmaLinux 10. It covers podman_quadlet, podman_image, and the
wait_for form podman_container_is_healthy:
| Distribution | Podman | Result |
|---|---|---|
| Debian 12 | 4.3.1 | No Quadlet; the suite checks that the failure names installed Podman 4.3.1 and required Podman 4.4. |
| Debian 13 | 5.4.2 | Passed. |
| Ubuntu 24.04 | 4.9.3 | Passed. |
| Ubuntu 26.04 | 5.7.0 | Passed. |
| Rocky Linux 9, AlmaLinux 10 | 5.8 | Passed. |
The suite also passed on Hetzner Cloud servers with Debian 12 and 13, and Ubuntu 24.04.
Not verified:
- Quadlet files of the kinds
.kube,.image, and.buildon a node. Go tests cover their name rule, the Podman version each needs, and the check, with a stand-in for Podman's generator. The suite starts.container,.volume,.network, and.podfiles. - Podman 4.4 to 4.8 and 5.0 to 5.3, which no supported distribution ships.
- A reboot of a node with Quadlet services and with an account's lingering services.
Limits on each distribution says what is limited for this module on Debian 12, and why.
Why it works this way
-
Removal names the file and service.
file_and_service_removed_named_volumes_keptstops the generated service and removes the Quadlet file. Named volume data stays. -
The Quadlet file is the declared thing. It is Podman's own format and has every container setting. MMX adds no container settings of its own, so nothing is repeated and no setting is missing.
-
A container is a systemd service. MMX already remembers what each service last loaded and restarts it once after a change, also after an interrupted run. Podman containers use that, with no second mechanism.
-
MMX does not drive
podman compose. Quadlet is Podman's own declared form, and it makes a container an ordinary systemd service that MMX's service records already handle. -
Docker and Podman have separate modules. They work differently on the server: Docker has a daemon and Compose, Podman has systemd units. A shared name would hide which one runs.
-
No module installs Podman. Installing is a package task, which already handles versions and removal.
-
The removal states say whether data stays. A reader must see from the one line whether data is deleted.
-
The volume goes before anything is stopped. A container's generated service requires the service of the volume file it names. If MMX stopped that first, systemd would stop the container, and Podman would then delete a volume that was in use a moment before.
-
There is no setting for lingering. A server container always needs it, and a setting that always has one value should not exist.
-
The check reads the generator's output, not its exit code. Podman 4.9 exits with 0 for some files it cannot use, and every version exits with 1 for a good new file beside another installed file that it rejects.
-
The stand-in file. A new file that the generator cannot read at all (a line that is no section, key, or comment) is passed over, by Podman 4.9 without a word. Without the stand-in, the generator would read the installed file with the new Quadlet file's name and print the installed file's service. MMX would then install the broken replacement (measured with Podman 4.9.3 and 5.4.2).
-
The account runs the check of its own files. The account fills its Quadlet directory, and a generator run by root would read whatever a link there points to.
-
A file kind that the node's Podman does not know is refused. An older generator ignores a file of a kind it does not know and says nothing (measured:
.podand.buildwith Podman 4.9.3). -
A file that another names is installed first. Podman's generator rejects a container file that names a Quadlet file it cannot find (measured with Podman 5.4 to 5.8; Podman 4.9 accepts it).
-
start_at_bootis refused when the project loads, too. On the node, a dryrun before the first run has no generated unit to look at, so only the run could fail, after it installed the Quadlet files.
This page is docs/reference/modules/podman_quadlet.md in the MMX repository.