Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 14: Laufzeit-Secrets

Ziel: Den API-Key als Datei unter /run/secrets/ statt als Umgebungsvariable an alle drei Dienste geben, prüfen, was danach noch sichtbar ist, und den Key ohne Rebuild rotieren. · Dauer: ca. 60 min · Voraussetzung: Tag 13

Briefing

  • Umgebungsvariablen sind bequem, aber gesprächig: docker inspect, docker compose config, docker exec … env, Kindprozesse und Crash-Dumps sehen sie.
  • Eine Datei unter /run/secrets/ sieht nur, wer im Container lesen darf. Die Anwendung bekommt per *_FILE-Variable nur den Pfad.
  • notes-api und notes-worker können das schon: NOTES_API_KEY_FILE hat Vorrang vor NOTES_API_KEY (Tag 0). notes-web nicht, dafür gibt es einen kleinen Wrapper.
  • Compose-Secrets kommen aus einer Datei (file:) oder einer Variablen auf deinem Rechner (environment:). Nur bei environment: wirken uid, gid und mode.
 secrets/notes_api_key.txt ──file:──► /run/secrets/notes_api_key ──► notes-api
 (nur lokal, .gitignore)               (Bind-Mount, read-only)        notes-worker
                                                                      notes-web
 Umgebung im Container:  NOTES_API_KEY_FILE=/run/secrets/notes_api_key  (kein Wert)

Drill 1: Ausgangslage – der Key in der Umgebung

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

Die zweite Kopie legt den Stand vom Ende von Tag 13 darüber – auch wenn du ihn übersprungen hast. Die Builds aus Tag 13 brauchen ihre Secrets und den artifact-server, also stellst du beides wieder her:

mkdir -p secrets
grep -qxF 'secrets/' .gitignore || echo 'secrets/' >> .gitignore
printf '%s' 'lab-artifact-token-123' > secrets/artifact_token.txt
cat > secrets/npmrc <<'EOF'
@notes-lab:registry=https://npm.lab.invalid/
//npm.lab.invalid/:_authToken=lab-npm-token-123
EOF
docker build -q -t notes-artifacts:tag14 "$LAB/code/tag13/artifact-server"
docker run -d --name notes-artifacts -p 127.0.0.1:8081:8081 \
  -e ARTIFACT_TOKEN_FILE=/run/token \
  -v "$PWD/secrets/artifact_token.txt:/run/token:ro" notes-artifacts:tag14
export ARTIFACT_TOKEN="$(cat secrets/artifact_token.txt)"
docker compose build --print | docker buildx bake -f - --allow network.host
docker compose up -d --no-build --wait

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

sha256:a28a889e66ef…
8b2e…
…
#47 naming to docker.io/library/notes-api:tag13 0.0s done
…
 Container notes-api Healthy
 Container notes-worker Healthy
 Container notes-web Healthy

Wie an Tag 13 baut docker buildx bake mit --allow network.host, danach startet up --no-build nur noch. Build-Zeiten, Größen und IDs weichen bei dir ab. Der Stand von Tag 12 und 13 holt den Key per env_file: .env. Drei Stellen, an denen ihn jeder mit Docker-Zugriff liest:

docker inspect -f '{{json .Config.Env}}' notes-api | jq -r '.[]' | grep NOTES_API
docker compose config | grep NOTES_API_KEY
docker exec notes-worker env | grep NOTES_API_KEY

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

NOTES_API_KEY=lab-api-key-123
      NOTES_API_KEY: lab-api-key-123
      NOTES_API_KEY: lab-api-key-123
      NOTES_API_KEY: lab-api-key-123
NOTES_API_KEY=lab-api-key-123

Dazu kommen Wege, die du nicht siehst: Jeder Kindprozess erbt die Umgebung, und Debug-Endpunkte, Fehlerberichte oder ein env im Support-Ticket geben sie weiter.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Die Secret-Datei

printf '%s' 'lab-api-key-123' > secrets/notes_api_key.txt
chmod 644 secrets/notes_api_key.txt
[ -d .git ] || git init -q
git check-ignore -v secrets/notes_api_key.txt
ls -l secrets

Erwartet (gekürzt, Zeilennummer und Datum weichen ab):

.gitignore:9:secrets/   secrets/notes_api_key.txt
-rw-r--r--  1 du  staff  22 Oct 29 10:02 artifact_token.txt
-rw-r--r--  1 du  staff  15 Oct 29 10:04 notes_api_key.txt
-rw-r--r--  1 du  staff  80 Oct 29 10:02 npmrc

chmod 644 ist Absicht: Eine Compose-Secret aus file: ist ein Bind-Mount der Datei. Im Container gelten deren Rechte, und User 65532 ist dort weder Besitzer noch Gruppe. Die strengere Variante folgt in Drill 6.

Sicherheit: Der Ordner secrets/ steht in .gitignore, aber nicht in der .dockerignore der Dienste. Das muss er auch nicht: Gebaut wird mit dem Dienstordner als Kontext, secrets/ liegt eine Ebene höher (Tag 3).

Fortschritt speichern? Kostenlos registrieren

Drill 3: Compose mit secrets:

Drei Änderungen gegenüber Tag 13: Top-Level-Secret notes_api_key aus der Datei, jeder Dienst bekommt es unter secrets:, und env_file entfällt, die Dienste kennen nur noch den Pfad.

cat > compose.yaml <<'EOF'
# compose.yaml – Stand Ende Tag 14
name: notes

services:
  notes-api:
    build:
      context: notes-api
      network: host            # Lab: artifact-server auf 127.0.0.1:8081 (Tag 13)
      secrets:
        - artifact_token       # Build-Secret (Tag 13)
    image: notes-api:tag14
    container_name: notes-api
    environment:
      NOTES_API_KEY_FILE: /run/secrets/notes_api_key
    secrets:
      - notes_api_key          # Tag 14: Laufzeit-Secret als Datei
    ports:
      - "127.0.0.1:8080:8080"

  notes-worker:
    build: notes-worker
    image: notes-worker:tag14
    container_name: notes-worker
    environment:
      NOTES_API_URL: http://notes-api:8080
      NOTES_API_KEY_FILE: /run/secrets/notes_api_key
    secrets:
      - notes_api_key
    depends_on:
      notes-api:
        condition: service_healthy

  notes-web:
    build:
      context: notes-web
      secrets:
        - npmrc                # Build-Secret (Tag 13)
    image: notes-web:tag14
    container_name: notes-web
    # notes-web kennt kein *_FILE: kleiner Wrapper liest die Datei beim Start
    entrypoint: ["/bin/sh", "-c"]
    command:
      - NOTES_API_KEY="$$(cat /run/secrets/notes_api_key)" exec node server.js
    environment:
      NOTES_API_URL: http://notes-api:8080
    secrets:
      - notes_api_key
    ports:
      - "127.0.0.1:3000:3000"
    depends_on:
      - notes-api

secrets:
  artifact_token:
    environment: ARTIFACT_TOKEN
  npmrc:
    file: ./secrets/npmrc
  notes_api_key:
    file: ./secrets/notes_api_key.txt
EOF
docker compose down
docker compose build --print | docker buildx bake -f - --allow network.host
docker compose up -d --no-build --wait
docker compose logs notes-api notes-worker | grep -E 'api key|worker started'

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

…
#46 naming to docker.io/library/notes-api:tag14 0.0s done
…
 Container notes-api Healthy
…
notes-api     | time=… level=INFO msg="api key loaded" source=file
notes-worker  | worker started, api=http://notes-api:8080, interval=10s

source=file: notes-api hat den Key aus der Datei. Die kurze Syntax - notes_api_key mountet ihn read-only nach /run/secrets/notes_api_key. Schreiben über notes-web und direkt gegen die API:

curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"Tag 14 über notes-web"}'; echo
curl -s -o /dev/null -w '%{http_code}\n' -X POST localhost:8080/notes \
  -H 'X-API-Key: lab-api-key-123' -d '{"text":"direkt"}'

Erwartet (gekürzt, IDs weichen ab):

{"id":"0d7e…","text":"Tag 14 über notes-web"}
201

Fortschritt speichern? Kostenlos registrieren

Drill 4: Was jetzt noch sichtbar ist

docker inspect -f '{{json .Config.Env}}' notes-api | jq -r '.[]' | grep NOTES_API
docker inspect -f '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{end}}' notes-api
docker compose config | grep -c lab-api-key-123
docker exec notes-worker cat /run/secrets/notes_api_key; echo

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

NOTES_API_KEY_FILE=/run/secrets/notes_api_key
/Users/du/docker-lab/tag14/secrets/notes_api_key.txt -> /run/secrets/notes_api_key
0
lab-api-key-123
Wo env_file (Tag 12) Secret-Datei (Tag 14)
docker inspect Wert nur Pfad
docker compose config Wert nur Pfad zur Quelldatei
docker exec … env, Kindprozesse Wert nur Pfad
docker exec … cat /run/secrets/… – Wert

Die letzte Zeile bleibt: Wer docker exec darf, liest das Secret. Zugriff auf den Docker-Socket ist Root-Zugriff auf den Host, daran ändert keine Secret-Technik etwas.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Der Wrapper für notes-web

notes-web liest nur NOTES_API_KEY. Statt den Code zu ändern, setzt ein sh -c die Variable beim Start aus der Datei. $$ verhindert, dass Compose $(…) selbst interpoliert, und exec ersetzt die Shell, damit node PID 1 bleibt und SIGTERM bekommt (Tag 2).

docker inspect -f '{{json .Config.Env}}' notes-web | jq -r '.[]' \
  | grep -c NOTES_API_KEY=
docker exec notes-web sh -c 'tr "\0" "\n" < /proc/1/environ | grep -c NOTES_API_KEY='
docker exec notes-web ps -o pid,args | head -2

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

0
1
PID   COMMAND
    1 node server.js

Docker kennt den Wert nicht mehr, der Prozess schon, in seiner eigenen Umgebung. Das ist besser als env_file, aber schwächer als echtes *_FILE: Kindprozesse von notes-web würden ihn erben. Auf Dauer gehört NOTES_API_KEY_FILE in den Code.

Fortschritt speichern? Kostenlos registrieren

Drill 6: uid, gid, mode – wann wirken sie?

Die lange Syntax erlaubt Besitzer und Rechte der Secret-Datei. Die Compose-Referenz schränkt ein: Umgesetzt sind uid, gid und mode nur, wenn die Quelle environment: ist. Bei file: nutzt Compose einen Bind-Mount und ignoriert die drei Angaben stillschweigend. Prüf es selbst mit beiden Quellen nebeneinander:

cp "$LAB/code/tag14/compose.modes.yaml" .
sed -n '/secrets:/,$p' compose.modes.yaml

Erwartet:

    secrets:
      - source: aus_datei
        uid: "65532"
        gid: "65532"
        mode: 0400
      - source: aus_env
        uid: "65532"
        gid: "65532"
        mode: 0400

secrets:
  aus_datei:
    file: ./secrets/notes_api_key.txt
  aus_env:
    environment: NOTES_API_KEY
export NOTES_API_KEY="$(cat secrets/notes_api_key.txt)"
docker compose -f compose.modes.yaml run --rm notes-modes
docker compose -f compose.modes.yaml down
unset NOTES_API_KEY

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

total 8
-rw-r--r-- 1   501    20 15 Oct 29 10:04 aus_datei
-r-------- 1 65532 65532 15 Oct 29 10:11 aus_env

aus_datei trägt Besitzer und Rechte der Datei auf deinem Mac, aus_env genau das, was in der YAML steht. Der Default ohne Angabe ist laut Referenz 0444. Unter Swarm (docker stack deploy) verwaltet Docker Secrets selbst; das behandelt dieses Buch nicht, und environment: gibt es dort laut Referenz nicht.

Achtung: environment: liest die Variable aus der Shell, in der du docker compose aufrufst. Sie landet nicht im Container, aber in deiner Shell-Umgebung. Lade sie aus einem Passwort-Manager oder Vault-CLI, nicht aus einer Datei im Projekt.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Key rotieren ohne Rebuild

Ein Key im Image hieße: neu bauen, neu pushen, neu ausrollen. Ein Secret zur Laufzeit tauschst du aus und startest die Container neu. Beide Apps lesen den Key nur beim Start, also --force-recreate; --no-build beweist, dass nichts gebaut wird:

printf '%s' 'lab-api-key-456' > secrets/notes_api_key.txt
docker compose up -d --no-build --force-recreate --wait
for k in lab-api-key-123 lab-api-key-456; do
  printf '%s → ' "$k"
  curl -s -o /dev/null -w '%{http_code}\n' -X POST localhost:8080/notes \
    -H "X-API-Key: $k" -d '{"text":"rotiert"}'
done
curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"über notes-web"}'; echo

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

[+] Running 3/3
 ✔ Container notes-api     Healthy
 ✔ Container notes-worker  Started
 ✔ Container notes-web     Started
lab-api-key-123 → 401
lab-api-key-456 → 201
{"id":"a93f…","text":"über notes-web"}

Alter Key abgelehnt, neuer akzeptiert, auch der Wrapper von notes-web hat ihn beim Neustart gelesen. Gebaut wurde nichts, die Images sind dieselben wie vorher. Die Notizen aus Drill 3 sind weg: notes-api speichert im Speicher, das Neuerstellen hat sie gelöscht.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Ausblick Kubernetes

Der *_FILE-Vertrag trägt unverändert in einen Pod. Das Secret wird zum Volume, der Container bekommt wieder nur den Pfad:

sed -n '/kind: Pod/,$p' "$LAB/code/tag14/k8s/notes-api.yaml"

Erwartet:

kind: Pod
metadata:
  name: notes-api
spec:
  securityContext:
    runAsUser: 65532
    runAsGroup: 65532
    runAsNonRoot: true
  containers:
    - name: notes-api
      image: localhost:5001/notes-api:tag14
      env:
        - name: NOTES_API_KEY_FILE
          value: /run/secrets/notes/notes_api_key
      volumeMounts:
        - name: api-key
          mountPath: /run/secrets/notes
          readOnly: true
  volumes:
    - name: api-key
      secret:
        secretName: notes-api-key
        defaultMode: 0400
Compose Kubernetes
Top-Level secrets: Objekt kind: Secret
services.*.secrets volumes.secret + volumeMounts
mode (nur environment:) defaultMode bzw. items[].mode
--force-recreate Rollout; gemountete Secrets aktualisiert das Kubelet

Die Datei liegt nur zum Lesen im Begleitcode, heute läuft kein Cluster. Das stringData im Manifest enthält einen Lab-Wert; echte Secrets schreibst du nie in YAML, die kommen aus einem Secret-Store.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Kein env_file mehr in der Compose-Datei:

cd ~/docker-lab/tag14
grep -c env_file compose.yaml

Erwartet:

0

Die Secret-Datei ist ignoriert:

git check-ignore -v secrets/notes_api_key.txt

Erwartet:

.gitignore:9:secrets/   secrets/notes_api_key.txt

notes-api liest den Key aus der Datei:

docker logs notes-api 2>&1 | grep -o 'source=[a-z]*'

Erwartet:

source=file

Der Worker hat keinen Key in der Umgebung:

docker exec notes-worker env | grep -c NOTES_API_KEY=

Erwartet:

0

docker compose config zeigt den Key-Wert nicht:

docker compose config | grep -cFf secrets/notes_api_key.txt

Erwartet:

0

notes-web schreibt mit dem Key:

curl -s -o /dev/null -w '%{http_code}\n' -X POST localhost:3000/api/notes \
  -H 'Content-Type: application/json' -d '{"text":"Kontrollpunkt"}'

Erwartet:

201

Challenge

Die Datei secrets/notes_api_key.txt ist für jeden lokalen User lesbar. Stell notes_api_key so um, dass der Key aus der Variablen NOTES_API_KEY deiner Shell kommt und im Container nur dem jeweiligen Dienst-User gehört (0400). Danach darf secrets/notes_api_key.txt nicht mehr existieren.

Hinweis: Drill 6 zeigt, welche Quelle uid, gid und mode ernst nimmt; der User node im Image node:24-alpine hat die UID 1000.

Lösung

Top-Level-Secret auf environment: umstellen und in jedem Dienst die lange Syntax verwenden, hier für notes-api:

    secrets:
      - source: notes_api_key
        uid: "65532"
        gid: "65532"
        mode: 0400
secrets:
  notes_api_key:
    environment: NOTES_API_KEY

Die vollständige Datei liegt unter ~/docker-lab/code/tag14/challenge/compose.yaml (notes-web mit uid: "1000").

cd ~/docker-lab/tag14
cp "$LAB/code/tag14/challenge/compose.yaml" compose.yaml
export NOTES_API_KEY="$(cat secrets/notes_api_key.txt)"
rm secrets/notes_api_key.txt
docker compose up -d --no-build --force-recreate --wait
docker exec notes-worker ls -ln /run/secrets
docker exec notes-web ls -ln /run/secrets
docker logs notes-api 2>&1 | grep 'api key'

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

-r-------- 1 65532 65532 15 Oct 29 10:31 notes_api_key
-r--------    1 1000     1000            15 Oct 29 10:31 notes_api_key
time=… level=INFO msg="api key loaded" source=file

Die erste Zeile kommt von Debian (python:3.13-slim), die zweite von BusyBox (node:24-alpine). notes-api hat kein ls im scratch-Image, aber source=file zeigt, dass User 65532 die Datei lesen kann. Aufräumen:

unset NOTES_API_KEY ARTIFACT_TOKEN
docker compose down
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):

notes-artifacts
Untagged: notes-api:tag14
Deleted: sha256:…
…
Total:  …

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Kubernetes-Secrets sind nur base64-kodiert. Verschlüsselung at rest für etcd und RBAC auf secrets sind Pflicht, sonst ist das Volume nur Kosmetik.
  • Die Quelle der Wahrheit ist ein Secret-Store: External Secrets Operator oder der Secrets Store CSI Driver holen Werte aus OpenBao, Vault oder dem Cloud-KMS. Wie das aufgebaut wird, zeigt „OpenBao-Secrets zum Anfassen”.
  • Rotation ohne Ausfall braucht zwei gültige Keys gleichzeitig: neuen Key zusätzlich zulassen, Clients umstellen, alten Key entfernen. notes-api kennt nur einen Key, in Produktion wäre das der erste Umbau.
  • *_FILE ist eine verbreitete Konvention, zum Beispiel in offiziellen Images wie postgres mit POSTGRES_PASSWORD_FILE. Beim Kunden gehört sie in die Anforderungen an jede eigene Anwendung.
  • Audit: Wer darf docker exec, kubectl exec oder Secrets lesen? Dieser Kreis ist der eigentliche Kreis der Mitwisser, nicht die Liste in der Secret-Policy.