Zum Inhalt springen
Trainingslager IT-Trainingslager

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 scratch und auf distroless. · Dauer: ca. 75 min · Voraussetzung: Tag 4

Briefing

  • Jedes FROM beginnt eine neue Stage. Ins Image kommt nur die letzte (oder die per --target gewä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.
  • scratch ist 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=0 liefert 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"]
EOF

Was neu ist:

  • AS build benennt die erste Stage. Ohne Namen hieße sie 0; ein Name übersteht das Umsortieren des Dockerfiles.
  • ARG VERSION und ENV CGO_ENABLED=0 gelten nur in build. Jedes FROM startet mit leerem Zustand, deshalb stehen LABEL, USER und HEALTHCHECK jetzt im zweiten Teil.
  • ARG GO_VERSION vor dem ersten FROM ist global und darf in jedem FROM stehen.
  • Das Binary landet als /notes-api im Wurzelverzeichnis; scratch hat kein PATH, also nennen ENTRYPOINT und HEALTHCHECK den absoluten Pfad.
docker build --build-arg VERSION=tag05 -t notes-api:tag05 notes-api

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

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

Erwartet (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; echo

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

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

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

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

Erwartet (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 build ist 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-api

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

Erwartet (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 eine debug-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-80

Erwartet (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/list

Erwartet (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/Dockerfile

Erwartet:

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

Erwartet (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:tag05

Erwartet:

65532:65532

Keine Shell im Image:

docker run --rm --entrypoint sh notes-api:tag05 -c true

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

Erwartet:

["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/zoneinfo

Die 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 --force

Erwartet (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 scratch musst 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 eine debug-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.
  • --target gehört in CI-Templates: dieselbe Datei liefert Test-, Debug- und Release-Image (Tag 7).