Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 4: Layer-Cache meistern

Ziel: Das Dockerfile so ordnen, dass eine Codeänderung nur noch den Build-Schritt neu ausführt, Cache-Mounts für Go nutzen und den Cache über die Registry teilen. · Dauer: ca. 75 min · Voraussetzung: Tag 3

Briefing

  • Jede Anweisung bekommt einen Cache-Schlüssel. Bei COPY zählt der Inhalt der Dateien, bei RUN der Befehlstext. Ein Fehlschlag macht alle folgenden Schritte ungültig.
  • Also: Was sich selten ändert (go.mod, go.sum) nach oben, was sich ständig ändert (Quellcode) nach unten.
  • RUN --mount=type=cache hält Download- und Compiler-Caches zwischen Builds, ohne sie ins Image zu legen.
  • Der Cache lebt im Builder. Mit --cache-to/--cache-from type=registry reist er über die Registry zu anderen Buildern, etwa in CI.
 FROM ─► WORKDIR ─► COPY go.mod go.sum ─► go mod download ─► COPY . . ─► go build
  ✔        ✔             ✔                     ✔               ✘           ✘
                                                           main.go     läuft neu
                                                           geändert

Drill 1: Den Cache brechen sehen

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

Die zweite Kopie legt den Stand vom Ende von Tag 3 darüber – auch wenn du ihn übersprungen hast. --progress=plain schreibt jeden Schritt als Text, grep lässt nur die Schrittnamen ([2/4]), Cache-Treffer und Go-Downloads stehen; time misst:

docker build -q -t notes-api:tag04 notes-api >/dev/null
echo '// cache-test 1' >> notes-api/main.go
time docker build --progress=plain -t notes-api:tag04 notes-api 2>&1 \
  | grep -E 'CACHED|/[0-9]\]|downloading'

Erwartet für den zweiten Lauf (gekürzt, kann je nach Version abweichen):

#6 [1/4] FROM docker.io/library/golang:1.27-alpine@sha256:d200d2dd76b0…
#8 [2/4] WORKDIR /src
#8 CACHED
#9 [3/4] COPY . .
#10 [4/4] RUN go build -ldflags "-X main.version=dev" -o /usr/local/bin/notes-api .
#10 0.703 go: downloading github.com/google/uuid v1.6.0

real    1m17.109s
…

Eine Kommentarzeile in main.go, und Go lädt die Abhängigkeiten neu und übersetzt alles von vorn. COPY . . hat einen neuen Cache-Schlüssel, also ist ab dort alles ungültig. Zeiten weichen bei dir ab, es geht um das Verhältnis zwischen den Läufen.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Abhängigkeiten zuerst

cat > notes-api/Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
ARG GO_VERSION=1.27
FROM golang:${GO_VERSION}-alpine
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"
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
ARG VERSION=dev
RUN go build -ldflags "-X main.version=${VERSION}" -o /usr/local/bin/notes-api .
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=2s --start-period=5s --start-interval=1s \
  CMD ["notes-api", "healthcheck"]
STOPSIGNAL SIGTERM
USER 65532:65532
ENTRYPOINT ["notes-api"]
EOF
docker build -q -t notes-api:tag04 notes-api >/dev/null
echo '// cache-test 2' >> notes-api/main.go
time docker build --progress=plain -t notes-api:tag04 notes-api 2>&1 \
  | grep -E 'CACHED|/[0-9]\]|downloading'

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

#6 [1/6] FROM docker.io/library/golang:1.27-alpine@sha256:d200d2dd76b0…
#8 [2/6] WORKDIR /src
#8 CACHED
#9 [3/6] COPY go.mod go.sum ./
#9 CACHED
#10 [4/6] RUN go mod download
#10 CACHED
#11 [5/6] COPY . .
#12 [6/6] RUN go build -ldflags "-X main.version=dev" -o /usr/local/bin/notes-api .

real    1m14.126s
…

Kein go: downloading mehr: Die Module liegen im Layer von Schritt 4, und der bleibt gültig, solange go.mod und go.sum gleich sind. Übersetzt wird aber weiterhin alles von vorn, deshalb ist es kaum schneller. Das ändert Drill 4.

Fortschritt speichern? Kostenlos registrieren

Drill 3: ARG an der richtigen Stelle

ARG VERSION steht jetzt direkt vor dem go build. Das hat einen Grund: Ein RUN hängt implizit von allen vorher deklarierten ARGs ab. Ein neuer Wert führt zum Cache-Fehlschlag beim ersten Schritt, der ihn benutzt – stünde ARG VERSION oben, liefe bei jedem Release auch go mod download neu.

time docker build --progress=plain --build-arg VERSION=0.4.0 \
  -t notes-api:tag04 notes-api 2>&1 | grep -E 'CACHED|/[0-9]\]|downloading'
docker run --rm -d --name notes-api -p 127.0.0.1:8080:8080 \
  -e NOTES_API_KEY=lab-api-key-123 notes-api:tag04
sleep 2 && curl -s localhost:8080/version && docker rm -f notes-api >/dev/null

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

#6 [1/6] FROM docker.io/library/golang:1.27-alpine@sha256:d200d2dd76b0…
…
#11 [5/6] COPY . .
#11 CACHED
#12 [6/6] RUN go build -ldflags "-X main.version=0.4.0" -o /usr/local/bin/notes-api .

real    1m12.574s
…
d49ab7c46435…
0.4.0

Nur der letzte Schritt läuft. Die ersten beiden Zeilen (FROM, WORKDIR) sind hier wie in Drill 2 und ausgelassen.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Cache-Mounts für Go

Go hat zwei Caches: Module unter /go/pkg/mod und übersetzte Pakete unter /root/.cache/go-build. Mit RUN --mount=type=cache überleben beide den Build, gehören aber nicht zum Image. Das ist das kanonische Dockerfile für heute:

cat > notes-api/Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
# Stand Ende Tag 4: Abhängigkeiten zuerst, Cache-Mounts für Module und Build-Cache.
ARG GO_VERSION=1.27
FROM golang:${GO_VERSION}-alpine
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"
WORKDIR /src
# 1. Nur die Abhängigkeitsliste – ändert sich selten, Layer bleibt im Cache
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download
# 2. Quellcode – ändert sich ständig, invalidiert nur noch das Folgende
COPY . .
# ARG erst hier: Ein neuer VERSION-Wert invalidiert nur den Build-Schritt
ARG VERSION=dev
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go build -ldflags "-X main.version=${VERSION}" -o /usr/local/bin/notes-api .
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=2s --start-period=5s --start-interval=1s \
  CMD ["notes-api", "healthcheck"]
STOPSIGNAL SIGTERM
USER 65532:65532
ENTRYPOINT ["notes-api"]
EOF
hadolint notes-api/Dockerfile && docker build --check notes-api
docker build -q -t notes-api:tag04 notes-api >/dev/null
echo '// cache-test 3' >> notes-api/main.go
time docker build --progress=plain -t notes-api:tag04 notes-api 2>&1 \
  | grep -E 'CACHED|/[0-9]\]|downloading'

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

Check complete, no warnings found.
#10 [stage-0 4/6] RUN --mount=type=cache,target=/go/pkg/mod     go mod download
#10 CACHED
#11 [stage-0 5/6] COPY . .
#12 [stage-0 6/6] RUN --mount=type=cache,target=/go/pkg/mod     --mount=type=cache,t…

real    0m9.400s
…

Von gut einer Minute auf neun Sekunden (Zeiten weichen bei dir ab): Go übersetzt nur noch das geänderte Paket, Standardbibliothek und uuid kommen aus dem Build-Cache. Beide Cache-Mounts nutzen dasselbe /go/pkg/mod, weil die id standardmäßig gleich dem target ist. Nebeneffekt: Die Module liegen nicht mehr in einem Layer des Images.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Cache-Mounts ansehen und leeren

Cache-Mounts sind Einträge vom Typ exec.cachemount im Builder. Damit du nicht den Cache anderer Projekte im Builder default löschst, baust du für diesen Drill mit dem Lab-Builder und lädst das Image mit --load nach docker image ls:

docker buildx build --builder docker-lab --load -q -t notes-api:tag04 notes-api \
  >/dev/null
docker buildx du --builder docker-lab --filter type=exec.cachemount
docker buildx prune --builder docker-lab --filter type=exec.cachemount -f >/dev/null
echo '// cache-test 4' >> notes-api/main.go
docker buildx build --builder docker-lab --load --progress=plain -t notes-api:tag04 \
  notes-api 2>&1 | grep -E 'go mod download|CACHED|go: downloading' | cut -c1-80

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

ID                              RECLAIMABLE     SIZE            LAST ACCESSED
k3v9x0w1q8m2p7r4t6y5u0i9o*      true            118.2MB         Less than a second ago
p0o9i8u7y6t5r4e3w2q1a2s3d*      true            6.81MB          Less than a second ago
#9 [4/6] RUN --mount=type=cache,target=/go/pkg/mod     go mod download
#9 CACHED
#11 0.341 go: downloading github.com/google/uuid v1.6.0

Das Layer von go mod download ist noch gültig, der Cache-Mount dahinter aber leer. Der Build funktioniert trotzdem, weil go build fehlende Module selbst lädt. Genau so musst du Cache-Mounts behandeln: als Beschleunigung, nie als Voraussetzung. Die Doku sagt es deutlich: Ein anderer Build oder die Garbage Collection darf den Inhalt jederzeit überschreiben oder löschen.

Option Standard Wofür
id Wert von target Cache unter eigenem Namen, auch über Dockerfiles hinweg
sharing shared private: eigene Kopie je Build, locked: Builds warten
ro aus Cache nur lesen
uid, gid, mode 0, 0, 0755 Rechte des neuen Cache-Ordners, z. B. für non-root

sharing=locked brauchen Paketmanager, die exklusiven Zugriff verlangen, die Doku nennt apt als Beispiel. An Tag 6 kommen dieselben Mounts für die anderen Dienste:

# uv (notes-worker): Hardlinks gehen aus dem Cache-Mount nicht, also kopieren
ENV UV_LINK_MODE=copy
RUN --mount=type=cache,target=/root/.cache/uv uv sync --locked
# npm (notes-web)
RUN --mount=type=cache,target=/root/.npm npm ci

Fortschritt speichern? Kostenlos registrieren

Drill 6: Bind-Mount statt COPY

Braucht das Image den Quellcode gar nicht, kannst du ihn nur für einen Schritt einblenden. --mount=type=bind hängt den Build-Kontext schreibgeschützt ein, nichts davon landet in einem Layer:

cp "$LAB/code/tag04/Dockerfile.bind" notes-api/
grep -A3 '^RUN' notes-api/Dockerfile.bind
docker build -q -f notes-api/Dockerfile.bind -t notes-api:tag04-bind notes-api
docker run --rm --entrypoint ls notes-api:tag04-bind -A /src | wc -l | tr -d ' '
docker history --format '{{.Size}}\t{{.CreatedBy}}' notes-api:tag04-bind \
  | head -7 | cut -c1-80

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

RUN --mount=type=bind,target=. \
    --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go build -ldflags "-X main.version=${VERSION}" -o /usr/local/bin/notes-api .
sha256:…
0
0B      ENTRYPOINT ["notes-api"]
0B      USER 65532:65532
0B      STOPSIGNAL SIGTERM
0B      HEALTHCHECK &{["CMD" "notes-api" "healthcheck"] "10s" "2s" "5s" "1s" '\x00'}
0B      EXPOSE map[8080/tcp:{}]
11.8MB  RUN |1 VERSION=dev /bin/sh -c go build -ldflags "-X main.version=${VERSIO
0B      ARG VERSION=dev

/src ist leer, es gibt kein COPY-Layer, nur das Binary. Die .dockerignore von Tag 3 gilt auch hier, denn der Bind-Mount zeigt den gefilterten Kontext. Ab Tag 5 erledigt Multi-Stage dasselbe Problem gründlicher; das kanonische Dockerfile bleibt deshalb bei COPY.

Fortschritt speichern? Kostenlos registrieren

Drill 7: --no-cache und --pull

Zwei Schalter, die du kennen musst, wenn der Cache zu gut funktioniert:

docker build -q --pull -t notes-api:tag04 notes-api
docker build --progress=plain --no-cache -t notes-api:tag04 notes-api 2>&1 \
  | grep -c CACHED

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

sha256:8e18a96ecc0f…
2

Die zwei CACHED gehören zum Dockerfile-Frontend und zum Kontext, kein Build-Schritt kommt aus dem Cache.

  • --pull fragt die Registry, ob es für golang:1.27-alpine einen neuen Digest gibt. Gibt es einen, ist ab FROM alles ungültig. So kommen Sicherheitsupdates ins Image.
  • --no-cache führt jeden Schritt neu aus. Der Cache eines RUN wird sonst nie von selbst ungültig: RUN apk upgrade bleibt für immer im Stand des ersten Builds.

Tipp: In CI ist --pull für nächtliche oder Release-Builds sinnvoll, für jeden Push meist nicht. Ein gepinnter Digest (Tag 8) macht das Verhalten vorhersagbar.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Cache über die Registry teilen

Ein frischer CI-Runner hat keinen Cache. Er kann ihn aber aus der Registry holen. Der Builder default kann Registry-Cache nur mit dem containerd-Image-Store exportieren; der Lab-Builder docker-lab kann es immer.

docker buildx build --builder docker-lab --progress=quiet \
  --cache-to type=registry,ref=localhost:5001/notes-api:buildcache,mode=max \
  --cache-from type=registry,ref=localhost:5001/notes-api:buildcache \
  -t localhost:5001/notes-api:tag04 --push notes-api
curl -s localhost:5001/v2/notes-api/tags/list | jq -c .

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

{"name":"notes-api","tags":["buildcache","tag04"]}

Jetzt den lokalen Cache des Builders löschen, wie auf einem neuen Runner, und neu bauen:

docker buildx prune --builder docker-lab --all -f >/dev/null
docker buildx build --builder docker-lab --progress=plain \
  --cache-from type=registry,ref=localhost:5001/notes-api:buildcache \
  -t localhost:5001/notes-api:tag04 --push notes-api 2>&1 \
  | grep -E 'importing cache|\[[0-9]/[0-9]\]|CACHED' | cut -c1-80

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

#4 importing cache manifest from localhost:5001/notes-api:buildcache
#7 [2/6] WORKDIR /src
#7 CACHED
#8 [3/6] COPY go.mod go.sum ./
#8 CACHED
#9 [4/6] RUN --mount=type=cache,target=/go/pkg/mod     go mod download
#9 CACHED
#10 [5/6] COPY . .
#10 CACHED
#11 [6/6] RUN --mount=type=cache,target=/go/pkg/mod     --mount=type=cache,targe
#11 CACHED

Alles aus der Registry, nichts neu gebaut. Die Parameter, die du kennen solltest:

Parameter Standard Bedeutung
mode min min: nur Layer des Ergebnis-Images, max: alle, auch Zwischenschritte
ignore-error false Build schlägt nicht fehl, wenn der Cache-Export scheitert
oci-mediatypes true OCI-Medientypen im Cache-Manifest
image-manifest true Image-Manifest statt Index (mit OCI-Medientypen)

Bei einem einstufigen Build wie heute sind min und max gleich, denn jedes Layer gehört zum Ergebnis. Ab Tag 5 hat max zusätzlich die Build-Stage im Cache.

Sicherheit: Der Registry-Cache enthält Layer, also Dateien. Mit mode=max auch die Zwischen-Stages, die du nie ausliefern wolltest. Was dort an Secrets liegt, liegt im Cache-Image. Lesbar ist es für jeden, der das Cache-Repository ziehen darf.

Cache-Mounts reisen übrigens nicht mit: Die Registry bekommt Layer, nicht den Inhalt von /go/pkg/mod oder /root/.cache/go-build. Die Docker-Doku sagt das ausdrücklich für den GitHub-Actions-Cache. Auf einem frischen Runner lädt go build die Module deshalb neu, sobald sich Code ändert.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

go.mod und go.sum stehen vor dem Quellcode, ARG VERSION danach:

cd ~/docker-lab/tag04
grep -n -E '^(COPY|ARG VERSION)' notes-api/Dockerfile

Erwartet:

10:COPY go.mod go.sum ./
14:COPY . .
16:ARG VERSION=dev

Drei Cache-Mounts:

grep -c 'type=cache' notes-api/Dockerfile

Erwartet:

3

Nach einer Codeänderung kommt go mod download aus dem Cache:

echo '// kontrollpunkt' >> notes-api/main.go
docker build --progress=plain -t notes-api:tag04 notes-api 2>&1 \
  | grep -A1 'go mod download$'

Erwartet (gekürzt):

#10 [stage-0 4/6] RUN --mount=type=cache,target=/go/pkg/mod     go mod download
#10 CACHED

Das Cache-Image liegt in der Registry:

curl -s localhost:5001/v2/notes-api/tags/list | jq -c .tags

Erwartet:

["buildcache","naiv","tag01","tag04"]

Challenge

Stell einen CI-Lauf auf einem frischen Runner nach: eigener, leerer Builder, Cache nur aus der Registry. Zuerst baut main und legt seinen Cache ab. Dann baut der Feature-Branch feature/farbe mit einer Codeänderung auf einem neuen Builder und nimmt den eigenen Cache, sonst den von main.

Hinweis: --cache-from darf mehrfach stehen. Ein Branch-Name wie feature/farbe ist kein gültiger Tag, im Tag wird daraus feature-farbe.

Lösung

Der Runner für main: Builder anlegen, bauen, Cache exportieren, Builder weg. $C kürzt den Namen des Cache-Images ab:

cd ~/docker-lab/tag04
C=localhost:5001/notes-api:buildcache
docker buildx create --name notes-ci --driver docker-container --driver-opt network=host
docker buildx build --builder notes-ci -q --push -t localhost:5001/notes-api:main \
  --cache-to type=registry,ref=$C-main,mode=max notes-api
docker buildx rm notes-ci

Erwartet (gekürzt):

notes-ci
sha256:76eee35db8d4…
notes-ci removed

Der Runner für den Feature-Branch fängt wieder leer an. Sein eigener Cache existiert noch nicht, also greift der zweite --cache-from:

echo '// feature' >> notes-api/main.go
docker buildx create --name notes-ci --driver docker-container --driver-opt network=host
docker buildx build --builder notes-ci --progress=plain --push \
  -t localhost:5001/notes-api:feature-farbe \
  --cache-from type=registry,ref=$C-feature-farbe \
  --cache-from type=registry,ref=$C-main \
  --cache-to type=registry,ref=$C-feature-farbe,mode=max notes-api 2>&1 \
  | grep -E 'importing cache|CACHED|downloading'
docker buildx rm notes-ci
curl -s localhost:5001/v2/notes-api/tags/list | jq -c .tags

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

notes-ci
#7 importing cache manifest from localhost:5001/notes-api:buildcache-main
#8 importing cache manifest from localhost:5001/notes-api:buildcache-feature-farbe
#11 CACHED
#12 CACHED
#13 CACHED
#15 0.321 go: downloading github.com/google/uuid v1.6.0
 > importing cache manifest from localhost:5001/notes-api:buildcache-feature-farbe:
notes-ci removed
["buildcache","buildcache-feature-farbe","buildcache-main","feature-farbe","main",…]

Die Zeile mit > meldet nur, dass es den Feature-Cache noch nicht gibt. Die Abhängigkeits-Layer kommen aus dem Cache von main, nur Quellcode und Build laufen neu. Das go: downloading zeigt die Grenze aus Drill 8: Der Cache-Mount war auf dem frischen Builder leer. In echter CI hängst du an --cache-to noch ignore-error=true an, damit ein kaputter Cache-Export den Build nicht scheitern lässt. 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

Die Cache-Tags bleiben in der Registry, wie in echt. Erst docker volume rm docker-lab-registry-data (Tag 0, Drill 9) löscht sie mit.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Cache-Repositories getrennt von Release-Images halten (…/notes-api-cache), mit eigener Retention und eigenen Leserechten, denn sie enthalten Zwischen-Layer.
  • main schreibt den Standard-Cache, Feature-Branches lesen ihn und schreiben ihren eigenen. Pull-Requests aus Forks bekommen keine Schreibrechte auf den Cache.
  • ignore-error=true beim Export: Ein volles Registry-Kontingent darf keinen Release-Build kippen. Beim Import ist ein fehlender Cache ohnehin nur eine Warnung.
  • GitLab-Runner mit Docker-in-Docker haben keinen dauerhaften Builder; ohne Registry-Cache baut dort jeder Job alles neu.
  • Cache-Mounts helfen nur auf langlebigen Buildern (eigene BuildKit-Instanz, Remote- Builder). Für flüchtige Runner zählt die Reihenfolge der Anweisungen doppelt.