Skip to content
Hands-on IT IT Drills

Day 7: Advanced Patterns and Multi-Platform

Goal: Restructure notes-api into a Dockerfile with shared base, test, build and final stages 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: test only runs on request (--target test), final contains none of it.
  • BuildKit only builds stages the target depends on, and independent stages in parallel.
  • FROM --platform=$BUILDPLATFORM lets the compiler run natively; Go compiles via GOOS/GOARCH for the target platform.
  • COPY --link puts 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)
        }
    }
}
EOF

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

Expected (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 -c

Expected (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 share base via 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)'
done

Expected (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/null

Expected:

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

Expected (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:tag07

Expected (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/null

Expected:

linux/arm64
0.7.0

Warning: Without --platform=$BUILDPLATFORM in the base stage, BuildKit would pull an amd64 golang image 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-riscv64

Expected (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 error shows up in CI or on the cluster, first run docker buildx imagetools inspect <image> (which platforms exist?) and docker image inspect --format '{{.Architecture}}' (which one is local?).

Save your progress? Sign up for free

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'
done

Expected (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.Dockerfile

Expected (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, the COPY doesn’t see the previous content. That’s why --chown only 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 out

Expected (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 out

Security: A foreign image in COPY --from is 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/Dockerfile

Expected:

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

Expected:

2

The build checks are silent:

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

Expected:

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 Platform

Expected:

  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 Platform

Expected (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 --force

Save your progress? Sign up for free

Enterprise Note

  • In CI, test and the image build are separate jobs on the same Dockerfile; both pull base from the registry cache (Day 4), and you fetch test reports via --output type=local from 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 error at pod start.
  • COPY --link makes 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 --from belong in the same inventory as base images: mirroring, pinning, scanning.