Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 1: Podman

Ziel: Podman wie docker benutzen – Images holen, Container starten, die drei notes-Images bauen – und verstehen, was Short-Names, rootless und rootful bedeuten. · Dauer: ca. 75 min · Voraussetzung: Tag 0

Briefing

  • Podman hat keinen Daemon. Jeder podman-Aufruf ist ein eigener Prozess; neben dem Container bleibt nur der kleine Wächter conmon stehen.
  • Die Befehle heißen wie bei Docker: run, ps, logs, exec, build, images.
  • Rootless (als ubuntu) und rootful (sudo podman) sind zwei getrennte Welten mit eigenem Image-Speicher, eigenen Containern und eigenem Netz.
  • Image-Namen ohne Registry (Short-Names) löst Podman nur über Aliase auf. Im Buch steht deshalb immer docker.io/library/….
 ubuntu (rootless)                          root (sudo podman)
 ┌──────────────────────────────────┐       ┌──────────────────────────────┐
 │ podman run ─► conmon ─► crun     │       │ sudo podman run ─► conmon    │
 │ ~/.local/share/containers        │       │ /var/lib/containers/storage  │
 │ UID 0 im Container = ubuntu      │       │ UID 0 im Container = root    │
 │ Netz: pasta                      │       │ Netz: Bridge podman0         │
 └──────────────────────────────────┘       └──────────────────────────────┘

Drill 1: podman – Steckbrief und Installation

Steckbrief podman
Aufgabe Container und Pods starten, Images bauen, holen und verwalten
Besonderheit daemonlos, rootless als Standard, Pods, systemd-Integration (Quadlet)
Projekt podman.io, github.com/containers/podman
Version im Buch 5.7.0 (Ubuntu-Paket podman)

Installiert hast du Podman an Tag 0. Einzeln sieht das so aus:

sudo apt-get install -y podman
apt-cache policy podman | head -3
podman --version
dpkg -L podman | grep -E 'bin/|libexec/podman/'

Erwartet:

podman:
  Installed: 5.7.0+ds2-3build1
  Candidate: 5.7.0+ds2-3build1
podman version 5.7.0
/usr/bin/podman
/usr/libexec/podman/podman-testing
/usr/libexec/podman/quadlet
/usr/libexec/podman/rootlessport
/usr/bin/podmansh

apt ist hier idempotent: Ist das Paket in dieser Version da, passiert nichts. quadlet brauchst du an Tag 3.

So funktioniert Podman: podman run legt den Container an, startet conmon und beendet sich. conmon ruft die OCI-Runtime crun auf, die den Prozess in eigenen Namespaces und cgroups startet, und bleibt als Wächter für Logs und Exit-Code stehen. Einen Dienst wie dockerd, der alle Container besitzt, gibt es nicht.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Short-Names und registries.conf

Bei Docker heißt nginx immer docker.io/library/nginx. Podman kennt mehrere Registries und rät nicht:

podman pull nginx:1.30.6-alpine; echo "Exit: $?"
grep -n 'unqualified-search-registries' /etc/containers/registries.conf
ls /etc/containers/registries.conf.d/
grep -E '"(alpine|golang|node|python|nginx|postgres)"' \
  /etc/containers/registries.conf.d/shortnames.conf

Erwartet:

Error: short-name "nginx:1.30.6-alpine" did not resolve to an alias and no unqualified-
search registries are defined in "/etc/containers/registries.conf"
Exit: 125
21:# unqualified-search-registries = ["example.com"]
shortnames.conf
  "alpine" = "docker.io/library/alpine"
  "golang" = "docker.io/library/golang"
  "python" = "docker.io/library/python"
  "node" = "docker.io/library/node"
  • registries.conf legt fest, welche Registries Podman für Namen ohne Registry durchsucht. Bei Ubuntu ist die Liste leer.
  • shortnames.conf enthält feste Aliase für bekannte Images. golang, node und python stehen drin, nginx und postgres nicht.

Warum so streng? Würde Podman nginx der Reihe nach in mehreren Registries suchen, könnte jemand in der ersten Registry ein gleichnamiges Image ablegen und so Code unterschieben. Vollqualifiziert gibt es keinen Zweifel:

podman pull docker.io/library/nginx:1.30.6-alpine
podman images
podman image inspect docker.io/library/nginx:1.30.6-alpine \
  --format '{{range .RepoDigests}}{{println .}}{{end}}'

Erwartet (gekürzt, IDs und Zeiten weichen bei dir ab):

Trying to pull docker.io/library/nginx:1.30.6-alpine...
Getting image source signatures
Copying blob sha256:9f0afb44f10e…
…
Writing manifest to image destination
88f52f3d58a505b7e1ad96ca6969478517bcccb58418e75a54223271a64da7df
REPOSITORY               TAG            IMAGE ID      CREATED     SIZE
docker.io/library/nginx  1.30.6-alpine  88f52f3d58a5  8 days ago  63.7 MB
docker.io/library/nginx@sha256:0e52bd054126cdc040b1276c0af347aeb02a41b9cfe305d60947…
docker.io/library/nginx@sha256:…

Der erste Digest gehört zum Index (die Liste aller Architekturen) und ist überall gleich, der zweite zum arm64-Manifest deiner VM. Einen eigenen Alias kannst du pro User anlegen – zum Ausprobieren:

mkdir -p ~/.config/containers/registries.conf.d
cat > ~/.config/containers/registries.conf.d/50-lab.conf <<'EOF'
# ~/.config/containers/registries.conf.d/50-lab.conf – nur Tag 1
[aliases]
"nginx" = "docker.io/library/nginx"
EOF
podman run --rm nginx:1.30.6-alpine nginx -v
rm ~/.config/containers/registries.conf.d/50-lab.conf

Erwartet (gekürzt):

/docker-entrypoint.sh: Configuration complete; ready for start up
nginx version: nginx/1.30.6

Im Buch bleibt es trotzdem bei vollqualifizierten Namen: Sie funktionieren auf jeder Maschine, ohne dass dort jemand Aliase pflegt.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Wie docker – run, ps, logs, exec

podman run -d --name web -p 127.0.0.1:8080:80 docker.io/library/nginx:1.30.6-alpine
podman ps
curl -sI http://127.0.0.1:8080 | head -2
podman logs --tail 1 web
podman exec web sh -c 'id; ps'

Erwartet (gekürzt):

dc1bd37dac9b2950c303f8f03ceeb362867a9c053e0ae6b6ee0a959b1554780e
CONTAINER ID  IMAGE                                  COMMAND               CREATED   …
dc1bd37dac9b  docker.io/library/nginx:1.30.6-alpine  nginx -g daemon o...  Less than…
HTTP/1.1 200 OK
Server: nginx/1.30.6
192.168.64.… - - [30/Oct/2026:19:18:20 +0000] "HEAD / HTTP/1.1" 200 0 "-" "curl/8.18.0"…
uid=0(root) gid=0(root) groups=0(root),1(bin),2(daemon),3(sys),4(adm),6(disk),10(wheel)…
PID   USER     TIME  COMMAND
    1 root      0:00 nginx: master process nginx -g daemon off;
   25 nginx     0:00 nginx: worker process
   26 nginx     0:00 nginx: worker process
   27 root      0:00 ps

Im Log steht als Absender die Adresse der VM, nicht 127.0.0.1: Rootless leitet pasta die Verbindung in den Container weiter (Tag 2). Und von außen betrachtet?

podman top web user huser pid hpid args
ps -o user,pid,ppid,comm -C conmon

Erwartet (gekürzt, PIDs weichen ab):

USER        HUSER       PID         HPID        COMMAND
root        1000        1           12725       nginx: master process nginx -g daemon…
nginx       100100      25          12757       nginx: worker process
nginx       100100      26          12758       nginx: worker process
USER         PID    PPID COMMAND
ubuntu     61076       1 conmon
  • HUSER ist der User auf dem Host. root im Container ist ubuntu (UID 1000), User nginx (UID 101) wird zu 100100. Das Mapping erklärt Tag 2.
  • conmon hängt direkt an PID 1. Es gibt keinen Daemon, dessen Absturz alle Container mitnimmt.
podman stop web && podman rm web
podman ps -a

Erwartet:

web
web
CONTAINER ID  IMAGE       COMMAND     CREATED     STATUS      PORTS       NAMES

Tipp: Das Ubuntu-Paket podman-docker legt /usr/bin/docker als Weiterleitung auf podman an. Für Skripte, die docker fest verdrahtet haben – im Buch nicht nötig.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Die notes-Images bauen

Tagesstart mit dem Stand von Tag 0:

source ~/ct-lab/setup/env.sh
mkdir -p ~/ct-lab/tag01 && cd ~/ct-lab/tag01
cp -R "$LAB/code/notes/." .
podman build -t localhost/notes-api:0.1.0 --build-arg VERSION=0.1.0 notes-api

Erwartet (gekürzt, dauert 1–2 Minuten):

[1/4] STEP 1/5: FROM --platform=linux/arm64 golang:1.27-alpine AS base
Resolved "golang" as an alias (/etc/containers/registries.conf.d/shortnames.conf)
Trying to pull docker.io/library/golang:1.27-alpine...
…
[4/4] STEP 1/10: FROM scratch AS final
…
[3/4] STEP 3/3: RUN --mount=type=cache,target=/go/pkg/mod     --mount=type=cache,targe…
…
[4/4] STEP 8/10: HEALTHCHECK --interval=10s --timeout=2s --start-period=5s --start-int…
time="…" level=warning msg="HEALTHCHECK is not supported for OCI image format and will
be ignored. Must use `docker` format"
…
[4/4] COMMIT localhost/notes-api:0.1.0
Successfully tagged localhost/notes-api:0.1.0
  • podman build ist eingebautes Buildah (Tag 5). --mount=type=cache, --link und $BUILDPLATFORM versteht es wie BuildKit.
  • Stage 2/4 (test) fehlt in der Ausgabe: Stages, die das Ziel nicht braucht, baut Buildah gar nicht erst.
  • golang löst Podman über den Alias auf – deshalb klappt der Build trotz Short-Name.
  • Die Warnung ist ernst: Das OCI-Image-Format kennt kein HEALTHCHECK. Podman baut standardmäßig OCI. Mit --format docker bleibt der Healthcheck im Image:
podman image inspect localhost/notes-api:0.1.0 --format '{{.Config.Healthcheck}}'
podman build --format docker -t localhost/notes-api:0.1.0 \
  --build-arg VERSION=0.1.0 notes-api 2>&1 | tail -2
podman image inspect localhost/notes-api:0.1.0 \
  --format '{{.Config.Healthcheck.Test}} {{.ManifestType}}'

Erwartet (gekürzt):

<nil>
Successfully tagged localhost/notes-api:0.1.0
70cfecc8196f03af339c000a7937ce7ab16791c0225d3e63dc7535642ad9d32f
[CMD /notes-api healthcheck] application/vnd.docker.distribution.manifest.v2+json

Der zweite Lauf dauert Sekunden, alle Schritte kommen aus dem Cache. Jetzt web und worker, gleich im Docker-Format:

podman build --format docker -t localhost/notes-web:0.1.0 notes-web
podman build --format docker -t localhost/notes-worker:0.1.0 notes-worker
podman image prune -f >/dev/null
podman images --filter reference='localhost/*'

Erwartet (gekürzt):

[1/2] STEP 1/6: FROM node:26-alpine AS build
Resolved "node" as an alias (/etc/containers/registries.conf.d/shortnames.conf)
…
[1/2] STEP 2/7: COPY --from=ghcr.io/astral-sh/uv:0.13.6 /uv /uvx /bin/
Trying to pull ghcr.io/astral-sh/uv:0.13.6...
…
REPOSITORY              TAG         IMAGE ID      CREATED             SIZE
localhost/notes-worker  0.1.0       f44274688acd  15 seconds ago      131 MB
localhost/notes-web     0.1.0       71b442015094  43 seconds ago      187 MB
localhost/notes-api     0.1.0       70cfecc8196f  About a minute ago  11.9 MB

localhost/ ist Podmans Präfix für Images ohne Registry. Den --mount=type=secret in notes-web überspringt Podman ohne Fehler, wenn kein Secret npmrc übergeben wird. image prune löscht nur die namenlosen Zwischen-Images (<none>) deines Users.

Fortschritt speichern? Kostenlos registrieren

Drill 5: notes-api starten

podman run -d --name notes-api -p 127.0.0.1:8080:8080 \
  -e NOTES_API_KEY=lab-api-key-123 localhost/notes-api:0.1.0
sleep 3
podman ps --format '{{.Names}}\t{{.Status}}\t{{.Ports}}'
curl -s 127.0.0.1:8080/version; echo
curl -s -X POST 127.0.0.1:8080/notes -H 'X-API-Key: lab-api-key-123' \
  -H 'Content-Type: application/json' -d '{"text":"Tag 1 mit Podman"}'; echo
podman logs notes-api

Erwartet (gekürzt):

d5bd47739ed5…
notes-api   Up 3 seconds (healthy)  127.0.0.1:8080->8080/tcp
0.1.0
{"id":"268d5866-…","text":"Tag 1 mit Podman"}
time=… level=INFO msg="api key loaded" source=env
time=… level=INFO msg="store ready" store=memory
time=… level=INFO msg=listening addr=:8080 version=0.1.0 pid=1

(healthy) kommt aus dem HEALTHCHECK im Image. Ohne Daemon braucht Podman jemanden, der den Check regelmäßig ausführt – das ist ein systemd-Timer deines Users:

id=$(podman inspect -f '{{.Id}}' notes-api)
systemctl --user list-timers --no-pager | grep -c "$id"
podman healthcheck run notes-api && echo "gesund"
podman exec notes-api sh; echo "Exit: $?"

Erwartet:

1
gesund
Error: crun: executable file `sh` not found in $PATH: No such file or directory: OCI
runtime attempted to invoke a command that was not found
Exit: 127

notes-api ist ein scratch-Image ohne Shell. exec kann nur starten, was im Image liegt.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Rootful gegen rootless

sudo podman ist ein komplett eigener Podman – mit eigenem Speicher:

podman images --format '{{.Repository}}:{{.Tag}}' | grep nginx
sudo podman images
podman info --format '{{.Store.GraphRoot}}'
sudo podman info --format '{{.Store.GraphRoot}}'

Erwartet:

docker.io/library/nginx:1.30.6-alpine
REPOSITORY  TAG         IMAGE ID    CREATED     SIZE
/home/ubuntu/.local/share/containers/storage
/var/lib/containers/storage

Root sieht deine Images nicht, und du siehst seine nicht. Derselbe nginx rootful:

sudo podman run -d --name web-root -p 127.0.0.1:81:80 \
  docker.io/library/nginx:1.30.6-alpine
sudo podman top web-root user huser args
sudo podman inspect web-root --format '{{.NetworkSettings.IPAddress}}'
curl -sI http://127.0.0.1:81 | head -1

Erwartet (gekürzt):

Trying to pull docker.io/library/nginx:1.30.6-alpine...
…
6a40e9e5dfc1…
USER        HUSER       COMMAND
root        root        nginx: master process nginx -g daemon off;
nginx       messagebus  nginx: worker process
nginx       messagebus  nginx: worker process
10.88.0.2
HTTP/1.1 200 OK
  • Rootful ist root im Container echtes root auf dem Host. Und UID 101 ist auf Ubuntu zufällig messagebus – ein Ausbruch landete bei einem echten Systemuser.
  • Rootful bekommt der Container eine IP in der Bridge podman0 (10.88.0.0/16), und Port 81 ist kein Problem. Rootless geht das so nicht (Tag 2).

Aufräumen – rootful bleibt im Buch die Ausnahme:

sudo podman rm -f web-root
sudo podman rmi docker.io/library/nginx:1.30.6-alpine

Erwartet (gekürzt):

web-root
Untagged: docker.io/library/nginx:1.30.6-alpine
Deleted: 88f52f3d58a5…

Fortschritt speichern? Kostenlos registrieren

Drill 7: podman info

podman info sagt dir, wie dein Podman eingerichtet ist. Die wichtigsten Felder:

podman info --format json | jq '{rootless: .host.security.rootless,
  arch: .host.arch, cgroup: .host.cgroupVersion, runtime: .host.ociRuntime.name,
  net: .host.networkBackend, rootlessNet: .host.rootlessNetworkCmd,
  driver: .store.graphDriverName, graphRoot: .store.graphRoot,
  runRoot: .store.runRoot, uidmap: .host.idMappings.uidmap}'

Erwartet:

{
  "rootless": true,
  "arch": "arm64",
  "cgroup": "v2",
  "runtime": "crun",
  "net": "netavark",
  "rootlessNet": "pasta",
  "driver": "overlay",
  "graphRoot": "/home/ubuntu/.local/share/containers/storage",
  "runRoot": "/run/user/1000/containers",
  "uidmap": [
    {
      "container_id": 0,
      "host_id": 1000,
      "size": 1
    },
    {
      "container_id": 1,
      "host_id": 100000,
      "size": 65536
    }
  ]
}
Feld Bedeutung
runtime crun startet die Container (statt runc)
net, rootlessNet netavark für Netze, pasta für das rootless Netz
graphRoot Images und Container-Layer deines Users
runRoot Laufzeitdaten im RAM, weg nach dem Neustart
uidmap UID 0 → 1000, UID 1… → 100000… (Tag 2)

Konfiguriert wird das über Dateien in /etc/containers/ (System) und ~/.config/containers/ (User): registries.conf, storage.conf, containers.conf.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Die drei Images sind gebaut:

cd ~/ct-lab/tag01
podman images --filter reference='localhost/notes-*:0.1.0' --format '{{.Repository}}'

Erwartet:

localhost/notes-worker
localhost/notes-web
localhost/notes-api

Der Healthcheck steckt im Image, der Container ist healthy:

podman image inspect localhost/notes-api:0.1.0 --format '{{.Config.Healthcheck.Test}}'
podman ps --filter name=notes-api --format '{{.Status}}'

Erwartet (Zeit weicht ab):

[CMD /notes-api healthcheck]
Up 19 seconds (healthy)

/version liefert 0.1.0:

curl -s 127.0.0.1:8080/version; echo

Erwartet:

0.1.0

Rootful ist aufgeräumt, der eigene Alias entfernt:

sudo podman ps -aq | wc -l
ls ~/.config/containers/registries.conf.d/

Erwartet: kein rootful Container, der Ordner ist leer.

0

Challenge

Bring localhost/notes-api:0.1.0 in den Speicher von root, ohne neu zu bauen und ohne Registry. Die Image-ID muss rootless und rootful gleich sein.

Hinweis: podman save schreibt ein Image als Archiv auf stdout, podman load liest es von stdin.

Lösung

podman save localhost/notes-api:0.1.0 | sudo podman load
podman images --format '{{.ID}}' localhost/notes-api:0.1.0
sudo podman images --format '{{.ID}} {{.Repository}}:{{.Tag}}'

Erwartet (gekürzt):

Copying blob sha256:bd1c1408ba45…
Copying blob sha256:eac76113fc08…
Copying config sha256:70cfecc8196f…
Writing manifest to image destination
Loaded image: localhost/notes-api:0.1.0
70cfecc8196f
70cfecc8196f localhost/notes-api:0.1.0

Gleiche ID heißt gleiche Konfiguration und gleiche Layer. Fürs Kopieren zwischen Hosts gibt es podman image scp, das intern genau so arbeitet. Zurück zum Stand des Tages:

sudo podman rmi localhost/notes-api:0.1.0
podman rm -f notes-api

Erwartet:

Untagged: localhost/notes-api:0.1.0
Deleted: 70cfecc8196f…
notes-api

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Rootless ist für Entwickler und die meisten Dienste der richtige Standard. Rootful nur, wo es nicht anders geht (Ports < 1024 ohne Sysctl, Geräte, bestimmte Netze).
  • unqualified-search-registries bleibt in Produktion leer. Aliase, wenn überhaupt, zentral in /etc/containers/registries.conf.d/ verteilen.
  • Statt docker.io direkt: ein interner Pull-Through-Cache oder Spiegel per [[registry]]-Eintrag mit mirror in registries.conf – Rate-Limits und Ausfälle von Docker Hub treffen dich dann nicht.
  • Images mit HEALTHCHECK im Docker-Format bauen oder den Healthcheck beim Start angeben (--health-cmd, Quadlet HealthCmd=, Tag 3).
  • Ubuntu-LTS liefert Podman-Updates nur als Sicherheits-Backports. Wer neue Funktionen braucht, plant den Wechsel auf die nächste LTS, statt Fremdpakete zu mischen.