Tag 7: Fortgeschrittene Muster und Multi-Plattform
Ziel: notes-api in ein Dockerfile mit gemeinsamer
base-,test-,build- undfinal-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:
testläuft nur auf Wunsch (--target test),finalenthält davon nichts. - BuildKit baut nur Stages, von denen das Ziel abhängt, und unabhängige Stages parallel.
FROM --platform=$BUILDPLATFORMlässt den Compiler nativ laufen; Go übersetzt perGOOS/GOARCHfür die Zielplattform.COPY --linklegt 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)
}
}
}
EOFJetzt 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-apiErwartet (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 -cErwartet (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 sichbaseü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)'
doneErwartet (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/nullErwartet:
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-apiErwartet (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:tag07Erwartet (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/nullErwartet:
linux/arm64
0.7.0
Achtung: Ohne
--platform=$BUILDPLATFORMin derbase-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-riscv64Erwartet (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 errorin CI oder auf dem Cluster, zuerstdocker buildx imagetools inspect <image>(welche Plattformen gibt es?) unddocker image inspect --format '{{.Architecture}}'(welche liegt lokal?).
Fortschritt speichern? Kostenlos registrieren
Drill 6: COPY --link
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'
doneErwartet (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.DockerfileErwartet (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
--linksieht dasCOPYden bisherigen Inhalt nicht. Darum geht--chownnur 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 outErwartet (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 outSicherheit: Ein fremdes Image in
COPY --fromist 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/DockerfileErwartet:
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/DockerfileErwartet:
2
Die Build Checks sind still:
docker build --check notes-api 2>&1 | tail -1Erwartet:
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 PlatformErwartet:
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 PlatformErwartet (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 --forceFortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- In CI sind
testund Image-Build getrennte Jobs auf demselben Dockerfile; beide ziehenbaseaus dem Registry-Cache (Tag 4), Testberichte holst du per--output type=localaus 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 errorbeim Pod-Start. COPY --linkmacht 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 --fromgehören ins selbe Inventar wie Base-Images: Spiegel, Pinning, Scan.