Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 2: Anweisungen im Detail

Ziel: Das Dockerfile von notes-api um ENTRYPOINT, ARG, LABEL, EXPOSE, USER, STOPSIGNAL und HEALTHCHECK erweitern 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 stop schickt das Stop-Signal (Standard SIGTERM) und nach 10 Sekunden SIGKILL. Wer 10 Sekunden wartet, hat ein Signal-Problem.
  • ARG gilt nur beim Bauen, ENV auch im Container. Ein ARG vor FROM gilt nur für FROM.
  • HEALTHCHECK, USER, EXPOSE, LABEL und STOPSIGNAL schreiben 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 -3

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

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

Erwartet (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-sleep

Erwartet (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 30 oder docker run --stop-timeout 30 geben 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-60

Erwartet (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/version

Erwartet (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 Container healthy.
  • --start-interval=1s: Während der Start-Phase prüft Docker jede Sekunde statt im Standardabstand von 5 s. Der Container wird schnell healthy, im Betrieb gilt danach --interval=10s.
  • --timeout=2s: Ein Check, der länger braucht, gilt als fehlgeschlagen.

Achtung: --start-interval braucht Docker Engine 25.0 oder neuer und ein Dockerfile-Frontend ab 1.6.0; mit docker/dockerfile:1 und 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-api

Erwartet (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. USER schü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:tag02

Erwartet (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 nach EOT behebt das und liest sich ohnehin besser.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Das Dockerfile von heute:

cd ~/docker-lab/tag02
cat notes-api/Dockerfile

Erwartet:

# 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:tag02

Erwartet:

65532:65532

Der Healthcheck steckt im Image:

docker image inspect --format '{{json .Config.Healthcheck.Test}}' notes-api:tag02

Erwartet:

["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-stop

Erwartet (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-stop

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

Erwartet (gekürzt, Namen, IDs und Größen weichen ab):

Untagged: notes-api:tag02
Deleted: sha256:…
…
Total:  …

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Kubernetes wertet HEALTHCHECK aus dem Image nicht aus; dort übernehmen Liveness-, Readiness- und Startup-Probes. Der Healthcheck bleibt für Docker und Compose nützlich, der Befehl notes-api healthcheck lässt sich als exec-Probe weiterverwenden.
  • Kubernetes wartet nach SIGTERM standardmäß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, dass runAsNonRoot sie 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.source werten 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).