Tag 5: Multi-Stage-Grundlagen – Go nach scratch
Ziel: notes-api in zwei Stages bauen, sodass das Laufzeit-Image nur noch Binary und CA-Zertifikate enthält – auf
scratchund auf distroless. · Dauer: ca. 75 min · Voraussetzung: Tag 4
Briefing
- Jedes
FROMbeginnt eine neue Stage. Ins Image kommt nur die letzte (oder die per--targetgewählte); alle anderen sind Werkbänke. COPY --from=<stage>holt einzelne Dateien aus einer früheren Stage. Compiler, Quellcode und Modul-Cache bleiben zurück.scratchist leer: keine Shell, keine libc, keine CA-Zertifikate, keine Zeitzonen. Was das Programm braucht, kopierst du selbst hinein.- Go eignet sich dafür ideal:
CGO_ENABLED=0liefert ein statisches Binary.
Stage "build" golang:1.27-alpine Stage 1 scratch
┌───────────────────────────────┐ ┌──────────────────────────────┐
│ Go-Toolchain, apk, sh │ │ │
│ /src Quellcode │ COPY │ /etc/ssl/certs/ca-cert….crt │
│ /etc/ssl/certs/ca-cert….crt ──┼─--from──►│ /notes-api │
│ /out/notes-api ───────────────┼─────────►│ USER 65532, ENTRYPOINT │
└───────────────────────────────┘ └──────────────────────────────┘
wird verworfen wird zum Image
Drill 1: Ausgangslage messen
source ~/docker-lab/setup/env.sh
mkdir -p ~/docker-lab/tag05 && cd ~/docker-lab/tag05
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag04/notes/." .Die zweite Kopie legt den Stand vom Ende von Tag 4 darüber – auch wenn du ihn übersprungen hast. Bau ihn einmal als Vergleichswert:
docker build -q -t notes-api:tag04 notes-api
docker image ls notes-api --format '{{.Repository}}:{{.Tag}} {{.Size}}'
docker run --rm --entrypoint sh notes-api:tag04 -c 'du -sh /usr/local/go; which go'Erwartet (gekürzt, kann je nach Version abweichen):
sha256:3f0a…
notes-api:tag04 268MB
253.4M /usr/local/go
/usr/local/go/bin/go
Über 250 MB davon sind Go-Toolchain, die der laufende Dienst nie braucht. Image-Größen und Build-Zeiten in diesem Kapitel stammen aus einer Beispielumgebung und weichen bei dir ab – entscheidend ist das Verhältnis.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Zwei Stages
Ersetze das Dockerfile vollständig:
cat > notes-api/Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
# notes-api, Stand Tag 5: zweistufig, Laufzeit-Image auf scratch
ARG GO_VERSION=1.27
# in Produktion: @sha256:… pinnen, siehe Tag 8
FROM golang:${GO_VERSION}-alpine AS build
ARG VERSION=dev
ENV CGO_ENABLED=0
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
--mount=type=cache,target=/root/.cache/go-build \
go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" \
-o /out/notes-api .
FROM scratch
LABEL org.opencontainers.image.title="notes-api" \
org.opencontainers.image.description="Notiz-API aus dem Trainingslager" \
org.opencontainers.image.source="https://example.com/docker-lab/notes"
COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=build /out/notes-api /notes-api
EXPOSE 8080
USER 65532:65532
HEALTHCHECK --interval=10s --timeout=2s --start-period=5s --start-interval=1s \
CMD ["/notes-api", "healthcheck"]
STOPSIGNAL SIGTERM
ENTRYPOINT ["/notes-api"]
EOFWas neu ist:
AS buildbenennt die erste Stage. Ohne Namen hieße sie0; ein Name übersteht das Umsortieren des Dockerfiles.ARG VERSIONundENV CGO_ENABLED=0gelten nur inbuild. JedesFROMstartet mit leerem Zustand, deshalb stehenLABEL,USERundHEALTHCHECKjetzt im zweiten Teil.ARG GO_VERSIONvor dem erstenFROMist global und darf in jedemFROMstehen.- Das Binary landet als
/notes-apiim Wurzelverzeichnis;scratchhat keinPATH, also nennenENTRYPOINTundHEALTHCHECKden absoluten Pfad.
docker build --build-arg VERSION=tag05 -t notes-api:tag05 notes-apiErwartet (gekürzt, kann je nach Version abweichen):
[+] Building 19.7s (14/14) FINISHED docker:colima
=> [internal] load build definition from Dockerfile 0.0s
=> [internal] load metadata for docker.io/library/golang:1.27-alpine 0.9s
=> [internal] load .dockerignore 0.0s
=> [build 1/6] FROM docker.io/library/golang:1.27-alpine@sha256:… 0.0s
=> [internal] load build context 0.0s
=> CACHED [build 2/6] WORKDIR /src 0.0s
=> CACHED [build 3/6] COPY go.mod go.sum ./ 0.0s
=> CACHED [build 4/6] RUN --mount=type=cache,target=/go/pkg/mod go mod … 0.0s
=> [build 5/6] COPY . . 0.0s
=> [build 6/6] RUN --mount=type=cache,target=/go/pkg/mod --mount=t… 14.8s
=> [stage-1 1/2] COPY --from=build /etc/ssl/certs/ca-certificates.crt … 0.1s
=> [stage-1 2/2] COPY --from=build /out/notes-api /notes-api 0.1s
=> exporting to image 0.3s
Die unbenannte zweite Stage taucht als stage-1 auf. Die
Cache-Treffer aus Tag 4 greifen weiter, weil der build-Teil
bis go mod download gleich geblieben ist.
docker image ls notes-api --format '{{.Repository}}:{{.Tag}} {{.Size}}'Erwartet (gekürzt, kann je nach Version abweichen):
notes-api:tag05 6.31MB
notes-api:tag04 268MB
Faktor 40, ohne eine Zeile Go-Code zu ändern.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Leben ohne Shell
docker run -d --name notes-api -p 127.0.0.1:8080:8080 \
-e NOTES_API_KEY=lab-api-key-123 notes-api:tag05
sleep 3
curl -s localhost:8080/version
curl -s -X POST localhost:8080/notes -H 'X-API-Key: lab-api-key-123' \
-d '{"text":"aus scratch"}'
docker inspect --format '{{.State.Health.Status}} {{.Config.User}}' notes-apiErwartet (gekürzt, IDs weichen ab):
tag05
{"id":"9a4e…","text":"aus scratch"}
healthy 65532:65532
Der Healthcheck funktioniert, weil er das Binary selbst aufruft statt
curl. Eine Shell zum Nachschauen gibt es nicht mehr:
docker exec notes-api sh
docker exec notes-api ls /Erwartet (gekürzt, kann je nach Version abweichen):
OCI runtime exec failed: exec failed: unable to start container process: exec: "sh":
executable file not found in $PATH: unknown
OCI runtime exec failed: exec failed: unable to start container process: exec: "ls":
executable file not found in $PATH: unknown
Genau das ist gewollt: Wer in den Container einbricht, findet kein Werkzeug vor. Wie man trotzdem debuggt, zeigt Tag 8. Den Inhalt kannst du aber von außen auflisten:
docker export notes-api | tar -t | sort
docker rm -f notes-apiErwartet (gekürzt, kann je nach Version abweichen):
.dockerenv
dev/
…
etc/
etc/hostname
etc/hosts
etc/resolv.conf
etc/ssl/
etc/ssl/certs/
etc/ssl/certs/ca-certificates.crt
notes-api
proc/
sys/
notes-api
Neben deinen zwei Dateien legt nur die Container-Runtime ein paar
Einträge an (/etc/hosts, /etc/resolv.conf,
/dev). Die letzte Zeile ist die Ausgabe von
docker rm.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Ohne CA-Zertifikate
Was passiert ohne die erste COPY --from-Zeile? Du baust
eine Variante, ohne die Datei anzufassen: sed löscht die
Zeile, docker build -f- liest das Dockerfile von stdin.
sed '/ca-certificates/d' notes-api/Dockerfile \
| docker build -q -f- -t notes-api:tag05-noca notes-api
docker run -d --name notes-api-noca -p 127.0.0.1:8081:8080 \
-e NOTES_API_KEY=lab-api-key-123 notes-api:tag05-noca
docker run -d --name notes-api -p 127.0.0.1:8080:8080 \
-e NOTES_API_KEY=lab-api-key-123 notes-api:tag05
sleep 2
curl -s localhost:8081/upstream; echo
curl -s localhost:8080/upstream; echoErwartet (gekürzt, kann je nach Version abweichen):
sha256:c71b…
{"error":"Get \"https://example.com\": tls: failed to verify certificate: x509:
certificate signed by unknown authority"}
{"status":200,"url":"https://example.com"}
Go sucht die Zertifikate unter Linux an festen Pfaden, darunter
/etc/ssl/certs/ca-certificates.crt. Fehlt die Datei,
scheitert jede HTTPS-Verbindung erst zur Laufzeit – der Build und
/healthz bleiben grün. Diesen Fehler triffst du an Tag 15
wieder.
docker rm -f notes-api notes-api-nocaFortschritt speichern? Kostenlos registrieren
Drill 5: Zeitzonen
scratch hat auch keine Zeitzonen-Datenbank. Go fällt
dann stillschweigend auf UTC zurück:
docker run -d --name notes-api -e TZ=Europe/Berlin \
-e NOTES_API_KEY=lab-api-key-123 notes-api:tag05
sleep 1; docker logs notes-api | head -1 | cut -d' ' -f1
docker rm -f notes-apiErwartet (Zeit weicht ab):
time=2026-10-29T17:42:10.318Z
notes-api
Das Z heißt UTC, trotz TZ=Europe/Berlin. Go
kann die Datenbank aber ins Binary einbetten: Das Build-Tag
timetzdata bindet das Paket time/tzdata ein
(rund 450 KB laut Go-Doku).
sed 's/go build -trimpath/go build -trimpath -tags timetzdata/' notes-api/Dockerfile \
| docker build -q -f- -t notes-api:tag05-tz notes-api
docker run -d --name notes-api -e TZ=Europe/Berlin \
-e NOTES_API_KEY=lab-api-key-123 notes-api:tag05-tz
sleep 1; docker logs notes-api | head -1 | cut -d' ' -f1
docker rm -f notes-apiErwartet (Zeit weicht ab):
sha256:0e8d…
time=2026-10-29T18:42:10.902+01:00
notes-api
+01:00 im Winter, +02:00 im Sommer. Ob dein
Dienst lokale Zeit braucht, entscheidest du; Logs in UTC sind in
Produktion meist die bessere Wahl. Den zweiten Weg, die Datenbank als
Dateien ins Image zu kopieren, übst du in der Challenge.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Nur bis zur Werkbank –
--target
--target hält den Build nach einer Stage an. BuildKit
baut dabei nur die Stages, von denen das Ziel abhängt.
docker build -q --target build -t notes-api:tag05-build notes-api
docker run --rm notes-api:tag05-build go version -m /out/notes-apiErwartet (gekürzt, kann je nach Version abweichen):
sha256:7d22…
/out/notes-api: go1.27.3
path example.com/notes-api
mod example.com/notes-api (devel)
dep github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
build -buildmode=exe
build -compiler=gc
build -trimpath=true
build CGO_ENABLED=0
build GOARCH=arm64
build GOOS=linux
build GOARM64=v8.0
Das Binary trägt seine Build-Einstellungen in sich. Die drei Schalter im Überblick:
| Schalter | Wirkung |
|---|---|
CGO_ENABLED=0 |
rein in Go gelinkt, braucht keine libc – Pflicht für
scratch |
-trimpath |
entfernt lokale Pfade wie /src aus dem Binary
(reproduzierbarer) |
-ldflags="-s -w" |
lässt Symboltabelle und DWARF-Debug-Infos weg |
Was -s -w bringt, siehst du im Vergleich mit einem Build
ohne Flags. Der Modul-Cache lag in einem Cache-Mount und ist nicht im
Image, deshalb lädt go das Modul neu:
docker run --rm notes-api:tag05-build \
sh -c 'go build -o /tmp/plain . && ls -l /tmp/plain /out/notes-api'Erwartet (gekürzt, kann je nach Version abweichen):
go: downloading github.com/google/uuid v1.6.0
-rwxr-xr-x 1 root root 6029496 Oct 29 17:50 /out/notes-api
-rwxr-xr-x 1 root root 8716059 Oct 29 17:51 /tmp/plain
Rund ein Drittel kleiner. Der Preis: Stacktraces bleiben lesbar, aber
Debugger wie Delve finden keine Symbole mehr. Für einen Debug-Build
lässt du -s -w weg.
Tipp:
--target buildist auch der schnellste Weg, einen Build-Fehler zu untersuchen: Das Zwischen-Image hat Shell und Toolchain. In CI nutzt du dasselbe für eine Test-Stage (Tag 7).
Fortschritt speichern? Kostenlos registrieren
Drill 7: distroless statt scratch
gcr.io/distroless/static-debian13 ist fast so klein wie
scratch, bringt aber CA-Zertifikate, tzdata, eine
/etc/passwd und /tmp mit. Der Tag
nonroot ist auf User 65532 vorbereitet.
cat > notes-api/Dockerfile.distroless <<'EOF'
# syntax=docker/dockerfile:1
# notes-api, Variante Tag 5: Laufzeit-Image distroless static (nonroot)
ARG GO_VERSION=1.27
# in Produktion: @sha256:… pinnen, siehe Tag 8
FROM golang:${GO_VERSION}-alpine AS build
ARG VERSION=dev
ENV CGO_ENABLED=0
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
--mount=type=cache,target=/root/.cache/go-build \
go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" \
-o /out/notes-api .
# bringt CA-Zertifikate, tzdata, /etc/passwd und /tmp schon mit
FROM gcr.io/distroless/static-debian13:nonroot
LABEL org.opencontainers.image.title="notes-api" \
org.opencontainers.image.description="Notiz-API aus dem Trainingslager" \
org.opencontainers.image.source="https://example.com/docker-lab/notes"
COPY --from=build /out/notes-api /notes-api
EXPOSE 8080
USER 65532:65532
HEALTHCHECK --interval=10s --timeout=2s --start-period=5s --start-interval=1s \
CMD ["/notes-api", "healthcheck"]
STOPSIGNAL SIGTERM
ENTRYPOINT ["/notes-api"]
EOF
docker build -q -f notes-api/Dockerfile.distroless --build-arg VERSION=tag05 \
-t notes-api:tag05-distroless notes-apiErwartet (gekürzt, kann je nach Version abweichen):
sha256:4b90…
Der build-Teil ist identisch, also kommt er komplett aus
dem Cache. Jetzt beide Eigenschaften prüfen, die scratch
fehlten:
docker run -d --name notes-api -p 127.0.0.1:8080:8080 -e TZ=Europe/Berlin \
-e NOTES_API_KEY=lab-api-key-123 notes-api:tag05-distroless
sleep 2
curl -s localhost:8080/upstream; echo
docker logs notes-api | head -1 | cut -d' ' -f1
docker rm -f notes-apiErwartet (gekürzt, Zeit weicht ab):
{"status":200,"url":"https://example.com"}
time=2026-10-29T18:55:03.114+01:00
notes-api
Tipp: Ältere Anleitungen zeigen noch
static-debian12. Diese Variante ist abgekündigt, die distroless-README listet nur noch-debian13. Der Wechsel ist eine Zeile, das Laufzeitverhalten bleibt gleich (User 65532, CA-Zertifikate, tzdata). Zu jedem Tag gibt es außerdem einedebug-Variante mit Busybox-Shell, z. B.:debug-nonroot.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Vergleich und Registry
docker image ls notes-api --format '{{.Tag}}\t{{.Size}}' | sort
docker history --format '{{.Size}}\t{{.CreatedBy}}' notes-api:tag05 | cut -c1-80Erwartet (gekürzt, kann je nach Version abweichen):
tag04 268MB
tag05 6.31MB
tag05-build 291MB
tag05-distroless 8.38MB
tag05-noca 6.08MB
tag05-tz 6.70MB
0B ENTRYPOINT ["/notes-api"]
0B STOPSIGNAL SIGTERM
0B HEALTHCHECK &{["CMD" "/notes-api" "healthcheck"] "10s" "2s" "5s" "1s" …
0B USER 65532:65532
0B EXPOSE map[8080/tcp:{}]
6.03MB COPY /out/notes-api /notes-api # buildkit
225kB COPY /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ # buildkit
0B LABEL org.opencontainers.image.title=notes-api org.opencontainers.image.…
Zwei Layer mit Inhalt, sonst nur Metadaten. Vom
build-Stage steht nichts in der History: Kein
go build, kein Quellcode, kein Hinweis auf die Toolchain.
Das tag05-build-Image ist die Werkbank mit Binary – nur zum
Untersuchen, nie zum Ausliefern.
Schieb das Ergebnis in die lokale Registry:
docker tag notes-api:tag05 localhost:5001/notes-api:tag05
docker push -q localhost:5001/notes-api:tag05
curl -s http://localhost:5001/v2/notes-api/tags/listErwartet (gekürzt, kann je nach Version abweichen):
localhost:5001/notes-api:tag05
{"name":"notes-api","tags":["tag05"]}
Weitere Tags aus früheren Tagen erscheinen ebenfalls in der Liste.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Zwei Stages, das Laufzeit-Stage auf scratch,
CA-Zertifikate aus dem build-Stage:
cd ~/docker-lab/tag05
grep -E '^FROM|^COPY --from=build /etc/ssl' notes-api/DockerfileErwartet:
FROM golang:${GO_VERSION}-alpine AS build
FROM scratch
COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
Beide Varianten sind gebaut, tag05 liegt unter 20
MB:
docker image ls notes-apiErwartet (gekürzt, Größen weichen ab):
IMAGE ID DISK USAGE CONTENT SIZE EXTRA
notes-api:tag04 e34fbc92b985 398MB 81.3MB
notes-api:tag05 4c5f162e9005 10.7MB 3.23MB
notes-api:tag05-build b916f6e468ab 392MB 78.4MB
notes-api:tag05-distroless a622dad25fce 17MB 3.99MB
…
Das Image läuft als UID 65532:
docker image inspect --format '{{.Config.User}}' notes-api:tag05Erwartet:
65532:65532
Keine Shell im Image:
docker run --rm --entrypoint sh notes-api:tag05 -c trueErwartet (gekürzt):
docker: Error response from daemon: failed to create task for container: …
… exec: "sh": executable file not found in $PATH
Run 'docker run --help' for more information
tag05 liegt in der Registry:
curl -s localhost:5001/v2/notes-api/tags/list | jq -c .tagsErwartet:
["buildcache",…,"tag01","tag04","tag05"]
Challenge
Bring die Zeitzonen-Datenbank ins scratch-Image, ohne
-tags timetzdata: Die Dateien sollen aus dem
build-Stage kommen. Speichere die Variante als
~/docker-lab/tag05/Dockerfile.tz, bau
notes-api:tag05-tzfiles und zeig mit
TZ=Europe/Berlin, dass die Logs +01:00 (bzw.
+02:00) tragen.
Hinweis: golang:*-alpine bringt
ca-certificates mit, aber kein tzdata; Go
sucht unter /usr/share/zoneinfo/.
Lösung
Die Datei liegt auch unter
~/docker-lab/code/tag05/Dockerfile.tz. Gegenüber
notes-api/Dockerfile kommen zwei Zeilen hinzu:
# im build-Stage, vor WORKDIR:
# hadolint ignore=DL3018
RUN apk add --no-cache tzdata
# im scratch-Stage, nach der CA-Zeile:
COPY --from=build /usr/share/zoneinfo /usr/share/zoneinfoDie hadolint-Ausnahme unterdrückt die Warnung, dass
tzdata nicht auf eine Version gepinnt ist (Tag 9). Bauen
und prüfen:
cd ~/docker-lab/tag05
cp ~/docker-lab/code/tag05/Dockerfile.tz .
docker build -q -f Dockerfile.tz -t notes-api:tag05-tzfiles notes-api
docker run -d --name notes-api -e TZ=Europe/Berlin \
-e NOTES_API_KEY=lab-api-key-123 notes-api:tag05-tzfiles
sleep 1; docker logs notes-api | head -1 | cut -d' ' -f1
docker image ls notes-api --format '{{.Tag}}\t{{.Size}}' \
| grep -E '^tag05(-tz|-tzfiles)?[[:space:]]'Erwartet (gekürzt, kann je nach Version abweichen):
sha256:a3f6…
time=2026-10-29T19:03:44.207+01:00
tag05 6.31MB
tag05-tz 6.70MB
tag05-tzfiles 7.9MB
Beide Wege funktionieren. -tags timetzdata hält das
Dockerfile schlicht und das Binary unabhängig vom Image; die Dateien aus
tzdata werden mit dem Base-Image aktualisiert und dienen
auch anderen Programmen im Image. Das Dockerfile liegt im Projektordner,
nicht im Kontext notes-api/ – sonst würde es die
.dockerignore (Dockerfile*) ohnehin
ausschließen. Zum Schluss aufräumen:
docker rm -f notes-api
docker ps -a --filter name=^notes- --format '{{.Names}}' | xargs -r docker rm -f
docker image ls --format '{{.Repository}}:{{.Tag}}' \
| grep -E '^(notes-|localhost:5001/)' | xargs -r docker rmi
docker buildx prune --builder docker-lab --all --forceErwartet (gekürzt, Namen, IDs und Größen weichen ab):
notes-api
Untagged: notes-api:tag05
Deleted: sha256:…
…
Total: …
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Viele Plattformen verlangen ein „Golden Base Image” (z. B. intern
gespiegeltes distroless oder Chainguard) statt
scratch; dann gilt Drill 7, nicht Drill 2. - Das Firmen-CA-Zertifikat für TLS-Inspection-Proxys gehört in den
Trust-Store des Laufzeit-Images; bei
scratchmusst du das Bundle selbst zusammenstellen. - Ohne Shell im Image fallen
kubectl exec-Gewohnheiten weg. Kläre vorher, wie Debugging läuft: Ephemeral Containers (kubectl debug) oder einedebug-Variante. - Images ohne Paketmanager haben weniger CVE-Treffer, aber das Go-Binary selbst enthält die Standardbibliothek: Bei Go-Sicherheitsupdates muss trotzdem neu gebaut werden.
--targetgehört in CI-Templates: dieselbe Datei liefert Test-, Debug- und Release-Image (Tag 7).