Zum Inhalt springen
Trainingslager IT-Trainingslager

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.container wird notes-api.service, aus notes.pod wird notes-pod.service. Gestartet, gestoppt und geloggt wird mit systemctl und journalctl.
  • Ohne Linger stirbt dein User-systemd beim Abmelden – und mit ihm die Container.
  • AutoUpdate= plus podman auto-update holt 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 -version

Erwartet:

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 -2

Erwartet (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 -user

Erwartet (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 langes podman run: --replace ersetzt einen gleichnamigen Container, --rm löscht ihn beim Stoppen. Zustand gehört deshalb in Volumes.
  • Type=notify mit --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/qtest

Erwartet:

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-reload

Fortschritt 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
EOF

VolumeName=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
EOF

Die 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 in notes-db.service.
  • Pod=notes.pod bindet jeden Container per BindsTo= an notes-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; echo

Erwartet (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 State

Erwartet:

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 reboot

Nach 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 length

Erwartet (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-run

Erwartet:

            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 -2

Erwartet (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=registry verlangt einen vollqualifizierten Namen. Mit Image=nginx:… warnt schon der Dryrun, und podman run mit 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-web

Erwartet:

active
active
active
active

Linger und Auto-Update-Timer:

loginctl show-user "$USER" -p Linger
systemctl --user is-enabled podman-auto-update.timer

Erwartet:

Linger=yes
enabled

Notizen über den Quadlet-Pod:

curl -s 127.0.0.1:8080/notes | jq length

Erwartet:

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=128m
q=~/.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-web

Erwartet (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.service

Fortschritt 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= mit podman secret create oder EnvironmentFile= mit Modus 0600, besser ein Secret-Store.
  • AutoUpdate=registry nur mit Tags, die ihr selbst kontrolliert, und mit Rollback: podman auto-update stellt das alte Image wieder her, wenn der neue Dienst nicht startet – vorausgesetzt, Notify=healthy meldet 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.