Day 7: Advanced Patterns and Multi-Platform
Goal: Restructure notes-api into a Dockerfile with shared
base,test,buildandfinalstages and build it for amd64 and arm64 via cross-compilation, without emulation. · Duration: approx. 75 min · Prerequisite: Day 6
Briefing
- A Dockerfile can be more than one pipeline stage:
testonly runs on request (--target test),finalcontains none of it. - BuildKit only builds stages the target depends on, and independent stages in parallel.
FROM --platform=$BUILDPLATFORMlets the compiler run natively; Go compiles viaGOOS/GOARCHfor the target platform.COPY --linkputs files into a separate layer that doesn’t depend on the base image.
┌──► test (go vet, go test) only with --target test
base ──────────┤
(BUILDPLATFORM) └──► build (GOOS/GOARCH = target) ──► final (scratch, COPY --link)
Drill 1: Four stages, one 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/." .The second copy lays the state from the end of Day 6 on top – even if you skipped it. Today notes-api first gets a test, so that the test stage has something to do:
cat > notes-api/main_test.go <<'EOF'
package main
import (
"net/http"
"net/http/httptest"
"strings"
"testing"
)
// Lab value, not a real 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)
}
}
}
EOFNow the new Dockerfile. Everything from Day 2 to Day 5 stays; only the stages are cut differently:
cat > notes-api/Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
ARG GO_VERSION=1.27
# base: shared by test and build, always runs on the builder's platform
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: only with --target test (CI); not part of the 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 for the target platform, without 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: only CA certificates and the 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-apiExpected (abbreviated, may vary by version):
[+] 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 is silent, so are the build checks, exit code 0.
final is the last stage and thus the default target. Build
and count which stages ran:
docker build --progress=plain -t notes-api:tag07 notes-api 2>&1 \
| grep -oE '\[(base|test|build|final) ' | sort | uniq -cExpected (abbreviated, may vary by version):
5 [base
1 [build
3 [final
No [test: BuildKit built the dependency graph starting
from final, and test doesn’t appear in it. So
the test costs nothing in the normal build.
Save your progress? Sign up for free
Drill 2: Test stage for CI
docker build --progress=plain --target test -t notes-api:tag07-test notes-api 2>&1 \
| grep -E 'go vet|ok |FAIL|ERROR'Expected (abbreviated, may vary by version):
#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 came entirely from the cache of Drill 1; only the
test ran. Now you deliberately break a test (the correct status code
would be 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]}"Expected (abbreviated, may vary by version):
#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
On Linux it’s sed -i without ''. Exit code
1 is enough for any CI to stop the pipeline. You fix the test with the
copy from the companion code:
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: $?"Expected:
Exit: 0
Tip: In GitLab or GitHub Actions this is a separate job
docker build --target test …before the build job. Both sharebasevia the registry cache (Day 4).
Save your progress? Sign up for free
Drill 3: ARG before FROM and the platform ARGs
GO_VERSION comes before the first FROM,
i.e. in the global scope: it may appear in FROM lines, but
is unknown inside the stages. The same applies to the automatic platform
ARGs. Try it with a throwaway 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)'
doneExpected (abbreviated, may vary by version):
#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)
Before the ARG (“vorher” = before),
TARGETARCH is empty; only the line without a value brings
it into the stage (“nachher” = after). In
FROM --platform=$BUILDPLATFORM it works without a
declaration, because FROM sees the global scope. And
because the stage is pinned to BUILDPLATFORM, the
RUN ran natively on arm64 in both cases. That’s exactly
what the build stage of notes-api uses.
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/nullExpected:
0.7.0
Save your progress? Sign up for free
Drill 4: Cross-compile for two platforms
You build multi-platform images with the builder
docker-lab and push them directly to the 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-apiExpected (abbreviated, may vary by version):
[+] 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
You see three things here: base runs only once (both
targets use the same arm64 stage), the two build stages run
in parallel, and arm64->amd64 means: the compiler runs
natively, only its result is amd64. What’s in the registry:
docker buildx imagetools inspect localhost:5001/notes-api:tag07Expected (abbreviated, digests differ):
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
One tag, one index, below it one manifest per platform. The
unknown/unknown entries are provenance attestations that
the docker-container driver attaches by default (Day 10).
Whoever pulls the image automatically gets their platform:
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/nullExpected:
linux/arm64
0.7.0
Warning: Without
--platform=$BUILDPLATFORMin thebasestage, BuildKit would pull an amd64golangimage for amd64 and emulate the compiler via QEMU, if the VM even has an emulator for it. That is usually many times slower.
Save your progress? Sign up for free
Drill 5: Provoke an exec format error
What happens when an image for the wrong architecture lands on your
machine? riscv64 is suitable because usually no emulator is
registered for it:
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-riscv64Expected (abbreviated, may vary by version):
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
The build worked because nothing was executed in the target image:
compilation happened on arm64, and final consists only of
COPY. Only the kernel at startup recognizes the foreign
architecture. If the container runs anyway on your machine, your VM has
an emulator for riscv64 registered; check with
colima ssh -- ls /proc/sys/fs/binfmt_misc.
Tip: If
exec format errorshows up in CI or on the cluster, first rundocker buildx imagetools inspect <image>(which platforms exist?) anddocker image inspect --format '{{.Architecture}}'(which one is local?).
Save your progress? Sign up for free
Drill 6: COPY --link
A normal COPY depends on the state before it: if the
base image changes, every following layer is invalid. With
--link, the copy lands in a separate, empty layer that is
simply placed on top. The demo Dockerfile.link shows this;
its runtime image can be chosen via ARG RUNTIME:
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'
doneExpected (abbreviated, may vary by version):
FROM ${RUNTIME}
COPY --link --from=build /out/notes-api /notes-api
USER 65532:65532
ENTRYPOINT ["/notes-api"]
#12 DONE 0.1s
#12 CACHED
In the second build the runtime image is a different one, yet the
COPY --link comes from the cache. Counter-check without
--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.DockerfileExpected (abbreviated, may vary by version):
#12 DONE 0.1s
#12 DONE 0.1s
For a 6 MB binary it doesn’t matter. For large layers (a
node_modules, a JDK, model files), --link
saves real rebuilding and uploading when the base image changes,
especially together with --cache-from.
Warning: Under
--link, theCOPYdoesn’t see the previous content. That’s why--chownonly works with numeric IDs, symlinks in the destination aren’t followed, and copied directories keep the permissions of the source.
Save your progress? Sign up for free
Drill 7: COPY --from a foreign
image
--from accepts not only stage names, but any image.
That’s how you fetch individual files or ready-made binaries (like
uv on Day 6) without a package manager in your own image.
With -o, the result of a build even lands directly as files
on the 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 outExpected (abbreviated, may vary by version):
-rw-r--r-- 1 du staff 392K … zoneinfo.zip
No build context (-), no stage, just one file from a
foreign image. A Go binary in scratch finds time zones via
ENV ZONEINFO=/zoneinfo.zip, if you need them (Day 5). Clean
up:
rm -rf outSecurity: A foreign image in
COPY --fromis a dependency like any base image. Pin it at least to a version, in production to a digest (Day 8).
Save your progress? Sign up for free
Checkpoint
Four stages, base runs on the build platform:
cd ~/docker-lab/tag07
grep '^FROM' notes-api/DockerfileExpected:
FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine AS base
FROM base AS test
FROM base AS build
FROM scratch AS final
COPY --link in the final stage:
grep -c 'COPY --link' notes-api/DockerfileExpected:
2
The build checks are silent:
docker build --check notes-api 2>&1 | tail -1Expected:
Check complete, no warnings found.
The tests are green:
docker build -q --target test notes-api >/dev/null; echo "Exit: $?"Expected:
Exit: 0
The registry has both platforms (Drill 4):
docker buildx imagetools inspect localhost:5001/notes-api:tag07 | grep PlatformExpected:
Platform: linux/amd64
Platform: linux/arm64
Platform: unknown/unknown
Platform: unknown/unknown
Challenge
Play through a small pipeline by hand: first the test stage, only on
success the build for linux/amd64,linux/arm64 with version
0.7.1 to localhost:5001/notes-api:tag07, and
finally the check whether the registry really has both platforms. Also
check what a broken test does.
Hint: && only runs the second
command if the first one succeeded. You recognize attestations in
imagetools inspect by unknown/unknown, one per
platform.
Solution
Test first, then push – in one line with &&:
cd ~/docker-lab/tag07
docker build -q --target test notes-api >/dev/null && echo "Tests grün"Expected:
Tests grün
Only then the multi-platform 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 PlatformExpected (abbreviated, digest differs):
sha256:159974c547fe…
Platform: linux/amd64
Platform: linux/arm64
Platform: unknown/unknown
Platform: unknown/unknown
Now a broken 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/Expected (abbreviated):
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
No “Tests grün” (tests green), exit code not 0: a pipeline aborts here, the push never happens, and the registry still shows version 0.7.1. Finally, clean up:
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 --forceSave your progress? Sign up for free
Enterprise Note
- In CI,
testand the image build are separate jobs on the same Dockerfile; both pullbasefrom the registry cache (Day 4), and you fetch test reports via--output type=localfrom a dedicated stage. - With cross-compilation, multi-platform costs hardly any time. For languages without cross-compilation (native Python wheels, Node addons), use native arm64 runners instead of QEMU.
- Kubernetes clusters with mixed nodes (Graviton, Apple Silicon
developers, x86 CI) need an index with all platforms, otherwise
exec format errorat pod start. COPY --linkmakes rebasing onto a patched base image cheap; paired with automatic base image updates (Day 8), a security fix becomes a matter of minutes.- External images in
COPY --frombelong in the same inventory as base images: mirroring, pinning, scanning.