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
COPYzählt der Inhalt der Dateien, beiRUNder 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=cachehält Download- und Compiler-Caches zwischen Builds, ohne sie ins Image zu legen.- Der Cache lebt im Builder. Mit
--cache-to/--cache-from type=registryreist 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/nullErwartet (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-80Erwartet (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 ciFortschritt 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-80Erwartet (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 CACHEDErwartet (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.
--pullfragt die Registry, ob es fürgolang:1.27-alpineeinen neuen Digest gibt. Gibt es einen, ist abFROMalles ungültig. So kommen Sicherheitsupdates ins Image.--no-cacheführt jeden Schritt neu aus. Der Cache einesRUNwird sonst nie von selbst ungültig:RUN apk upgradebleibt für immer im Stand des ersten Builds.
Tipp: In CI ist
--pullfü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-80Erwartet (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=maxauch 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/DockerfileErwartet:
10:COPY go.mod go.sum ./
14:COPY . .
16:ARG VERSION=dev
Drei Cache-Mounts:
grep -c 'type=cache' notes-api/DockerfileErwartet:
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 .tagsErwartet:
["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-ciErwartet (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 .tagsErwartet (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 --forceDie 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. mainschreibt den Standard-Cache, Feature-Branches lesen ihn und schreiben ihren eigenen. Pull-Requests aus Forks bekommen keine Schreibrechte auf den Cache.ignore-error=truebeim 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.