Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 6: containerd – ctr, nerdctl, buildctl

Ziel: containerd und BuildKit als Systemdienste starten, Images und Container mit ctr auf unterster Ebene anfassen, notes mit nerdctl und nerdctl compose betreiben und mit buildctl direkt bauen. · Dauer: ca. 90 min · Voraussetzung: Tag 5

Briefing

  • containerd ist die Laufzeit unter Docker und Kubernetes: ein Daemon, der Images, Snapshots und Container verwaltet. Anders als Podman braucht er einen Dienst.
  • ctr ist der Debug-Client von containerd – nackt, ohne Komfort. nerdctl ist der Docker-kompatible Client, buildctl spricht mit dem Build-Daemon BuildKit.
  • containerd trennt alles in Namespaces: default für ctr und nerdctl, k8s.io für Kubernetes, buildkit für BuildKit.
  • Podman und containerd haben getrennte Speicher. Ein Image wandert nur per Archiv hinüber: podman save | sudo ctr images import -.
 ubuntu (rootless)                     root (Systemdienste)
 ┌────────────────────────────┐        ┌───────────────────────────────────────────┐
 │ podman, buildah, ko        │ save/  │ ctr ─────┐                                │
 │ ~/.local/share/containers  │ import │ nerdctl ─┼► containerd.service ► runc     │
 │                            │───────►│          │  /var/lib/containerd           │
 └────────────────────────────┘        │ buildctl ─► buildkit.service              │
                                       │             /var/lib/buildkit             │
                                       └───────────────────────────────────────────┘

Drill 1: nerdctl-full installieren, containerd starten

containerd, nerdctl, BuildKit, runc und die CNI-Plugins gibt es als ein Bündel: nerdctl-full. An Tag 0 hast du es schon nach /usr/local ausgepackt. Einzeln sieht das so aus:

source ~/ct-lab/setup/env.sh
mkdir -p ~/ct-lab/tag06 && cd ~/ct-lab/tag06
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag05/notes/." .
mkdir -p /tmp/dl && cd /tmp/dl
V=2.4.2
BASE=https://github.com/containerd/nerdctl/releases/download/v$V
curl -fsSLO "$BASE/nerdctl-full-$V-linux-arm64.tar.gz"
curl -fsSLO "$BASE/SHA256SUMS"
grep "nerdctl-full-$V-linux-arm64" SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
tar -tzf "nerdctl-full-$V-linux-arm64.tar.gz" | grep -E 'system/.+|^bin/(ctr|runc)$'
sudo tar -C /usr/local -xzf "nerdctl-full-$V-linux-arm64.tar.gz"
cd ~/ct-lab/tag06 && rm -rf /tmp/dl
nerdctl --version; containerd --version | cut -d' ' -f1,3; ctr --version
buildctl --version | cut -d' ' -f1,3; runc --version | head -1

Erwartet (gekürzt, der Download ist knapp 300 MB):

fe0ef0e9840ee8932640e6058f84b7fa98050f9726e44af44883a5b804ae830e  nerdctl-full-2.4.2-l…
nerdctl-full-2.4.2-linux-arm64.tar.gz: OK
bin/ctr
bin/runc
lib/systemd/system/buildkit.service
lib/systemd/system/containerd.service
lib/systemd/system/stargz-snapshotter.service
nerdctl version 2.4.2
containerd v2.4.2
ctr github.com/containerd/containerd/v2 v2.4.2
buildctl v0.34.1
runc version 1.5.2

Die Prüfsumme ist dieselbe wie in tools.lock. tar -C /usr/local entpackt alles an seinen Platz: Programme nach bin/, CNI-Plugins nach libexec/cni/, drei systemd-Units nach lib/systemd/system/. Das Verzeichnis kennt systemd schon:

systemd-analyze unit-paths | grep local
sudo systemctl daemon-reload
sudo systemctl enable --now containerd
systemctl status containerd --no-pager | sed -n 1,3p
ls -l /run/containerd/containerd.sock
ls /etc/containerd; containerd config default | sed -n 1,3p

Erwartet (gekürzt):

/usr/local/lib/systemd/system
Created symlink '/etc/systemd/system/multi-user.target.wants/containerd.service' → …
● containerd.service - containerd container runtime
     Loaded: loaded (/usr/local/lib/systemd/system/containerd.service; enabled; preset:…
     Active: active (running) since Fri 2026-10-30 20:20:19 UTC; 47ms ago
srw-rw---- 1 root root 0 Oct 30 20:20 /run/containerd/containerd.sock
ls: cannot access '/etc/containerd': No such file or directory
version = 4
root = '/var/lib/containerd'
state = '/run/containerd'
  • Der Socket gehört root, Modus 0660 – darum steht vor jedem ctr und nerdctl heute ein sudo.
  • Eine config.toml gibt es nicht: containerd läuft mit eingebauten Standardwerten, Daten unter /var/lib/containerd. containerd config default zeigt sie.

Fortschritt speichern? Kostenlos registrieren

Drill 2: ctr – Namespaces und Images

Steckbrief ctr
Aufgabe containerd direkt bedienen: Images, Container, Tasks, Snapshots
Besonderheit Debug-Werkzeug, keine Netze, keine Ports, keine Short-Names
Projekt containerd.io, github.com/containerd/containerd
Version im Buch v2.4.2 (aus nerdctl-full)
sudo ctr ns ls
sudo ctr images pull nginx:1.30.6-alpine; echo "Exit: $?"
sudo ctr images pull docker.io/library/nginx:1.30.6-alpine 2>&1 | tail -2
sudo ctr ns ls
sudo ctr images ls -q

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

NAME LABELS
ctr: failed to resolve image: parse "dummy://nginx:1.30.6-alpine": invalid port ":1.3…
Exit: 1
application/vnd.oci.image.index.v1+json sha256:0e52bd054126cdc040b1276c0af347aeb02a41…
Completed pull from OCI Registry (docker.io/library/nginx:1.30.6-alpine)    elapsed: 7.2 s…
NAME    LABELS
default
docker.io/library/nginx:1.30.6-alpine
  • ctr ergänzt nichts: kein docker.io, kein library/. nginx:1.30.6-alpine liest es als Rechner nginx mit Port 1.30.6-alpine.
  • Der Index-Digest 0e52bd054126… ist derselbe wie bei Podman an Tag 1 – gleiche Registry, gleiches Image, nur ein anderer Speicher.
  • Der Namespace default entsteht beim ersten Objekt. Ohne -n arbeitet ctr dort.

Fortschritt speichern? Kostenlos registrieren

Drill 3: ctr run – Container, Tasks und Snapshots

containerd unterscheidet zwei Dinge, die Docker „Container” nennt: Der Container ist die Beschreibung (Image, Konfiguration, Snapshot), der Task der laufende Prozess dazu.

I=docker.io/library/nginx:1.30.6-alpine
sudo ctr run -d "$I" web
sudo ctr containers ls
sudo ctr tasks ls
sudo ctr tasks exec --exec-id e1 web nginx -v
sudo ctr snapshots ls | grep web

Erwartet (gekürzt):

CONTAINER    IMAGE                                    RUNTIME
web          docker.io/library/nginx:1.30.6-alpine    io.containerd.runc.v2
TASK    PID       STATUS
web     135129    RUNNING
nginx version: nginx/1.30.6
web    sha256:3b40866184a698343e4e4669f485c61c12afbf74c3cec956c4afafaae96e97c5 Active
  • exec braucht eine eigene --exec-id: Jeder zusätzliche Prozess ist ein eigener Eintrag im Task.
  • Der Snapshot web ist die beschreibbare Schicht über den Image-Layern (bei overlayfs ein upperdir). Elternteil ist der letzte Image-Layer.

Netz? ctr run legt einen leeren Network Namespace an – nur lo, keine Ports:

sudo ctr run --rm "$I" net-test ip -o addr | cut -c1-48

Erwartet:

1: lo    inet 127.0.0.1/8 scope host lo\
1: lo    inet6 ::1/128 scope host \

Für Netze und Ports bräuchte ctr CNI per Hand – das erledigt nerdctl (Drill 5). Aufräumen geht in drei Schritten: Task stoppen, Task löschen, Container löschen.

sudo ctr tasks kill web; sleep 2
sudo ctr tasks ls
sudo ctr tasks rm web
sudo ctr containers rm web
sudo ctr snapshots ls | grep -c web

Erwartet:

TASK    PID       STATUS
web     135129    STOPPED
0

Mit dem Container verschwindet sein Snapshot. Das Image bleibt.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Podman-Images nach containerd

Die notes-Images liegen in Podmans Speicher deines Users, containerd sieht sie nicht. podman save schreibt ein Archiv, ctr images import liest es – über eine Pipe:

podman save localhost/notes-api:0.2.0 | sudo ctr images import -
sudo ctr images ls -q
podman image inspect localhost/notes-api:0.2.0 --format '{{.Id}}' | cut -c1-12
sudo ctr images inspect localhost/notes-api:0.2.0 | sed -n 4,6p | cut -c1-88

Erwartet (gekürzt):

localhost/notes api:0.2.0                   saved
application/vnd.docker.distribution.manifest.v2+json sha256:cea8daf0f92891ea59719b6e…
Importing   elapsed: 1.8 s  total:   0.0 B  (0.0 B/s)
docker.io/library/nginx:1.30.6-alpine
localhost/notes-api:0.2.0
3cac2607c210
└── application/vnd.docker.distribution.manifest.v2+json @sha256:cea8daf0f92891ea5971…
    ├── application/vnd.docker.container.image.v1+json @sha256:3cac2607c2107e9249e036…
    └── application/vnd.docker.image.rootfs.diff.tar @sha256:f1fca665eac4fa423f4d0c9…

Podmans Image-ID ist der Digest der Config (3cac2607…). In containerd hängt dieselbe Config unter einem Manifest – das Image ist bitgenau angekommen. Das sudo steht nur vor ctr: podman save liest weiter deinen rootless Speicher.

Fortschritt speichern? Kostenlos registrieren

Drill 5: nerdctl – Docker-Befehle für containerd

Steckbrief nerdctl
Aufgabe Docker-kompatibles CLI für containerd: run, ps, build, compose
Besonderheit CNI-Netze, Namespaces, Lazy Pulling, Image-Verschlüsselung, rootless
Projekt github.com/containerd/nerdctl
Version im Buch 2.4.2 (nerdctl-full)
sudo nerdctl namespace ls
sudo nerdctl images
sudo nerdctl run -d --name web -p 127.0.0.1:8081:80 \
  docker.io/library/nginx:1.30.6-alpine
sudo nerdctl ps
curl -sI 127.0.0.1:8081 | head -2
sudo ctr containers ls

Erwartet (gekürzt):

NAME       CONTAINERS    IMAGES    VOLUMES    LABELS
default    0             2         0
IMAGE                        ID              DISK USAGE    CONTENT SIZE    EXTRA
localhost/notes-api:0.2.0    cea8daf0f928    23.8MB        11.9MB
nginx:1.30.6-alpine          0e52bd054126    261MB         195MB
61386ca7a7cd80269011bf0267a9d4d0132bbaeee58901d4a136b1324d87f464
CONTAINER ID    IMAGE                                    COMMAND                   …
61386ca7a7cd    docker.io/library/nginx:1.30.6-alpine    "/docker-entrypoint.…"    …
HTTP/1.1 200 OK
Server: nginx/1.30.6
CONTAINER                                                           IMAGE          …
61386ca7a7cd80269011bf0267a9d4d0132bbaeee58901d4a136b1324d87f464    docker.io/libr…
  • nerdctl und ctr teilen den Namespace default: Das von ctr geholte nginx und das importierte notes-api sind da, der nerdctl-Container erscheint in ctr containers ls.
  • nerdctl kürzt docker.io/library/ in der Anzeige wie Docker – und ergänzt es beim Holen. nerdctl images zeigt als ID den Manifest-Digest, nicht die Config.

Das Netz kommt aus CNI, wie bei Docker als Bridge:

sudo nerdctl network ls
ip -br addr show nerdctl0
sudo nerdctl inspect web --format '{{.NetworkSettings.IPAddress}}'
sudo nerdctl rm -f web

Erwartet:

NETWORK ID      NAME      FILE
17f29b073143    bridge    /etc/cni/net.d/nerdctl-bridge.conflist
                host
                none
nerdctl0         UP             10.4.0.1/24 fe80::7cf7:baff:fe2e:5fcf/64
10.4.0.2
web

Die Bridge nerdctl0 (10.4.0.0/24) ist das Gegenstück zu docker0; die Konfiguration schreibt nerdctl beim ersten Start nach /etc/cni/net.d/.

Fortschritt speichern? Kostenlos registrieren

Drill 6: nerdctl compose mit notes

Dieselbe compose.yaml wie an Tag 4, jetzt auf containerd. Erst muss der Quadlet-Pod die Ports 8080 und 3000 freigeben (3 s warten, Tag 4), dann wandern die drei Images in einem Archiv hinüber:

systemctl --user stop notes-pod.service && sleep 3
podman save -m localhost/notes-api:0.1.0 localhost/notes-web:0.1.0 \
  localhost/notes-worker:0.1.0 | sudo ctr images import - >/dev/null
sudo nerdctl images --format '{{.Repository}}:{{.Tag}}' | grep notes
sudo nerdctl volume create notes-pgdata

Erwartet:

localhost/notes-worker:0.1.0
localhost/notes-web:0.1.0
localhost/notes-api:0.1.0
localhost/notes-api:0.2.0
notes-pgdata

-m (multi-image-archive) packt mehrere Images in ein docker-archive. Das Volume notes-pgdata ist in compose.yaml als external markiert – containerd hat sein eigenes, leeres. Jetzt starten:

sudo nerdctl compose up -d 2>&1 | grep -E 'warn' | cut -c1-88
sleep 30
sudo nerdctl compose ps -a
sudo nerdctl exec notes-db-1 ps -o pid,time,args | head -2
sudo journalctl -k --since '-2 min' | grep -m1 DENIED | grep -o 'profile=.*' \
  | cut -c1-88

Erwartet (gekürzt):

time="…" level=warning msg="service db: healthcheck: CMD exec form is not supported,…
time="…" level=warning msg="Ignoring: service migrate: depends_on: db: condition ser…
time="…" level=warning msg="Ignoring: service api: depends_on: migrate: condition se…
…
NAME               IMAGE                                     …  SERVICE    STATUS
notes-api-1        localhost/notes-api:0.1.0                 …  api        Exited (1) …
notes-migrate-1    localhost/notes-api:0.1.0                 …  migrate    Exited (1) …
notes-web-1        localhost/notes-web:0.1.0                 …  web        running
notes-worker-1     localhost/notes-worker:0.1.0              …  worker     running
notes-db-1         docker.io/library/postgres:18.6-alpine    …  db         running
PID   TIME  COMMAND
    1  0:33 gosu postgres /usr/local/bin/docker-entrypoint.sh postgres
profile="nerdctl-default" pid=182735 comm="gosu" requested_mask="send" denied_mask="se…

Zwei Probleme auf einmal:

  • nerdctl compose ignoriert condition: in depends_on und sagt es auch. migrate und api starten sofort, finden keine Datenbank und beenden sich.
  • Die Datenbank kommt nie hoch: gosu hängt mit voller CPU. Das AppArmor-Profil nerdctl-default verbietet ihm auf Ubuntu 26.04 ein Signal an die eigenen Threads, das Go beim Wechsel der User-ID braucht. Podman nutzt ein anderes Profil – dort lief Postgres an Tag 2–4.

Lösung im Labor: eine Ergänzungsdatei, die das Profil für db abschaltet, und ein Start in zwei Stufen:

cat > compose.nerdctl.yaml <<'EOF'
# compose.nerdctl.yaml – Stand Ende Tag 6
# Ergänzung zu compose.yaml für nerdctl compose (containerd) auf Ubuntu 26.04:
# Das AppArmor-Profil nerdctl-default verbietet gosu (Postgres-Entrypoint) ein Signal
# an die eigenen Threads, postgres startet nie. Nur im Labor: Profil für db aus.
services:
  db:
    security_opt:
      - apparmor=unconfined
EOF
F="-f compose.yaml -f compose.nerdctl.yaml"
sudo nerdctl compose $F down 2>/dev/null
sudo nerdctl compose $F up -d db 2>/dev/null
until sudo nerdctl inspect -f '{{.State.Health.Status}}' notes-db-1 2>/dev/null \
  | grep -q '^healthy'; do sleep 1; done; echo "db healthy"
sudo nerdctl compose $F up -d 2>/dev/null
sleep 3
sudo nerdctl compose ps -a

Erwartet (gekürzt):

db healthy
NAME               IMAGE                                     …  SERVICE    STATUS
notes-api-1        localhost/notes-api:0.1.0                 …  api        running   …
notes-worker-1     localhost/notes-worker:0.1.0              …  worker     running
notes-web-1        localhost/notes-web:0.1.0                 …  web        running   …
notes-migrate-1    localhost/notes-api:0.1.0                 …  migrate    Exited (0) …
notes-db-1         docker.io/library/postgres:18.6-alpine    …  db         running
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 6 mit nerdctl compose"}'; echo
curl -s 127.0.0.1:3000/api/notes; echo
sudo nerdctl inspect -f '{{.State.Health.Status}}' notes-api-1
sudo nerdctl compose $F down 2>&1 | tail -1
systemctl --user start notes-pod.service

Erwartet (gekürzt):

0.1.0
{"id":"de8ce9aa-…","text":"Tag 6 mit nerdctl compose"}
[{"id":"de8ce9aa-…","text":"Tag 6 mit nerdctl compose"}]
healthy
time="…" level=info msg="Removing network notes_default"

Nur eine Notiz: Das Volume in containerd ist ein anderes als das von Podman (Drill 8). Der HEALTHCHECK aus dem Image wirkt auch unter nerdctl.

Sicherheit: apparmor=unconfined nimmt dem Container eine Schutzschicht. In Produktion schreibt man stattdessen ein eigenes Profil (nerdctl apparmor) oder nimmt ein Postgres-Image, das ohne gosu direkt als User startet.

Fortschritt speichern? Kostenlos registrieren

Drill 7: BuildKit – nerdctl build und buildctl

Steckbrief buildctl
Aufgabe Client für den Build-Daemon BuildKit (buildkitd)
Besonderheit Frontends (Dockerfile u. a.), Cache-Export, Ausgabe als OCI-Archiv
Projekt github.com/moby/buildkit
Version im Buch v0.34.1 (nerdctl-full)

nerdctl build baut nicht selbst – es braucht buildkitd:

sudo nerdctl build -t localhost/notes-api:0.2.0 notes-api 2>&1 | tail -1 | cut -c1-88
sudo systemctl enable --now buildkit
sudo buildctl debug workers -v | grep -E '^ID|executor|namespace'

Erwartet (gekürzt):

time="…" level=fatal msg="no buildkit host is available, tried 2 candidates: failed …
Created symlink '/etc/systemd/system/multi-user.target.wants/buildkit.service' → …
ID:     rhhdbavuhzrnk9xvsgrqbanzu
    org.mobyproject.buildkit.worker.executor:       oci
ID:     x2p7whwk7om974z41wou8k9l7
    org.mobyproject.buildkit.worker.containerd.namespace:   buildkit
    org.mobyproject.buildkit.worker.executor:       containerd

buildkitd bringt zwei Worker mit: oci (eigener runc, Daten unter /var/lib/buildkit) und containerd (Namespace buildkit). Benutzt wird der erste. Jetzt klappt der Build:

sudo nerdctl build -t localhost/notes-api:0.2.0 --build-arg VERSION=0.2.0 \
  notes-api 2>&1 | grep -E '^#[0-9]+ (\[final|exporting (manifest|config))'
sudo nerdctl images --format '{{.Repository}}:{{.Tag}} {{.ID}}' | grep 0.2.0
sudo nerdctl image inspect localhost/notes-api:0.2.0 --format '{{.Id}}' | cut -c1-19

Erwartet (gekürzt, ca. 1,5 Minuten):

#13 [final 2/2] COPY --link --from=build --chmod=555 /out/notes-api /notes-api
#14 exporting manifest sha256:46c20b4c7047a1e3a5b968c4de5e3e62fed5a4cc34ccac330706e9…
#14 exporting config sha256:9cedc11a94a5d11560e7a591c223291f1c1644ccf4e4c62925712a1d…
localhost/notes-api:0.2.0 46c20b4c7047
sha256:9cedc11a94a5

nerdctl lässt BuildKit ein Archiv erzeugen und importiert es selbst in containerd – der Tag 0.2.0 zeigt jetzt auf den BuildKit-Build (Config 9cedc11a…), nicht mehr auf den Buildah-Import. # syntax=docker/dockerfile:1 im Dockerfile wertet BuildKit aus: Es lädt das Dockerfile-Frontend als Image.

buildctl spricht BuildKit direkt an. Statt eines Image-Namens sagst du ihm, welches Frontend den Bau beschreibt, welche lokalen Ordner es lesen darf und wohin das Ergebnis geht:

mkdir -p out
sudo buildctl build --frontend dockerfile.v0 \
  --local context=notes-api --local dockerfile=notes-api \
  --opt build-arg:VERSION=0.2.0 \
  --output type=oci,dest=out/notes-api-oci.tar,name=localhost/notes-api:0.2.0-buildctl \
  --export-cache type=local,dest=out/buildcache 2>&1 \
  | grep -E 'exporting manifest|writing cache image'
ls -lh out/notes-api-oci.tar; ls out/buildcache
tar -xOf out/notes-api-oci.tar index.json \
  | jq -c '.manifests[] | {mediaType, ref: .annotations["io.containerd.image.name"]}'

Erwartet (gekürzt):

#14 exporting manifest sha256:46c20b4c7047a1e3a5b968c4de5e3e62fed5a4cc34ccac330706e9…
#15 writing cache image manifest sha256:704ae5aaaa8c7afdcb7cbd530eb659001d6d8cd3a0792…
-rw-rw-rw- 1 root root 4.3M Oct 30 20:52 out/notes-api-oci.tar
blobs  cache.lock  index.json  ingest  oci-layout
{"mediaType":"application/vnd.oci.image.manifest.v1+json","ref":"localhost/notes-api:…
  • --local context=… und --local dockerfile=… sind die beiden Ordner, die BuildKit lesen darf. Build-Args heißen --opt build-arg:NAME=wert.
  • Gleicher Manifest-Digest 46c20b4c… wie bei nerdctl build: Alle Schritte kamen aus dem Cache des Daemons.
  • --export-cache type=local schreibt diesen Cache als OCI-Layout auf die Platte – für CI-Runner, die jedes Mal leer starten.

Wie viel der Cache wert ist, zeigt ein leerer Daemon:

sudo buildctl prune --all >/dev/null
time (sudo buildctl build --frontend dockerfile.v0 --local context=notes-api \
  --local dockerfile=notes-api --opt build-arg:VERSION=0.2.0 \
  --output type=oci,dest=/dev/null \
  --import-cache type=local,src=out/buildcache 2>&1 | grep -c CACHED)

Erwartet (gekürzt):

6

real    0m4.913s
…

Mit Cache 5 Sekunden statt anderthalb Minuten – sechs Schritte kamen aus out/buildcache.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Zwei Welten – Podman und containerd

Derselbe Name, zwei Images:

podman images --format '{{.Repository}}:{{.Tag}} {{.ID}}' localhost/notes-api:0.2.0
sudo nerdctl image inspect localhost/notes-api:0.2.0 --format '{{.Id}}' | cut -c1-19
podman volume inspect notes-pgdata --format '{{.Mountpoint}}'
sudo nerdctl volume inspect notes-pgdata --format '{{.Mountpoint}}'
sudo du -sh /var/lib/containerd /var/lib/buildkit /var/lib/nerdctl

Erwartet (gekürzt):

localhost/notes-api:0.2.0 3cac2607c210
sha256:9cedc11a94a5
/home/ubuntu/.local/share/containers/storage/volumes/notes-pgdata/_data
/var/lib/nerdctl/1935db59/volumes/default/notes-pgdata/_data
1.2G    /var/lib/containerd
59M /var/lib/buildkit
47M /var/lib/nerdctl
Podman (rootless) containerd (root)
Images ~/.local/share/containers/storage /var/lib/containerd
Volumes …/storage/volumes /var/lib/nerdctl/<id>/volumes
Build-Cache im selben Speicher /var/lib/buildkit
Brücke podman save, podman load ctr images import, nerdctl save

Auch ein Archiv von buildctl liest Podman direkt:

podman load -i out/notes-api-oci.tar | tail -1
podman images --format '{{.Repository}}:{{.Tag}} {{.ID}}' \
  --filter reference='localhost/notes-api:0.2.0*'

Erwartet:

Loaded image: localhost/notes-api:0.2.0-buildctl
localhost/notes-api:0.2.0-buildctl 9cedc11a94a5
localhost/notes-api:0.2.0-buildah 666976c1aaff
localhost/notes-api:0.2.0 3cac2607c210
localhost/notes-api:0.2.0-ko 2acfdf58f9a3

Gleiche Config 9cedc11a… wie in containerd – ein OCI-Archiv ist das gemeinsame Format.

Rootless containerd gibt es auch: containerd-rootless-setuptool.sh install richtet containerd als User-Dienst mit RootlessKit ein. Ubuntu 26.04 blockt das zuerst:

containerd-rootless-setuptool.sh check 2>&1 | grep -E 'apparmor|ERROR' | cut -c1-88

Erwartet (gekürzt):

time="…" level=warning msg="[rootlesskit:parent] This error might have happened becau…
time="…" level=warning msg="[rootlesskit:parent] Hint: try running the following comm…
[ERROR] RootlessKit failed, see the error messages and https://rootlesscontaine.rs/ge…

apparmor_restrict_unprivileged_userns=1 verbietet unbekannten Programmen User Namespaces; das Skript schlägt ein AppArmor-Profil für /usr/local/bin/rootlesskit vor. Im Buch bleibt containerd rootful. Feierabend für die Dienste – sie belegen RAM und brauchst du erst wieder in der Challenge:

sudo systemctl disable --now containerd buildkit
systemctl is-active containerd buildkit

Erwartet (gekürzt):

Removed '/etc/systemd/system/multi-user.target.wants/containerd.service'.
Removed '/etc/systemd/system/multi-user.target.wants/buildkit.service'.
inactive
failed

failed bei buildkit ist kein Fehler im Labor: buildkitd endet beim Stoppen mit Exit-Code 1, systemd merkt sich das. sudo systemctl reset-failed buildkit setzt den Zustand zurück. Die Daten unter /var/lib/containerd, /var/lib/buildkit und /var/lib/nerdctl bleiben liegen.

Fortschritt speichern? Kostenlos registrieren

Drill 9: BuildKit eigenständig – auf dem Mac mit Lima

BuildKit braucht weder Docker noch containerd auf deinem Rechner: Der Client buildctl spricht über einen Socket mit einem buildkitd, der irgendwo laufen kann. Auf dem Mac startet Lima dafür eine kleine Linux-VM.

Steckbrief Lima
Aufgabe Linux-VMs auf macOS mit Datei- und Socket-Weiterleitung
Besonderheit Vorlagen per template://…; template://buildkit startet buildkitd rootless
Projekt github.com/lima-vm/lima (Apache-2.0)
Version im Buch 2.2.1, dazu buildkit 0.34.1 (beide Homebrew)

Auf dem Mac, nicht in der VM ct-lab. Das Homebrew-Paket buildkit bringt nur den Client buildctl, der Daemon läuft in der Lima-VM:

brew install buildkit lima
limactl start --name=buildkit --cpus=2 --memory=2 --disk=20 template://buildkit

Die Vorlage installiert in einer Ubuntu-VM containerd und BuildKit für den normalen User und leitet den Socket auf den Mac weiter. Zum Schluss gibt limactl den Hinweis der Vorlage aus (sinngemäß):

To run `buildkit` on the host (assumes buildctl is installed), run the following
commands:
-------
export BUILDKIT_HOST="unix:///Users/…/.lima/buildkit/sock/buildkitd.sock"
buildctl debug workers
-------

2 GiB RAM reichen für kleine Images; für größere Builds mit Go, Java oder Node.js gib der VM mehr (--memory=4). BUILDKIT_HOST sagt buildctl, wo der Daemon wartet – dauerhaft in ~/.zshrc (wer seine Dotfiles mit chezmoi verwaltet, trägt es dort ein):

echo 'export BUILDKIT_HOST="unix://$HOME/.lima/buildkit/sock/buildkitd.sock"' \
  >> ~/.zshrc
source ~/.zshrc
buildctl --version
buildctl debug workers

Erwartet (gekürzt, in der VM ct-lab gegen einen eigenständigen buildkitd geprüft):

buildctl github.com/moby/buildkit v0.34.1 f5b59a1f2fb25a0cb7072c398cab9aed7835da4e
ID              PLATFORMS
fo2svu2b6g2pjez8jwnntz8bv   linux/amd64,linux/amd64/v2,linux/amd64/v3,linux/386

Mindestens ein Worker – auf einem Mac mit Apple Silicon steht dort linux/arm64. Jetzt ein erstes Image, ganz ohne Docker:

mkdir -p ~/buildkit-test/myapp && cd ~/buildkit-test/myapp
cat > Dockerfile <<'EOF'
# myapp/Dockerfile – Stand Ende Tag 6: kleinstes Testimage für buildctl
FROM docker.io/library/alpine:3.24
CMD ["echo", "gebaut von BuildKit ohne Docker"]
EOF
buildctl build --frontend dockerfile.v0 --local context=. --local dockerfile=. \
  --output type=oci,dest=myapp.tar,name=localhost/myapp:0.1.0 2>&1 | tail -4
ls -lh myapp.tar

Erwartet (gekürzt):

#5 exporting to oci image format
#5 sending tarball
#5 sending tarball 0.2s done
#5 DONE 0.7s
-rw-rw-rw- 1 ubuntu ubuntu 3.7M Nov  1 12:48 myapp.tar

Der wichtigste Unterschied zu Docker: BuildKit ist nur eine Build-Engine. Es gibt kein docker images und kein docker run; das Ergebnis landet als OCI-Archiv auf der Platte oder in einer Registry. Ausführen kann es eine Runtime – etwa Podman in der VM ct-lab:

multipass transfer myapp.tar ct-lab:/home/ubuntu/ct-lab/tag06/
multipass exec ct-lab -- podman load -q -i /home/ubuntu/ct-lab/tag06/myapp.tar
multipass exec ct-lab -- podman run --rm localhost/myapp:0.1.0

Erwartet:

Loaded image: localhost/myapp:0.1.0
gebaut von BuildKit ohne Docker

name= im --output hat dem Archiv den Image-Namen mitgegeben, den podman load übernimmt. Die Lima-VM belegt Speicher, solange sie läuft:

limactl stop buildkit
limactl list
limactl start buildkit

limactl list zeigt Name, Status (Stopped/Running), CPUs, Speicher und Platte. Der Build-Cache liegt auf der Platte der VM und bleibt beim Stoppen erhalten.

Ab Tag 7, wenn die Lab-Registry läuft, schreibt BuildKit direkt dorthin: statt type=oci ein type=image mit push=true – Tags sind Versionen, nie latest. Den Login liest buildctl aus ~/.docker/config.json (Tag 7). Der Daemon muss die Registry erreichen und ihrer CA vertrauen. Die Registry der VM ct-lab lauscht nur auf 127.0.0.1, darum läuft buildkitd dafür eigenständig als Container in der VM – mit dem Netz des Hosts und dessen CA-Liste:

mkdir -p "$XDG_RUNTIME_DIR/bk"
podman run -d --name buildkitd --privileged --network host \
  -v "$XDG_RUNTIME_DIR/bk:/run/buildkit" \
  -v /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro \
  docker.io/moby/buildkit:v0.34.1
export BUILDKIT_HOST="unix://$XDG_RUNTIME_DIR/bk/buildkitd.sock"
buildctl build --frontend dockerfile.v0 --local context=. --local dockerfile=. \
  --output "type=image,name=$REG/lab/myapp:0.1.0,push=true" 2>&1 | tail -3 | cut -c1-80
crane ls "$REG/lab/myapp"

Erwartet (gekürzt):

#6 pushing manifest for registry.ct.lab:5000/lab/myapp:0.1.0@sha256:d85cecfb28e121…
#6 pushing manifest for registry.ct.lab:5000/lab/myapp:0.1.0@sha256:d85cecfb28e121…
#6 DONE 0.3s
0.1.0

Danach podman rm -f buildkitd – oder du lässt ihn als Build-Server für Tag 7 stehen.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

containerd und BuildKit sind gestoppt und deaktiviert:

cd ~/ct-lab/tag06
systemctl is-enabled containerd buildkit
systemctl is-active containerd buildkit

Erwartet (failed: buildkit endet beim Stopp mit Exit-Code 1, siehe oben):

disabled
disabled
inactive
failed

Die Daten von containerd liegen noch da:

sudo ls /var/lib/containerd/io.containerd.content.v1.content/blobs/sha256 | wc -l

Erwartet (Zahl weicht ab):

1319

OCI-Archiv und Build-Cache von buildctl:

tar -tf out/notes-api-oci.tar | grep index.json
ls out/buildcache

Erwartet (gekürzt):

index.json
blobs
cache.lock
index.json
ingest
oci-layout

Compose-Datei für nerdctl, das Image in Podman, der Quadlet-Pod:

grep apparmor compose.nerdctl.yaml
podman images --filter reference=localhost/notes-api:0.2.0-buildctl --format '{{.Tag}}'
systemctl --user is-active notes-pod.service

Erwartet:

      - apparmor=unconfined
0.2.0-buildctl
active

Challenge

Baue notes-api in Version 0.3.0 mit buildctl direkt in den Speicher von containerd – ohne Archiv auf der Platte – und starte es mit nerdctl auf 127.0.0.1:8081. Danach sind beide Dienste wieder aus.

Hinweis: Ein --output vom Typ docker schreibt mit dest=- auf stdout, und ctr images import - liest von stdin.

Lösung

cd ~/ct-lab/tag06
sudo systemctl start containerd buildkit
sudo buildctl build --frontend dockerfile.v0 --local context=notes-api \
  --local dockerfile=notes-api --opt build-arg:VERSION=0.3.0 \
  --output type=docker,name=localhost/notes-api:0.3.0,dest=- 2>/dev/null \
  | sudo ctr images import -
sudo nerdctl run -d --name api3 -p 127.0.0.1:8081:8080 \
  -e NOTES_API_KEY=lab-api-key-123 localhost/notes-api:0.3.0
sleep 3
curl -s 127.0.0.1:8081/version; echo
sudo nerdctl ps --format '{{.Names}} {{.Status}}'
sudo nerdctl rm -f api3
sudo systemctl stop containerd buildkit

Erwartet (gekürzt):

localhost/notes api:0.3.0                   saved
application/vnd.oci.image.manifest.v1+json sha256:c676cd0f88658497dba03d5daf4c704e505…
Importing   elapsed: 85.1s  total:   0.0 B  (0.0 B/s)
b0c520c3e8f3…
0.3.0
api3 Up (healthy)
time="…" level=warning msg="force cleanup timed out for container b0c520c3e8f3…, but …
api3

Genau so arbeitet nerdctl build intern: BuildKit liefert ein Archiv, nerdctl importiert es. systemctl start funktioniert auch bei deaktivierten Units – nur der automatische Start beim Booten fehlt.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • In Kubernetes spricht der kubelet über CRI mit containerd im Namespace k8s.io (Tag 10). ctr und nerdctl mit -n k8s.io sind dort Werkzeuge zur Fehlersuche, nicht zum Betrieb.
  • containerd-Konfiguration (/etc/containerd/config.toml) für Registry-Spiegel, Snapshotter und Runtime-Klassen gehört ins Konfigurationsmanagement, nicht in Handarbeit.
  • BuildKit im CI: als eigener Dienst oder rootless, Cache per --export-cache type=registry in einer internen Registry statt auf der Platte des Runners.
  • AppArmor-Profile nicht pauschal abschalten: nerdctl-default und eigene Profile testen, Abweichungen pro Dienst dokumentieren und begründen.
  • Getrennte Speicher heißen doppelter Plattenplatz und zwei Wahrheiten pro Tag. Images laufen in Produktion über eine Registry (Tag 7), nicht über save | import.