Deploy a container with Podman and Quadlet files
Prepare the server with the example podman-host. Then set
the server address and the image in inventories/example.yml, and run:
mmx dryrun deploy
mmx run deploy
mmx run deploy
A Quadlet file is a small file in systemd's unit syntax that describes a container. At each systemd reload, Podman turns every Quadlet file into a systemd service. The container then is an ordinary systemd service.
On the node, in order:
- MMX writes the application's configuration file into
/etc/shop-web, a directory of the node that the container reads. - If the node does not have the image, MMX pulls the image.
- MMX installs two Quadlet files under
/etc/containers/systemd/:shop-web-data.volumefor the application's data andshop-web.containerfor the container. Podman's generator checks each new Quadlet file before MMX installs the Quadlet file. systemd then has the servicesshop-web-data-volume.serviceandshop-web.service. - MMX starts
shop-web.service, which creates the volume and the container, and waits until the container's own health check reports healthy.
The second run changes nothing.
What a later run does
| You change | The next mmx run deploy |
|---|---|
shop_web_greeting |
Writes the configuration file and reloads the service: Podman runs the reload command inside the container, and the same process reads the file again. |
shop_web_image to the next tag |
Pulls the new image, installs the changed shop-web.container, and restarts the service once. |
Anything else in shop-web.container |
Checks and installs shop-web.container and restarts the service once. |
| Nothing | Nothing. |
If a run stops after a change and before the restart or reload, the next run still restarts or reloads the service once. MMX remembers what the service last loaded, not what the last run changed.
Stop for a backup, and remove
mmx run back_up # stop, copy the volume to a tar file, start
mmx run remove_and_keep_data # remove the container; the volume stays
mmx run remove_with_data # remove the container and delete the volume
back_up writes /var/lib/shop-web-backups/shop-web-data.tar on the node.
remove_with_data also deletes the volume when remove_and_keep_data ran
before it. Only the file shop-web-data.volume says which volume is its
own, and remove_and_keep_data deletes that file. So MMX records the
volume's name on the node at that moment, and remove_with_data finds the
volume by the record.
No playbook deletes the image or /etc/shop-web. Deleting a task from a
playbook removes nothing on the node.
Why it is written this way
The configuration is a directory, not a single file. MMX replaces a file by writing a new one and renaming it over the old one. A container that mounts the single file keeps seeing the old one until it restarts. A container that mounts the directory sees the new file at once, so a reload is enough.
The SELinux label rule. On a node with SELinux, a container may read
only files that carry a container label. The selinux_file_context task
gives /etc/shop-web and everything inside it that label, also files that
MMX writes later. On a node without SELinux the task reports skipped. On the
Red Hat family the task needs the package policycoreutils-python-utils.
The volume's file before the container's file. The container's file
names shop-web-data.volume. Podman's generator rejects a container file
that names a Quadlet file it cannot find, so the named file is installed
first. Removal goes the other way: the container first.
refresh: reload on the service task. It says what a changed
configuration file needs: a reload, which the Quadlet file's ExecReload=
line carries out inside the container. A new image and a changed Quadlet
file always restart the service, also with refresh: reload, because the
running container was made from the old ones.
No start_at_boot on the service task. systemd cannot enable a service that
a generator made. Whether the container starts at boot is the [Install]
section of the Quadlet file.
Distributions
The example needs Podman 4.4 or newer: Debian 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10.
Debian 12 ships an older Podman, which has no Quadlet files: there the
podman_quadlet tasks fail and name both versions.
For every field, see the
podman_quadlet and
podman_image pages.
This page is examples/deploy-with-podman-quadlet/README.md in the MMX repository.