Tag 3: Quadlet
Ziel: Den Pod notes als systemd-Dienste beschreiben, die nach jedem Neustart von selbst hochkommen, sich nach Abstürzen erholen und Image-Updates automatisch übernehmen. · Dauer: ca. 75 min · Voraussetzung: Tag 2
Briefing
- Quadlet übersetzt kleine INI-Dateien
(
.container,.pod,.volume,.network) in systemd-Services. Es ist ein systemd-Generator und Teil von Podman. - Deine Dateien liegen in
~/.config/containers/systemd/. Nach jeder Änderung:systemctl --user daemon-reload. - Aus
notes-api.containerwirdnotes-api.service, ausnotes.podwirdnotes-pod.service. Gestartet, gestoppt und geloggt wird mitsystemctlundjournalctl. - Ohne Linger stirbt dein User-systemd beim Abmelden – und mit ihm die Container.
AutoUpdate=pluspodman auto-updateholt neue Images und startet Dienste neu.
~/.config/containers/systemd/ systemd --user
notes.network ──quadlet──► notes-network.service
notes-pgdata.volume ──────────► notes-pgdata-volume.service
notes.pod ──────────► notes-pod.service ─┬─► notes-db.service (healthy)
notes-db.container ──────────► ├─► notes-migrate.service (1x)
notes-migrate/-api/-web.container ─► ├─► notes-api.service
└─► notes-web.service
Drill 1: Quadlet – Steckbrief und erster Dienst
| Steckbrief | Quadlet |
|---|---|
| Aufgabe | Container, Pods, Volumes und Netze als systemd-Units betreiben |
| Besonderheit | kein eigener Dienst: Generator beim daemon-reload,
Ergebnis ist normales systemd |
| Projekt | docs.podman.io, Handbuch
podman-systemd.unit(5) |
| Version im Buch | wie Podman: 5.7.0 |
Quadlet kommt mit dem Paket podman – es gibt nichts
extra zu installieren. Prüfen, wo es liegt und wie systemd es
aufruft:
dpkg -S /usr/libexec/podman/quadlet
ls -l /usr/lib/systemd/user-generators/podman-user-generator
/usr/libexec/podman/quadlet -versionErwartet:
podman: /usr/libexec/podman/quadlet
lrwxrwxrwx 1 root root 31 Feb 23 2026 /usr/lib/systemd/user-generators/podman-user-g…
5.7.0
So funktioniert Quadlet: Bei jedem
daemon-reload ruft systemd alle Generatoren auf. Quadlet
liest deine Dateien, schreibt fertige .service-Units nach
/run/user/1000/systemd/generator/ und ist wieder weg. Der
Dienst selbst ist ein podman run unter systemd.
Tagesstart und der erste Dienst – nginx auf Port 8080:
source ~/ct-lab/setup/env.sh
mkdir -p ~/ct-lab/tag03 && cd ~/ct-lab/tag03
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag02/notes/." .
mkdir -p ~/.config/containers/systemd
cat > ~/.config/containers/systemd/web.container <<'EOF'
# ~/.config/containers/systemd/web.container – nur Tag 3, Drill 1–2
[Unit]
Description=nginx als Quadlet (Tag 3)
[Container]
ContainerName=web
Image=docker.io/library/nginx:1.30.6-alpine
PublishPort=127.0.0.1:8080:80
[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload
systemctl --user start web.service
systemctl --user status web.service --no-pager | head -5
curl -sI 127.0.0.1:8080 | head -2Erwartet (gekürzt, IDs und Zeiten weichen bei dir ab):
● web.service - nginx als Quadlet (Tag 3)
Loaded: loaded (/home/ubuntu/.config/containers/systemd/web.container; generated)
Active: active (running) since Fri 2026-10-30 19:04:17 UTC; 106ms ago
Invocation: ac94eca29c47418482807f2ecf11d601
Main PID: 32732 (conmon)
HTTP/1.1 200 OK
Server: nginx/1.30.6
Loaded: … generated – die Unit stammt vom Generator, die
Quelle ist deine .container-Datei. Main PID
ist conmon, der Wächter aus Tag 1.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Was Quadlet erzeugt
Der Dryrun zeigt die erzeugten Units, ohne etwas zu ändern – das wichtigste Werkzeug bei Fehlern:
/usr/libexec/podman/quadlet -dryrun -userErwartet (gekürzt):
quadlet-generator[32657]: Loading source unit file /home/ubuntu/.config/containers/sy…
---web.service---
# ~/.config/containers/systemd/web.container – nur Tag 3, Drill 1–2
[Unit]
Wants=podman-user-wait-network-online.service
After=podman-user-wait-network-online.service
Description=nginx als Quadlet (Tag 3)
SourcePath=/home/ubuntu/.config/containers/systemd/web.container
RequiresMountsFor=%t/containers
[X-Container]
ContainerName=web
…
[Service]
Environment=PODMAN_SYSTEMD_UNIT=%n
KillMode=mixed
ExecStop=/usr/bin/podman rm -v -f -i web
ExecStopPost=-/usr/bin/podman rm -v -f -i web
Delegate=yes
Type=notify
NotifyAccess=all
SyslogIdentifier=%N
ExecStart=/usr/bin/podman run --name web --replace --rm --cgroups=split --sdnotify=c…
- Aus
[Container]wird ein langespodman run:--replaceersetzt einen gleichnamigen Container,--rmlöscht ihn beim Stoppen. Zustand gehört deshalb in Volumes. Type=notifymit--sdnotify=conmon: systemd meldet „gestartet”, sobald der Container läuft.
Und [Install]? Generierte Units kannst du nicht
enablen – Quadlet legt den Link selbst an:
systemctl --user enable web.service; echo "Exit: $?"
ls /run/user/1000/systemd/generator/default.target.wants/Erwartet:
Failed to enable unit: Unit /run/user/1000/systemd/generator/web.service is transient o…
Exit: 1
web.service
Tippfehler meldet ebenfalls der Dryrun.
QUADLET_UNIT_DIRS lässt ihn nur einen Ordner lesen:
mkdir -p /tmp/qtest
printf '[Container]\nImage=%s\nPublishport=8081:80\n' \
docker.io/library/nginx:1.30.6-alpine > /tmp/qtest/kaputt.container
QUADLET_UNIT_DIRS=/tmp/qtest /usr/libexec/podman/quadlet -dryrun -user; echo "Exit: $?"
rm -rf /tmp/qtestErwartet:
quadlet-generator[40035]: Loading source unit file /tmp/qtest/kaputt.container
quadlet-generator[40035]: converting "kaputt.container": unsupported key 'Publishport' …
quadlet-generator[40035]: processing encountered some errors
Exit: 1
Beim echten daemon-reload fehlt die Unit dann einfach:
Unit kaputt.service not found. Der nginx-Dienst hat seinen
Zweck erfüllt:
systemctl --user stop web.service
rm ~/.config/containers/systemd/web.container
systemctl --user daemon-reloadFortschritt speichern? Kostenlos registrieren
Drill 3: Netz, Volume und Pod
Drei kleine Units. NetworkName=,
VolumeName= und PodName= setzen die Namen
fest; ohne sie hießen die Objekte systemd-notes usw.
cd ~/.config/containers/systemd
cat > notes.network <<'EOF'
# ~/.config/containers/systemd/notes.network – Stand Ende Tag 3
[Unit]
Description=Netz für den Pod notes
[Network]
NetworkName=notes
EOF
cat > notes-pgdata.volume <<'EOF'
# ~/.config/containers/systemd/notes-pgdata.volume – Stand Ende Tag 3
[Unit]
Description=Postgres-Daten für notes
[Volume]
VolumeName=notes-pgdata
EOF
cat > notes.pod <<'EOF'
# ~/.config/containers/systemd/notes.pod – Stand Ende Tag 3
[Unit]
Description=Pod notes: db, migrate, api, web
[Pod]
PodName=notes
Network=notes.network
PublishPort=127.0.0.1:8080:8080
PublishPort=127.0.0.1:3000:3000
[Install]
WantedBy=default.target
EOFVolumeName=notes-pgdata ist Absicht: Das Volume von Tag
2 existiert schon, Quadlet legt es mit
podman volume create --ignore an – vorhandene Daten
bleiben. Und Network=notes.network verweist auf die Unit,
nicht auf den Netznamen. Daran erkennt Quadlet die Abhängigkeit.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Die Container des Pods
Postgres meldet sich erst als gestartet, wenn der Healthcheck grün
ist (Notify=healthy):
cat > notes-db.container <<'EOF'
# ~/.config/containers/systemd/notes-db.container – Stand Ende Tag 3
[Unit]
Description=Postgres für notes
[Container]
ContainerName=notes-db
Image=docker.io/library/postgres:18.6-alpine
Pod=notes.pod
Volume=notes-pgdata.volume:/var/lib/postgresql
Environment=POSTGRES_USER=notes POSTGRES_DB=notes
Environment=POSTGRES_PASSWORD=lab-db-pw-123
HealthCmd=pg_isready -h 127.0.0.1 -U notes -d notes
HealthInterval=5s
Notify=healthy
AutoUpdate=registry
[Service]
Restart=on-failure
TimeoutStartSec=300
EOFDie Migration ist ein Einmal-Job: Type=oneshot wartet,
bis der Container endet, RemainAfterExit=yes lässt die Unit
danach „active” stehen.
cat > notes-migrate.container <<'EOF'
# ~/.config/containers/systemd/notes-migrate.container – Stand Ende Tag 3
[Unit]
Description=Schema für notes anlegen (einmalig pro Start)
Requires=notes-db.container
After=notes-db.container
[Container]
ContainerName=notes-migrate
Image=localhost/notes-api:0.1.0
Pod=notes.pod
Exec=migrate
Environment=NOTES_DB_URL=postgres://notes:[email protected]:5432/notes
[Service]
Type=oneshot
RemainAfterExit=yes
EOF
cat > notes-api.container <<'EOF'
# ~/.config/containers/systemd/notes-api.container – Stand Ende Tag 3
[Unit]
Description=notes-api
Requires=notes-migrate.container
After=notes-migrate.container
[Container]
ContainerName=notes-api
Image=localhost/notes-api:0.1.0
Pod=notes.pod
Environment=NOTES_API_KEY=lab-api-key-123
Environment=NOTES_DB_URL=postgres://notes:[email protected]:5432/notes
Notify=healthy
AutoUpdate=local
[Service]
Restart=on-failure
EOF
cat > notes-web.container <<'EOF'
# ~/.config/containers/systemd/notes-web.container – Stand Ende Tag 3
[Unit]
Description=notes-web
Wants=notes-api.container
After=notes-api.container
[Container]
ContainerName=notes-web
Image=localhost/notes-web:0.1.0
Pod=notes.pod
Environment=NOTES_API_URL=http://127.0.0.1:8080
Environment=NOTES_API_KEY=lab-api-key-123
AutoUpdate=local
[Service]
Restart=on-failure
EOF- In
Requires=/After=darfst du die Quadlet-Datei nennen (notes-db.container); Quadlet übersetzt sie innotes-db.service. Pod=notes.podbindet jeden Container perBindsTo=annotes-pod.service: Stoppt der Pod, stoppen alle.- notes-api hat seinen Healthcheck im Image (Tag 1), deshalb reicht
Notify=healthy.
Prüfen, laden, starten:
/usr/libexec/podman/quadlet -dryrun -user 2>&1 | grep -E '^---|rror'
systemctl --user daemon-reload
systemctl --user list-unit-files 'notes*' --no-pager
systemctl --user start notes-pod.service
until curl -sf 127.0.0.1:3000 >/dev/null; do sleep 1; done
systemctl --user list-units 'notes*' --all --no-pager --legend=no
podman ps -a --pod --format '{{.Names}}\t{{.Status}}'
curl -s -X POST 127.0.0.1:3000/api/notes -H 'Content-Type: application/json' \
-d '{"text":"Tag 3 mit Quadlet"}'; echo
curl -s 127.0.0.1:8080/notes; echoErwartet (gekürzt):
---notes-pgdata-volume.service---
---notes-network.service---
---notes-api.service---
---notes-db.service---
---notes-migrate.service---
---notes-web.service---
---notes-pod.service---
UNIT FILE STATE PRESET
notes-api.service generated -
notes-db.service generated -
notes-migrate.service generated -
notes-network.service generated -
notes-pgdata-volume.service generated -
notes-pod.service generated -
notes-web.service generated -
7 unit files listed.
notes-api.service loaded active running notes-api
notes-db.service loaded active running Postgres für notes
notes-migrate.service loaded active exited Schema für notes anlegen (einmalig…
notes-network.service loaded active exited Netz für den Pod notes
notes-pgdata-volume.service loaded active exited Postgres-Daten für notes
notes-pod.service loaded active running Pod notes: db, migrate, api, web
notes-web.service loaded active running notes-web
notes-infra Up 18 seconds
notes-db Up 17 seconds (healthy)
notes-api Up 10 seconds (healthy)
notes-web Up 10 seconds
{"id":"ec7fd844-…","text":"Tag 3 mit Quadlet"}
[{"id":"1ac607e9-…","text":"Tag 2 im Pod"},{"id":"ec7fd844-…","text":"Tag 3 mit Quadlet…
systemctl start notes-pod.service kehrt nach einer
Sekunde zurück; die Container kommen per Wants= hinterher,
in der Reihenfolge aus After=. Die Notiz von Tag 2 ist da:
dasselbe Volume. notes-migrate ist kein laufender Container mehr, nur
noch eine Unit im Zustand exited.
Fortschritt speichern? Kostenlos registrieren
Drill 5: journalctl und Neustart nach Absturz
Jeder Container loggt ins Journal, mit dem Unit-Namen als Kennung
(-t). Unter -u stehen zusätzlich die Meldungen
von systemd und podman:
journalctl --user -t notes-migrate -o cat --no-pager -n 1
journalctl --user -u notes-db.service --no-pager -n 2 -o cat
podman kill notes-api
sleep 8
journalctl --user -u notes-api.service --no-pager -o cat \
| grep -E 'Main process|Failed|Scheduled|Started' | tail -4
podman ps --format '{{.Names}}\t{{.Status}}'Erwartet (gekürzt):
time=2026-10-30T19:04:50.700Z level=INFO msg="migration complete" table=notes
3cd7df25729bb0003c5862423ccf9b25bce91ee643feaf4837178d97ae57197c
Started notes-db.service - Postgres für notes.
notes-api
notes-api.service: Main process exited, code=exited, status=137/n/a
notes-api.service: Failed with result 'exit-code'.
notes-api.service: Scheduled restart job, restart counter is at 1.
Started notes-api.service - notes-api.
notes-infra Up 37 seconds
notes-db Up 36 seconds (healthy)
notes-web Up 29 seconds
notes-api Up 7 seconds (healthy)
Exit 137 = SIGKILL. Restart=on-failure startet den
Dienst neu, podman logs gibt es trotzdem weiterhin – beides
liest dasselbe Journal. Ein sauberes systemctl --user stop
zählt nicht als Fehler und löst keinen Neustart aus.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Linger – Dienste ohne Anmeldung
Dein systemd läuft nur, solange du angemeldet bist – es sei denn, Linger ist an:
loginctl show-user "$USER" -p Linger
sudo loginctl enable-linger "$USER"
loginctl show-user "$USER" -p Linger -p StateErwartet:
Linger=no
Linger=yes
State=active
Mit Linger startet systemd deinen User-Manager beim Booten, und der
startet alles, was in default.target hängt – hier
notes-pod.service aus [Install] in
notes.pod. Der echte Test ist ein Neustart der VM:
sudo rebootNach einer halben Minute auf dem Mac
multipass shell ct-lab, dann:
systemctl --user list-units 'notes*' --no-pager --legend=no | awk '{print $1, $3, $4}'
curl -s 127.0.0.1:8080/notes | jq lengthErwartet (gekürzt):
notes-api.service active running
notes-db.service active running
notes-migrate.service active exited
notes-network.service active exited
notes-pgdata-volume.service active exited
notes-pod.service active running
notes-web.service active running
2
Achtung: Ohne Linger beendet systemd beim Abmelden deinen User-Manager samt Containern – oft erst Sekunden später, was die Fehlersuche verwirrend macht.
Fortschritt speichern? Kostenlos registrieren
Drill 7: AutoUpdate und
podman auto-update
AutoUpdate=registry (notes-db) vergleicht den Digest in
der Registry mit dem lokalen Image, AutoUpdate=local (api,
web) vergleicht mit dem lokalen Image gleichen Namens. Erst trocken:
podman auto-update --dry-runErwartet:
UNIT CONTAINER IMAGE …
notes-pod.service e35b3fb550f5 (notes-db) docker.io/library/postgres:1…
notes-pod.service d6f8c01025dc (notes-api) localhost/notes-api:0.1.0 …
notes-pod.service 3a69eb4a82bc (notes-web) localhost/notes-web:0.1.0 …
Die letzten Spalten (abgeschnitten) heißen POLICY und
UPDATED: registry false,
local false, local false. Jetzt ein neues
lokales Image unter demselben Tag:
cd ~/ct-lab/tag03
podman build -q --format docker -t localhost/notes-api:0.1.0 \
--build-arg VERSION=0.1.0 --build-arg REVISION=tag03 notes-api
podman auto-update --dry-run --format '{{.Container}} {{.Policy}} {{.Updated}}'
podman auto-update --format '{{.Container}} {{.Policy}} {{.Updated}}'
sleep 15
podman inspect notes-api \
--format '{{index .Config.Labels "org.opencontainers.image.revision"}}'Erwartet (gekürzt):
f0ad4bdd6bbb…
e35b3fb550f5 (notes-db) registry false
d6f8c01025dc (notes-api) local pending
3a69eb4a82bc (notes-web) local false
e35b3fb550f5 (notes-db) registry true
d6f8c01025dc (notes-api) local true
3a69eb4a82bc (notes-web) local true
tag03
pending heißt: Ein Neustart würde ein anderes Image
bringen. Danach stehen alle drei auf true:
Container in einem Pod gehören zur Unit notes-pod.service,
und auto-update startet die ganze Unit neu. Automatisch, täglich, macht
das ein Timer:
systemctl --user enable --now podman-auto-update.timer
systemctl --user list-timers podman-auto-update.timer --no-pager | head -2Erwartet (gekürzt):
Created symlink '/home/ubuntu/.config/systemd/user/timers.target.wants/podman-auto-up…
NEXT LEFT LAST PASSED UNIT ACTIVATES
Sat 2026-10-31 00:12:21 UTC 5h 5min - - podman-auto-update.timer podman-auto-…
Achtung:
AutoUpdate=registryverlangt einen vollqualifizierten Namen. MitImage=nginx:…warnt schon der Dryrun, undpodman runmit dem Label scheitert:auto updates require fully-qualified image reference.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Die sieben Quadlet-Dateien und ein fehlerfreier Dryrun:
cd ~/ct-lab/tag03
ls ~/.config/containers/systemd/
/usr/libexec/podman/quadlet -dryrun -user >/dev/null 2>&1; echo "Exit: $?"Erwartet:
notes-api.container
notes-db.container
notes-migrate.container
notes-pgdata.volume
notes-web.container
notes.network
notes.pod
Exit: 0
Die Units laufen:
systemctl --user is-active notes-pod notes-db notes-api notes-webErwartet:
active
active
active
active
Linger und Auto-Update-Timer:
loginctl show-user "$USER" -p Linger
systemctl --user is-enabled podman-auto-update.timerErwartet:
Linger=yes
enabled
Notizen über den Quadlet-Pod:
curl -s 127.0.0.1:8080/notes | jq lengthErwartet:
3
Challenge
Begrenze notes-web per Quadlet auf 128 MB Arbeitsspeicher und beweise
mit podman, dass die Grenze greift.
Hinweis: podman-systemd.unit(5) kennt
im Abschnitt [Container] den Schlüssel
Memory=.
Lösung
Im Abschnitt [Container] von
notes-web.container eine Zeile ergänzen (ganze Datei:
code/tag03/challenge/notes-web.container):
AutoUpdate=local
Memory=128mq=~/.config/containers/systemd
cp "$q/notes-web.container" /tmp/notes-web.container.bak
sed -i 's/^AutoUpdate=local$/AutoUpdate=local\nMemory=128m/' "$q/notes-web.container"
/usr/libexec/podman/quadlet -dryrun -user 2>/dev/null | grep -o -- '--memory [^ ]*'
systemctl --user daemon-reload
systemctl --user restart notes-web.service
sleep 3
podman inspect notes-web --format '{{.HostConfig.Memory}}'
podman stats --no-stream --format '{{.Name}} {{.MemUsage}}' notes-webErwartet (gekürzt):
--memory 128m
134217728
notes-web 26.26MB / 134.2MB
Das Limit greift rootless nur, weil systemd deinem User den
cgroup-Controller memory überlässt
(cpu memory pids in cgroup.subtree_control
deines [email protected]). Zurück zum Stand des Tages:
cp /tmp/notes-web.container.bak ~/.config/containers/systemd/notes-web.container
systemctl --user daemon-reload && systemctl --user restart notes-web.serviceFortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Quadlet-Dateien gehören ins Git und werden per Ansible oder
ähnlichem verteilt. Für Systemdienste liegen sie in
/etc/containers/systemd/und laufen rootful – oder rootless unter einem eigenen Dienst-User mit Linger. - Passwörter nicht in
Environment=:Secret=mitpodman secret createoderEnvironmentFile=mit Modus 0600, besser ein Secret-Store. AutoUpdate=registrynur mit Tags, die ihr selbst kontrolliert, und mit Rollback:podman auto-updatestellt das alte Image wieder her, wenn der neue Dienst nicht startet – vorausgesetzt,Notify=healthymeldet wirklich „gesund”.- Wer ein bestehendes Kubernetes-YAML hat, kann es mit einer
.kube-Unit unverändert betreiben;.container-Dateien sind lesbarer und feiner steuerbar. - Ressourcen-Limits (
Memory=,PodmanArgs=--cpus …) und Logs ins zentrale System (journald → Fluent Bit, Vector) gehören zu jedem produktiven Dienst.