Tag 2: Anweisungen im Detail
Ziel: Das Dockerfile von
notes-apiumENTRYPOINT,ARG,LABEL,EXPOSE,USER,STOPSIGNALundHEALTHCHECKerweitern und verstehen, warum der Container jetzt in unter einer Sekunde sauber stoppt. · Dauer: ca. 75 min · Voraussetzung: Tag 1
Briefing
- Shell-Form (
CMD notes-api) startet/bin/sh -c …; die Shell wird PID 1 und reicht Signale nicht weiter. Exec-Form (CMD ["notes-api"]) startet das Programm direkt als PID 1. docker stopschickt das Stop-Signal (StandardSIGTERM) und nach 10 SekundenSIGKILL. Wer 10 Sekunden wartet, hat ein Signal-Problem.ARGgilt nur beim Bauen,ENVauch im Container. EinARGvorFROMgilt nur fürFROM.HEALTHCHECK,USER,EXPOSE,LABELundSTOPSIGNALschreiben Metadaten in die Image-Konfiguration, keine Dateien.
docker stop ──SIGTERM──► PID 1 ──?──► notes-api
Shell-Form: PID 1 = /bin/sh -c … Signal verpufft ─► 10 s ─► SIGKILL
Exec-Form: PID 1 = notes-api Graceful Shutdown in < 1 s
Drill 1: Shell-Form und das 10-Sekunden-Problem
source ~/docker-lab/setup/env.sh
mkdir -p ~/docker-lab/tag02 && cd ~/docker-lab/tag02
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag01/notes/." .Die zweite Kopie legt den Stand vom Ende von Tag 1 darüber – auch
wenn du ihn übersprungen hast. Zuerst ein Gegenbeispiel aus dem
Begleitcode: dasselbe Image wie an Tag 1, aber mit einem
CMD in Shell-Form, das die Logs zusätzlich in eine Datei
schreibt.
cp "$LAB/code/tag02/Dockerfile.shell" notes-api/
tail -1 notes-api/Dockerfile.shell
docker build -f notes-api/Dockerfile.shell -t notes-api:shell notes-api 2>&1 | tail -3Erwartet (gekürzt, kann je nach Version abweichen):
CMD notes-api 2>&1 | tee /tmp/notes-api.log
1 warning found (use docker --debug to expand):
- JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended
behavior related to OS signals (line 7)
BuildKit warnt. Du startest trotzdem und schaust, wer PID 1 ist:
docker run -d --name notes-api -e NOTES_API_KEY=lab-api-key-123 notes-api:shell
docker exec notes-api ps -o pid,args
/usr/bin/time -p docker stop notes-api
docker logs notes-api | tail -1
docker rm notes-apiErwartet (gekürzt, kann je nach Version abweichen):
PID COMMAND
1 /bin/sh -c notes-api 2>&1 | tee /tmp/notes-api.log
7 notes-api
8 tee /tmp/notes-api.log
notes-api
real 10.21
user 0.02
sys 0.01
time=… level=INFO msg=listening addr=:8080 version=dev pid=7
notes-api
PID 1 ist die Shell. Sie bekommt SIGTERM, reicht es
nicht an notes-api weiter und beendet sich selbst nicht.
Nach 10 Sekunden kommt SIGKILL,
shutdown complete fehlt im Log: Offene Anfragen wären
abgebrochen worden.
Fortschritt speichern? Kostenlos registrieren
Drill 2: ENTRYPOINT und CMD
Jetzt die Exec-Form, und statt CMD ein
ENTRYPOINT:
cat > notes-api/Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
FROM golang:1.27-alpine
WORKDIR /src
COPY . .
RUN go build -o /usr/local/bin/notes-api .
ENTRYPOINT ["notes-api"]
EOF
docker build -q -t notes-api:tag02 notes-api
docker run --rm notes-api:tag02 healthcheck; echo "Exit-Code: $?"
docker run --rm --entrypoint sh notes-api:tag02 -c 'echo "PID $$"; which notes-api'Erwartet (gekürzt, kann je nach Version abweichen):
sha256:c41f…
Exit-Code: 1
PID 1
/usr/local/bin/notes-api
healthcheck hinter dem Image-Namen wird an das
ENTRYPOINT angehängt: Der Container führt
notes-api healthcheck aus. Exit 1, weil kein Server läuft.
--entrypoint ersetzt das Programm selbst.
| Dockerfile | docker run IMAGE |
docker run IMAGE healthcheck |
|---|---|---|
CMD ["notes-api"] |
notes-api |
healthcheck (ersetzt CMD) |
ENTRYPOINT ["notes-api"] |
notes-api |
notes-api healthcheck |
ENTRYPOINT ["notes-api"] +
CMD ["--help"] |
notes-api --help |
notes-api healthcheck |
ENTRYPOINT notes-api (Shell-Form) |
/bin/sh -c notes-api |
Argumente ignoriert |
Und der Stopp?
docker run -d --name notes-api -e NOTES_API_KEY=lab-api-key-123 notes-api:tag02
docker exec notes-api ps -o pid,args
/usr/bin/time -p docker stop notes-api
docker logs notes-api | tail -2
docker rm notes-apiErwartet (gekürzt, kann je nach Version abweichen):
PID COMMAND
1 notes-api
notes-api
real 0.31
user 0.02
sys 0.01
time=… level=INFO msg="signal received, shutting down"
time=… level=INFO msg="shutdown complete"
notes-api
notes-api ist PID 1, bekommt SIGTERM direkt
und fährt sauber herunter.
Fortschritt speichern? Kostenlos registrieren
Drill 3: PID 1 und --init
notes-api fängt SIGTERM selbst ab. Nicht
jedes Programm tut das, und für PID 1 gilt eine Sonderregel des
Linux-Kernels: Signale ohne eigenen Handler werden ignoriert, statt den
Prozess zu beenden. sleep hat keinen Handler:
docker run -d --name notes-sleep golang:1.27-alpine sleep 300
/usr/bin/time -p docker stop notes-sleep 2>&1 | grep real
docker rm notes-sleep
docker run -d --init --name notes-sleep golang:1.27-alpine sleep 300
docker exec notes-sleep ps -o pid,args
/usr/bin/time -p docker stop notes-sleep 2>&1 | grep real
docker rm notes-sleepErwartet (gekürzt, kann je nach Version abweichen):
notes-sleep
real 10.18
notes-sleep
…
PID COMMAND
1 /sbin/docker-init -- sleep 300
7 sleep 300
real 0.27
notes-sleep
--init setzt docker-init als PID 1 davor.
Es basiert auf tini, reicht Signale an seinen Kindprozess weiter und
räumt Zombie-Prozesse ab. Für notes-api brauchst du es
nicht, für Shell-Skripte und Programme, die Kindprozesse starten, oft
schon.
Tipp: Die Wartezeit ist kein festes Gesetz:
docker stop -t 30oderdocker run --stop-timeout 30geben einem langsamen Dienst mehr Zeit. Erst Signale reparieren, dann über Timeouts reden.
Fortschritt speichern? Kostenlos registrieren
Drill 4: ARG, ENV und ihr Gültigkeitsbereich
Das Demo-Dockerfile im Begleitcode gibt drei Variablen aus, einmal
vor und einmal nach einem zweiten ARG GO_VERSION:
grep -v '^#' "$LAB/code/tag02/scope/Dockerfile"
docker build --no-cache --progress=plain --build-arg BUILD_NOTE=hallo \
-t notes-scope:tag02 "$LAB/code/tag02/scope" 2>&1 \
| grep 'GO_VERSION=\[' | grep -v 'RUN echo'Erwartet (Build-Ausgabe gekürzt, kann je nach Version abweichen):
ARG GO_VERSION=1.27
FROM golang:${GO_VERSION}-alpine
ARG BUILD_NOTE=ohne-notiz
ENV APP_MODE=lab
RUN echo "GO_VERSION=[${GO_VERSION}] BUILD_NOTE=[${BUILD_NOTE}] APP_MODE=[${APP_MODE}]"
ARG GO_VERSION
RUN echo "nach erneutem ARG: GO_VERSION=[${GO_VERSION}]"
#6 0.142 GO_VERSION=[] BUILD_NOTE=[hallo] APP_MODE=[lab]
#7 0.118 nach erneutem ARG: GO_VERSION=[1.27]
Das ARG vor FROM gilt nur für
FROM. Im Stage ist es leer, bis du es dort ohne Wert noch
einmal deklarierst; dann übernimmt es den Standardwert.
--build-arg überschreibt den Standardwert von
BUILD_NOTE. Was davon steckt im fertigen Image?
docker image inspect --format '{{json .Config.Env}}' notes-scope:tag02 \
| jq -r '.[]' | grep -E '^(APP_MODE|BUILD_NOTE|GO_VERSION)='
docker history --no-trunc --format '{{.CreatedBy}}' notes-scope:tag02 \
| grep '^RUN' | cut -c1-60Erwartet (gekürzt, kann je nach Version abweichen):
APP_MODE=lab
RUN |2 BUILD_NOTE=hallo GO_VERSION=1.27 /bin/sh -c echo "nach
RUN |1 BUILD_NOTE=hallo /bin/sh -c echo "GO_VERSION=[${GO_VERSION
ENV landet in der Konfiguration und gilt in jedem
Container. ARG nicht, aber sein Wert steht in der History
jedes RUN, das ihn sehen konnte.
Sicherheit: Darum gehört kein Secret in ein
ARG, auch kein „nur beim Bauen” gebrauchtes. Tag 11 zieht so einen Key aus der History, Tag 13 zeigt den richtigen Weg.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Das vollständige Dockerfile
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 . .
ARG VERSION=dev
RUN go build -ldflags "-X main.version=${VERSION}" -o /usr/local/bin/notes-api .
EXPOSE 8080
USER 65532:65532
STOPSIGNAL SIGTERM
HEALTHCHECK --interval=10s --timeout=2s --start-period=5s --start-interval=1s \
CMD ["notes-api", "healthcheck"]
ENTRYPOINT ["notes-api"]
EOF
hadolint notes-api/Dockerfile && echo "hadolint: ok"Erwartet:
hadolint: ok
| Anweisung | Wirkung |
|---|---|
ARG GO_VERSION vor FROM |
Go-Version zentral umstellbar:
--build-arg GO_VERSION=… |
LABEL org.opencontainers.image.* |
OCI-Annotationen: Name, Beschreibung, Quelle |
ARG VERSION + -ldflags "-X …" |
Version zur Build-Zeit ins Binary, sichtbar unter
/version |
EXPOSE 8080 |
Dokumentation des Ports; veröffentlicht wird erst mit
-p |
USER 65532:65532 |
Prozess und Healthcheck laufen ohne root (numerisch, Tag 9) |
STOPSIGNAL SIGTERM |
Signal für docker stop; ist ohnehin Standard, hier
explizit |
HEALTHCHECK … CMD [...] |
Docker prüft regelmäßig per Exit-Code 0/1, ohne curl im Image |
Das Begleitcode-Original liegt unter
~/docker-lab/code/tag02/notes/notes-api/Dockerfile. Bauen
mit Version:
docker build -q --build-arg VERSION=0.2.0 -t notes-api:tag02 notes-api
docker image inspect notes-api:tag02 | jq '.[0].Config
| {User, ExposedPorts, StopSignal, Entrypoint, Cmd, Healthcheck, Labels}'Erwartet (gekürzt, kann je nach Version abweichen):
sha256:8d02…
{
"User": "65532:65532",
"ExposedPorts": { "8080/tcp": {} },
"StopSignal": "SIGTERM",
"Entrypoint": [ "notes-api" ],
"Cmd": null,
"Healthcheck": {
"Test": [ "CMD", "notes-api", "healthcheck" ],
"Interval": 10000000000,
"Timeout": 2000000000,
"StartPeriod": 5000000000,
"StartInterval": 1000000000
},
"Labels": {
"org.opencontainers.image.description": "Notiz-API aus dem Trainingslager",
"org.opencontainers.image.source": "https://example.com/docker-lab/notes",
"org.opencontainers.image.title": "notes-api"
}
}
Alle Zeitangaben stehen in Nanosekunden. Image-Größen, Digests und Zeiten in diesem Kapitel weichen bei dir ab.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Healthcheck beobachten
docker run -d --name notes-api -p 127.0.0.1:8080:8080 \
-e NOTES_API_KEY=lab-api-key-123 notes-api:tag02
docker ps --filter name=^notes-api$ --format '{{.Status}}'
sleep 3
docker ps --filter name=^notes-api$ --format '{{.Status}}'
docker inspect --format '{{json .State.Health}}' notes-api \
| jq '{Status, FailingStreak, Last: .Log[-1].ExitCode}'
curl -s localhost:8080/versionErwartet (gekürzt, kann je nach Version abweichen):
…
Up Less than a second (health: starting)
Up 3 seconds (healthy)
{
"Status": "healthy",
"FailingStreak": 0,
"Last": 0
}
0.2.0
Die Optionen im Zusammenspiel:
--start-period=5s: Fehlschläge in den ersten 5 s zählen nicht gegen--retries(Standard 3). Ein erfolgreicher Check in dieser Zeit macht den Containerhealthy.--start-interval=1s: Während der Start-Phase prüft Docker jede Sekunde statt im Standardabstand von 5 s. Der Container wird schnellhealthy, im Betrieb gilt danach--interval=10s.--timeout=2s: Ein Check, der länger braucht, gilt als fehlgeschlagen.
Achtung:
--start-intervalbraucht Docker Engine 25.0 oder neuer und ein Dockerfile-Frontend ab 1.6.0; mitdocker/dockerfile:1und Docker 29 ist beides erfüllt. Ältere Engines kennen die Option nicht.
Fortschritt speichern? Kostenlos registrieren
Drill 7: USER und STOPSIGNAL im Betrieb
Der Container aus Drill 6 läuft noch.
docker exec notes-api id
docker exec notes-api touch /src/spur; echo "Exit-Code: $?"
/usr/bin/time -p docker stop notes-api 2>&1 | grep real
docker logs notes-api | tail -2
docker rm notes-apiErwartet (gekürzt, kann je nach Version abweichen):
uid=65532 gid=65532 groups=65532
touch: /src/spur: Permission denied
Exit-Code: 1
real 0.29
time=… level=INFO msg="signal received, shutting down"
time=… level=INFO msg="shutdown complete"
notes-api
UID 65532 hat keinen Eintrag in /etc/passwd, das ist in
Ordnung: Der Kernel kennt nur Zahlen. Weil /src root
gehört, kann der Prozess dort nichts schreiben. Für die API ist das
richtig so, sie hält alles im Speicher. Mehr zu Rechten an Tag 9.
Tipp:
docker exec -u 0 notes-api shöffnet zum Debuggen trotzdem eine root-Shell.USERschützt den Dienst, nicht vor jemandem, der den Docker-Daemon bedienen darf.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Heredocs in RUN und COPY
Heredocs sind seit Dockerfile-Frontend 1.4.0 stabil.
RUN <<EOT übergibt mehrere Zeilen als Skript an die
Shell, COPY <<EOT datei schreibt den Text als Datei
ins Image.
grep -v '^#' "$LAB/code/tag02/heredoc/Dockerfile"Erwartet:
FROM golang:1.27-alpine
ARG VERSION=dev
COPY <<EOT /etc/notes/banner.txt
notes-api ${VERSION} – gebaut im Trainingslager
EOT
COPY <<"EOT" /usr/local/bin/notes-info
echo "Banner: $(cat /etc/notes/banner.txt)"
echo "Laufzeit-User: $(id -u)"
EOT
RUN <<EOT
set -eu
chmod 0755 /usr/local/bin/notes-info
mkdir -p /var/lib/notes
date -u +%Y-%m-%d > /var/lib/notes/built
EOT
CMD ["notes-info"]
Die Shebang-Zeile #!/bin/sh von notes-info
hat grep -v '^#' mit herausgefiltert, in der Datei steht
sie. Bauen und starten:
docker build -q --build-arg VERSION=0.2.0 -t notes-heredoc:tag02 \
"$LAB/code/tag02/heredoc"
docker run --rm notes-heredoc:tag02
docker run --rm --user 65532 notes-heredoc:tag02Erwartet (gekürzt, kann je nach Version abweichen):
sha256:1be7…
Banner: notes-api 0.2.0 – gebaut im Trainingslager
Laufzeit-User: 0
Banner: notes-api 0.2.0 – gebaut im Trainingslager
Laufzeit-User: 65532
Ohne Anführungszeichen (<<EOT) ersetzt BuildKit
${VERSION} beim Bauen. Mit <<"EOT"
bleibt der Text wörtlich, $(cat …) wird erst zur Laufzeit
ausgewertet. Im RUN-Heredoc sorgt set -eu
dafür, dass ein Fehler in der Mitte den Build abbricht; ohne zählt wie
bei jeder Shell nur der Exit-Code der letzten Zeile.
Tipp: hadolint 2.14 stolpert über ein Heredoc, auf dessen Ende-Marker direkt die nächste Anweisung folgt (
unexpected 'R' expecting a new line). Eine Leerzeile nachEOTbehebt das und liest sich ohnehin besser.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Das Dockerfile von heute:
cd ~/docker-lab/tag02
cat notes-api/DockerfileErwartet:
# 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 . .
ARG VERSION=dev
RUN go build -ldflags "-X main.version=${VERSION}" -o /usr/local/bin/notes-api .
EXPOSE 8080
USER 65532:65532
STOPSIGNAL SIGTERM
HEALTHCHECK --interval=10s --timeout=2s --start-period=5s --start-interval=1s \
CMD ["notes-api", "healthcheck"]
ENTRYPOINT ["notes-api"]hadolint hat nichts zu meckern:
hadolint notes-api/Dockerfile; echo "Exit: $?"Erwartet:
Exit: 0
Das Image läuft als UID 65532:
docker image inspect --format '{{.Config.User}}' notes-api:tag02Erwartet:
65532:65532
Der Healthcheck steckt im Image:
docker image inspect --format '{{json .Config.Healthcheck.Test}}' notes-api:tag02Erwartet:
["CMD","notes-api","healthcheck"]
Challenge
Vergleiche notes-api:shell mit
notes-api:tag02: Wie lange dauert docker stop,
und steht shutdown complete im Log?
Hinweis: time misst die Dauer eines
Befehls, die Logs eines gestoppten Containers liest
docker logs weiterhin.
Lösung
Erst die Shell-Form:
docker run -d --name notes-stop -e NOTES_API_KEY=lab-api-key-123 notes-api:shell
time docker stop notes-stop
docker logs notes-stop 2>&1 | tail -1
docker rm notes-stopErwartet (gekürzt, ID und Zeiten weichen ab):
4ae1f1994964…
notes-stop
real 0m10.396s
…
time=… level=INFO msg=listening addr=:8080 version=dev pid=8
notes-stop
Dann die Exec-Form von heute:
docker run -d --name notes-stop -e NOTES_API_KEY=lab-api-key-123 notes-api:tag02
time docker stop notes-stop
docker logs notes-stop 2>&1 | tail -1
docker rm notes-stopErwartet (gekürzt, ID und Zeiten weichen ab):
c2fbaa868cd2…
notes-stop
real 0m0.379s
…
time=… level=INFO msg="shutdown complete"
notes-stop
Eine Zeile Unterschied im Dockerfile, zehn Sekunden Unterschied bei jedem Deployment und jedem Neustart. 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 --forceErwartet (gekürzt, Namen, IDs und Größen weichen ab):
Untagged: notes-api:tag02
Deleted: sha256:…
…
Total: …
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Kubernetes wertet
HEALTHCHECKaus dem Image nicht aus; dort übernehmen Liveness-, Readiness- und Startup-Probes. Der Healthcheck bleibt für Docker und Compose nützlich, der Befehlnotes-api healthchecklässt sich alsexec-Probe weiterverwenden. - Kubernetes wartet nach
SIGTERMstandardmäßig 30 s (terminationGracePeriodSeconds). Ein Dienst, der Signale ignoriert, verzögert jedes Rollout um genau diese Zeit. - Eine numerische
USER-ID ist Voraussetzung dafür, dassrunAsNonRootsie prüfen kann. OpenShift vergibt ohnehin eine zufällige UID mit Gruppe 0; Dateien, die der Dienst schreiben muss, brauchen dann Gruppenrechte. - OCI-Labels wie
org.opencontainers.image.sourcewerten Registries und Scanner aus; viele Plattform-Teams machen sie per Policy zur Pflicht (Tag 10). - Build-Argumente sind sichtbar: in der History, in CI-Logs, in Provenance-Attestations. Für Secrets gibt es Build-Secrets (Tag 13).