Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 7: Fortgeschrittene Muster und Multi-Plattform

Ziel: notes-api in ein Dockerfile mit gemeinsamer base-, test-, build- und final-Stage umbauen und für amd64 und arm64 per Cross-Compile bauen, ohne Emulation. · Dauer: ca. 75 min · Voraussetzung: Tag 6

Briefing

  • Ein Dockerfile kann mehr als eine Pipeline-Stufe sein: test läuft nur auf Wunsch (--target test), final enthält davon nichts.
  • BuildKit baut nur Stages, von denen das Ziel abhängt, und unabhängige Stages parallel.
  • FROM --platform=$BUILDPLATFORM lässt den Compiler nativ laufen; Go übersetzt per GOOS/GOARCH für die Zielplattform.
  • COPY --link legt Dateien in eine eigene Schicht, die nicht vom Base-Image abhängt.
                 ┌──► test   (go vet, go test)      nur mit --target test
 base ──────────┤
 (BUILDPLATFORM) └──► build  (GOOS/GOARCH = Ziel) ──► final (scratch, COPY --link)

Drill 1: Vier Stages, ein Dockerfile

source ~/docker-lab/setup/env.sh
mkdir -p ~/docker-lab/tag07 && cd ~/docker-lab/tag07
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag06/notes/." .

Die zweite Kopie legt den Stand vom Ende von Tag 6 darüber – auch wenn du ihn übersprungen hast. notes-api bekommt heute zuerst einen Test, damit die Test-Stage etwas zu tun hat:

cat > notes-api/main_test.go <<'EOF'
package main

import (
    "net/http"
    "net/http/httptest"
    "strings"
    "testing"
)

// Lab-Wert, kein echter Key.
const labKey = "lab-api-key-123"

func TestLoadAPIKeyFromEnv(t *testing.T) {
    t.Setenv("NOTES_API_KEY_FILE", "")
    t.Setenv("NOTES_API_KEY", labKey)
    key, source, err := loadAPIKey()
    if err != nil || key != labKey || source != "env" {
        t.Fatalf("got %q, %q, %v", key, source, err)
    }
}

func TestPostNotesRequiresKey(t *testing.T) {
    s := &store{notes: []note{}}
    h := s.handleNotes(labKey)
    cases := []struct {
        key  string
        want int
    }{
        {"", http.StatusUnauthorized},
        {"falsch", http.StatusUnauthorized},
        {labKey, http.StatusCreated},
    }
    for _, c := range cases {
        req := httptest.NewRequest(http.MethodPost, "/notes",
            strings.NewReader(`{"text":"test"}`))
        req.Header.Set("X-API-Key", c.key)
        rec := httptest.NewRecorder()
        h(rec, req)
        if rec.Code != c.want {
            t.Errorf("key %q: status %d, want %d", c.key, rec.Code, c.want)
        }
    }
}
EOF

Jetzt das neue Dockerfile. Alles aus Tag 2 bis Tag 5 bleibt, nur die Stages sind neu geschnitten:

cat > notes-api/Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
ARG GO_VERSION=1.27

# base: gemeinsam für test und build, läuft immer auf der Plattform des Builders
FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine AS base
ENV CGO_ENABLED=0
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .

# test: nur mit --target test (CI); gehört nicht zum Final-Image
FROM base AS test
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go vet ./... && go test ./...

# build: Cross-Compile für die Zielplattform, ohne Emulation
FROM base AS build
ARG TARGETOS
ARG TARGETARCH
ARG VERSION=dev
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    GOOS=$TARGETOS GOARCH=$TARGETARCH \
    go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" \
      -o /out/notes-api .

# final: nur CA-Zertifikate und Binary
FROM scratch AS final
COPY --link --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --link --from=build /out/notes-api /notes-api
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"
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
hadolint notes-api/Dockerfile && docker build --check notes-api

Erwartet (gekürzt, kann je nach Version abweichen):

[+] Building 1.4s (4/4) FINISHED                                  docker:colima
 => [internal] load build definition from Dockerfile                       0.0s
 => [internal] load metadata for docker.io/library/golang:1.27-alpine      0.9s
Check complete, no warnings found.

hadolint schweigt, die Build Checks auch, Exit-Code 0. final ist die letzte Stage und damit das Standardziel. Bauen und zählen, welche Stages gelaufen sind:

docker build --progress=plain -t notes-api:tag07 notes-api 2>&1 \
  | grep -oE '\[(base|test|build|final) ' | sort | uniq -c

Erwartet (gekürzt, kann je nach Version abweichen):

   5 [base
   1 [build
   3 [final

Kein [test: BuildKit hat den Abhängigkeitsgraphen von final aus aufgebaut, und test kommt darin nicht vor. Der Test kostet im normalen Build also nichts.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Test-Stage für CI

docker build --progress=plain --target test -t notes-api:tag07-test notes-api 2>&1 \
  | grep -E 'go vet|ok  |FAIL|ERROR'

Erwartet (gekürzt, kann je nach Version abweichen):

#11 [test 1/1] RUN --mount=type=cache,target=/go/pkg/mod --mount=type=cache,…
#11 3.2 ok      example.com/notes-api   0.014s

base kam komplett aus dem Cache von Drill 1, nur der Test lief. Jetzt brichst du absichtlich einen Test (der richtige Statuscode wäre 201):

sed -i '' 's/{labKey, http.StatusCreated}/{labKey, http.StatusOK}/' \
  notes-api/main_test.go
docker build --progress=plain --target test -t notes-api:tag07-test notes-api 2>&1 \
  | grep -E 'FAIL|want|ERROR'; echo "Exit: ${PIPESTATUS[0]}"

Erwartet (gekürzt, kann je nach Version abweichen):

#11 3.1 --- FAIL: TestPostNotesRequiresKey (0.00s)
#11 3.1     main_test.go:40: key "lab-api-key-123": status 201, want 200
#11 3.1 FAIL    example.com/notes-api   0.012s
ERROR: failed to build: failed to solve: process "/bin/sh -c go vet ./... && go
test ./..." did not complete successfully: exit code: 1
Exit: 1

Unter Linux heißt es sed -i ohne ''. Exit-Code 1 reicht jeder CI, um die Pipeline anzuhalten. Den Test reparierst du mit der Kopie aus dem Begleitcode:

cp "$LAB/code/tag07/notes/notes-api/main_test.go" notes-api/
docker build -q --target test -t notes-api:tag07-test notes-api >/dev/null
echo "Exit: $?"

Erwartet:

Exit: 0

Tipp: In GitLab oder GitHub Actions ist das ein eigener Job docker build --target test … vor dem Build-Job. Beide teilen sich base über den Registry-Cache (Tag 4).

Fortschritt speichern? Kostenlos registrieren

Drill 3: ARG vor FROM und die Plattform-ARGs

GO_VERSION steht vor dem ersten FROM, also im globalen Gültigkeitsbereich: Es darf in FROM-Zeilen stehen, ist in den Stages aber unbekannt. Für die automatischen Plattform-ARGs gilt dasselbe. Probier es mit einem Wegwerf-Dockerfile:

cat > platform.Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:1.27-alpine
RUN echo "vorher:  TARGETARCH=$TARGETARCH"
ARG BUILDPLATFORM
ARG TARGETPLATFORM
ARG TARGETARCH
RUN echo "nachher: $BUILDPLATFORM -> $TARGETPLATFORM ($TARGETARCH)"
EOF
for p in linux/arm64 linux/amd64; do
  docker build --no-cache --progress=plain --platform "$p" - < platform.Dockerfile \
    2>&1 | grep -E '^#[0-9]+ [0-9.]+ (vorher|nachher)'
done

Erwartet (gekürzt, kann je nach Version abweichen):

#5 0.142 vorher:  TARGETARCH=
#6 0.098 nachher: linux/arm64 -> linux/arm64 (arm64)
#5 0.131 vorher:  TARGETARCH=
#6 0.104 nachher: linux/arm64 -> linux/amd64 (amd64)

Vor dem ARG ist TARGETARCH leer, erst die Zeile ohne Wert holt es in die Stage. In FROM --platform=$BUILDPLATFORM geht es ohne Deklaration, weil FROM den globalen Bereich sieht. Und weil die Stage auf BUILDPLATFORM festgenagelt ist, lief das RUN in beiden Fällen nativ auf arm64. Genau das nutzt die build-Stage von notes-api.

rm platform.Dockerfile
docker build -q --build-arg VERSION=0.7.0 -t notes-api:tag07 notes-api >/dev/null
docker run --rm -d --name notes-api -p 127.0.0.1:8080:8080 \
  -e NOTES_API_KEY=lab-api-key-123 notes-api:tag07
sleep 2; curl -s localhost:8080/version; docker rm -f notes-api >/dev/null

Erwartet:

0.7.0

Fortschritt speichern? Kostenlos registrieren

Drill 4: Cross-Compile für zwei Plattformen

Multi-Plattform-Images baust du mit dem Builder docker-lab und pushst sie direkt in die Registry:

time docker buildx build --builder docker-lab \
  --platform linux/amd64,linux/arm64 --build-arg VERSION=0.7.0 \
  -t localhost:5001/notes-api:tag07 --push notes-api

Erwartet (gekürzt, kann je nach Version abweichen):

[+] Building 24.8s (21/21) FINISHED                      docker-container:docker-lab
 => [linux/arm64 base 1/5] FROM docker.io/library/golang:1.27-alpine@sha256:…  9.6s
 => [linux/arm64 base 4/5] RUN --mount=type=cache,target=/go/pkg/mod go mod …  2.3s
 => [linux/arm64->amd64 build 1/1] RUN --mount=type=cache,target=/go/pkg/mod…  7.9s
 => [linux/arm64 build 1/1] RUN --mount=type=cache,target=/go/pkg/mod --mount…  7.7s
 => [linux/amd64 final 2/2] COPY --link --from=build /out/notes-api /notes-api 0.0s
 => [linux/arm64 final 2/2] COPY --link --from=build /out/notes-api /notes-api 0.0s
 => pushing localhost:5001/notes-api:tag07 with docker                         0.6s
real    0m26.3s

Drei Dinge siehst du hier: base läuft nur einmal (beide Ziele nutzen dieselbe arm64-Stage), die zwei build-Stages laufen parallel, und arm64->amd64 heißt: der Compiler läuft nativ, nur sein Ergebnis ist amd64. Was in der Registry liegt:

docker buildx imagetools inspect localhost:5001/notes-api:tag07

Erwartet (gekürzt, Digests weichen ab):

Name:      localhost:5001/notes-api:tag07
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:…

Manifests:
  Name:        localhost:5001/notes-api:tag07@sha256:…
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/amd64

  Name:        localhost:5001/notes-api:tag07@sha256:…
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/arm64

  Name:        localhost:5001/notes-api:tag07@sha256:…
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    unknown/unknown
  Annotations:
    vnd.docker.reference.digest: sha256:…
    vnd.docker.reference.type:   attestation-manifest

Ein Tag, ein Index, darunter ein Manifest je Plattform. Die unknown/unknown-Einträge sind Provenance-Attestations, die der docker-container-Treiber standardmäßig anhängt (Tag 10). Wer das Image zieht, bekommt automatisch seine Plattform:

docker run --rm -d --name notes-api -p 127.0.0.1:8080:8080 \
  -e NOTES_API_KEY=lab-api-key-123 localhost:5001/notes-api:tag07
docker image inspect --format '{{.Os}}/{{.Architecture}}' \
  localhost:5001/notes-api:tag07
sleep 2; curl -s localhost:8080/version; docker rm -f notes-api >/dev/null

Erwartet:

linux/arm64
0.7.0

Achtung: Ohne --platform=$BUILDPLATFORM in der base-Stage würde BuildKit für amd64 ein amd64-golang-Image ziehen und den Compiler per QEMU emulieren, wenn die VM dafür überhaupt einen Emulator hat. Das ist meist um ein Vielfaches langsamer.

Fortschritt speichern? Kostenlos registrieren

Drill 5: exec format error provozieren

Was passiert, wenn ein Image für die falsche Architektur auf deinem Rechner landet? riscv64 eignet sich, weil dafür in der Regel kein Emulator registriert ist:

docker build -q --platform linux/riscv64 -t notes-api:tag07-riscv64 notes-api
docker image inspect --format '{{.Os}}/{{.Architecture}}' notes-api:tag07-riscv64
docker run --rm -e NOTES_API_KEY=lab-api-key-123 notes-api:tag07-riscv64

Erwartet (gekürzt, kann je nach Version abweichen):

sha256:…
linux/riscv64
WARNING: The requested image's platform (linux/riscv64) does not match the detected
host platform (linux/arm64/v8) and no specific platform was requested
exec /notes-api: exec format error

Der Build klappte, weil nichts im Ziel-Image ausgeführt wurde: kompiliert wurde auf arm64, final besteht nur aus COPY. Erst der Kernel beim Start erkennt die fremde Architektur. Läuft der Container bei dir trotzdem, hat deine VM einen Emulator für riscv64 registriert; nachsehen mit colima ssh -- ls /proc/sys/fs/binfmt_misc.

Tipp: Kommt exec format error in CI oder auf dem Cluster, zuerst docker buildx imagetools inspect <image> (welche Plattformen gibt es?) und docker image inspect --format '{{.Architecture}}' (welche liegt lokal?).

Fortschritt speichern? Kostenlos registrieren

Ein normales COPY hängt am Zustand davor: Ändert sich das Base-Image, ist jede folgende Schicht ungültig. Mit --link landet die Kopie in einer eigenen, leeren Schicht, die nur noch obendrauf gelegt wird. Das zeigt die Demo Dockerfile.link, deren Laufzeit-Image per ARG RUNTIME wählbar ist:

tail -4 "$LAB/code/tag07/Dockerfile.link"
d=gcr.io/distroless/static-debian13
for tag in nonroot latest; do
  docker build --progress=plain -f "$LAB/code/tag07/Dockerfile.link" \
    --build-arg RUNTIME="$d:$tag" -t "notes-api:tag07-link-$tag" notes-api 2>&1 \
    | grep -A1 -E '^#[0-9]+ \[stage-1 2/2\]' | grep -E 'CACHED|DONE'
done

Erwartet (gekürzt, kann je nach Version abweichen):

FROM ${RUNTIME}
COPY --link --from=build /out/notes-api /notes-api
USER 65532:65532
ENTRYPOINT ["/notes-api"]
#12 DONE 0.1s
#12 CACHED

Beim zweiten Build ist das Laufzeit-Image ein anderes, das COPY --link kommt trotzdem aus dem Cache. Gegenprobe ohne --link:

sed 's/COPY --link/COPY/' "$LAB/code/tag07/Dockerfile.link" > nolink.Dockerfile
for tag in nonroot latest; do
  docker build --progress=plain -f nolink.Dockerfile \
    --build-arg RUNTIME="$d:$tag" -t "notes-api:tag07-nolink-$tag" notes-api 2>&1 \
    | grep -A1 -E '^#[0-9]+ \[stage-1 2/2\]' | grep -E 'CACHED|DONE'
done
rm nolink.Dockerfile

Erwartet (gekürzt, kann je nach Version abweichen):

#12 DONE 0.1s
#12 DONE 0.1s

Bei einem 6-MB-Binary ist das egal. Bei großen Schichten (ein node_modules, ein JDK, Modelldateien) spart --link beim Wechsel des Base-Images echtes Rebuilden und Hochladen, besonders zusammen mit --cache-from.

Achtung: Unter --link sieht das COPY den bisherigen Inhalt nicht. Darum geht --chown nur mit numerischen IDs, Symlinks im Ziel werden nicht verfolgt, und kopierte Verzeichnisse behalten die Rechte der Quelle.

Fortschritt speichern? Kostenlos registrieren

Drill 7: COPY --from aus einem fremden Image

--from nimmt nicht nur Stage-Namen, sondern jedes Image. So holst du einzelne Dateien oder fertige Binaries (wie uv an Tag 6), ohne Paketmanager im eigenen Image. Mit -o landet das Ergebnis eines Builds sogar direkt als Dateien auf dem Mac:

docker build -q -o out - <<'EOF'
# syntax=docker/dockerfile:1
FROM scratch
COPY --from=golang:1.27-alpine /usr/local/go/lib/time/zoneinfo.zip /
EOF
ls -lh out

Erwartet (gekürzt, kann je nach Version abweichen):

-rw-r--r--  1 du  staff   392K  …  zoneinfo.zip

Kein Build-Kontext (-), keine Stage, nur eine Datei aus einem fremden Image. Ein Go- Binary in scratch findet Zeitzonen über ENV ZONEINFO=/zoneinfo.zip, falls du sie brauchst (Tag 5). Aufräumen:

rm -rf out

Sicherheit: Ein fremdes Image in COPY --from ist eine Abhängigkeit wie jedes Base-Image. Pinne es mindestens auf eine Version, in Produktion auf einen Digest (Tag 8).

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Vier Stages, base läuft auf der Build-Plattform:

cd ~/docker-lab/tag07
grep '^FROM' notes-api/Dockerfile

Erwartet:

FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine AS base
FROM base AS test
FROM base AS build
FROM scratch AS final

COPY --link im Final-Stage:

grep -c 'COPY --link' notes-api/Dockerfile

Erwartet:

2

Die Build Checks sind still:

docker build --check notes-api 2>&1 | tail -1

Erwartet:

Check complete, no warnings found.

Die Tests sind grün:

docker build -q --target test notes-api >/dev/null; echo "Exit: $?"

Erwartet:

Exit: 0

Die Registry hat beide Plattformen (Drill 4):

docker buildx imagetools inspect localhost:5001/notes-api:tag07 | grep Platform

Erwartet:

  Platform:    linux/amd64
  Platform:    linux/arm64
  Platform:    unknown/unknown
  Platform:    unknown/unknown

Challenge

Spiel eine kleine Pipeline von Hand durch: erst die Test-Stage, nur bei Erfolg der Build für linux/amd64,linux/arm64 mit Version 0.7.1 nach localhost:5001/notes-api:tag07, zum Schluss die Prüfung, ob die Registry wirklich beide Plattformen hat. Prüf auch, was ein kaputter Test bewirkt.

Hinweis: && führt den zweiten Befehl nur aus, wenn der erste erfolgreich war. Attestations erkennst du in imagetools inspect an unknown/unknown, eine pro Plattform.

Lösung

Erst testen, dann pushen – in einer Zeile mit &&:

cd ~/docker-lab/tag07
docker build -q --target test notes-api >/dev/null && echo "Tests grün"

Erwartet:

Tests grün

Nur dann der Multi-Plattform-Build:

docker buildx build --builder docker-lab --platform linux/amd64,linux/arm64 \
  --build-arg VERSION=0.7.1 -t localhost:5001/notes-api:tag07 --push -q notes-api
docker buildx imagetools inspect localhost:5001/notes-api:tag07 | grep Platform

Erwartet (gekürzt, Digest weicht ab):

sha256:159974c547fe…
  Platform:    linux/amd64
  Platform:    linux/arm64
  Platform:    unknown/unknown
  Platform:    unknown/unknown

Jetzt ein kaputter Test:

sed -i '' 's/{labKey, http.StatusCreated}/{labKey, http.StatusOK}/' \
  notes-api/main_test.go
docker build -q --target test notes-api >/dev/null && echo "Tests grün"
echo "Exit: $?"
cp "$LAB/code/tag07/notes/notes-api/main_test.go" notes-api/

Erwartet (gekürzt):

Dockerfile:14
--------------------
  13 |     FROM base AS test
  14 | >>> RUN --mount=type=cache,target=/go/pkg/mod \
  15 | >>>     --mount=type=cache,target=/root/.cache/go-build \
  16 | >>>     go vet ./... && go test ./...
  17 |
--------------------
ERROR: failed to build: failed to solve: process "/bin/sh -c go vet ./... && go test …
Exit: 1

Kein „Tests grün”, Exit-Code ungleich 0: Eine Pipeline bricht hier ab, der Push findet nie statt, die Registry zeigt weiter Version 0.7.1. Zum Schluss aufräumen:

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

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • In CI sind test und Image-Build getrennte Jobs auf demselben Dockerfile; beide ziehen base aus dem Registry-Cache (Tag 4), Testberichte holst du per --output type=local aus einer eigenen Stage.
  • Multi-Plattform kostet mit Cross-Compile kaum Zeit. Für Sprachen ohne Cross-Compile (native Python-Wheels, Node-Addons) nimmt man native arm64-Runner statt QEMU.
  • Kubernetes-Cluster mit gemischten Nodes (Graviton, Apple-Silicon-Entwickler, x86-CI) brauchen einen Index mit allen Plattformen, sonst exec format error beim Pod-Start.
  • COPY --link macht Rebase auf ein gepatchtes Base-Image billig; gepaart mit automatischen Base-Image-Updates (Tag 8) wird so ein Sicherheitsfix zur Minutensache.
  • Externe Images in COPY --from gehören ins selbe Inventar wie Base-Images: Spiegel, Pinning, Scan.