Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 7: Postgres als StatefulSet

Ziel: Postgres läuft als StatefulSet mit eigenem Volume, eine Migration legt die Tabelle an, alle api-Repliken sehen dieselben Notizen, und ein Backup liegt auf deinem Mac. · Dauer: ca. 90 min · Voraussetzung: Tag 6

Briefing

  • Ein StatefulSet gibt jedem Pod einen festen Namen (db-0), einen festen DNS-Namen und ein eigenes Volume, das beim Neustart wieder an denselben Pod geht.
  • Den DNS-Namen liefert ein headless Service (clusterIP: None): Er zeigt direkt auf die Pod-IPs, ohne virtuelle IP davor.
  • Das Volume beantragt ein PersistentVolumeClaim (PVC). Die StorageClass standard (in kind: local-path) erzeugt dazu ein PersistentVolume (PV) auf dem Node.
  • Die Tabelle legt ein Job an: ein Pod, der einmal erfolgreich enden soll.
 api ×3 ──db:5432──► Service db (headless) ──► db-0 ──► PVC data-db-0 ──► PV
                                               ▲          (StorageClass standard)
 Job migrate ──────────────────────────────────┘

Drill 1: Der Speicher-Cliffhanger

Tagesstart:

source ~/k8s-lab/setup/env.sh
mkdir -p ~/k8s-lab/tag07 && cd ~/k8s-lab/tag07
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag06/notes/." .

Erinnerung an Tag 3 – drei Notizen schreiben, sechsmal lesen:

for t in eins zwei drei; do
  curl -s -X POST localhost:30080/api/notes -H 'Content-Type: application/json' \
    -d "{\"text\":\"Notiz $t\"}" >/dev/null
done
for i in 1 2 3 4 5 6; do curl -s localhost:30080/api/notes | jq -c '[.[].text]'; done
kubectl get storageclass

Erwartet (gekürzt, Namen, IPs und Zeiten weichen bei dir ab):

["Notiz eins"]
["Notiz eins"]
["Notiz zwei","Notiz drei"]
["Notiz eins"]
["Notiz zwei","Notiz drei"]
["Notiz zwei","Notiz drei"]
NAME                 PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      …
standard (default)   rancher.io/local-path   Delete          WaitForFirstConsumer   …

Jede api-Replik hat ihre eigene Liste im Speicher. Die Lösung ist eine gemeinsame Datenbank. kind bringt die StorageClass standard mit; WaitForFirstConsumer heißt: Das Volume entsteht erst, wenn ein Pod es braucht – auf dessen Node.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Secret und StatefulSet

secrets.sh legt zusätzlich das Secret notes-db an – Passwort für Postgres und die fertige URL für api:

cat > k8s/secrets.sh <<'EOF'
#!/usr/bin/env bash
# k8s/secrets.sh – Stand Ende Tag 7: legt die Secrets an (idempotent, nur Lab-Werte)
set -euo pipefail
kubectl -n notes create secret generic notes-api \
  --from-literal=api-key="${NOTES_API_KEY:-lab-api-key-123}" \
  --dry-run=client -o yaml | kubectl apply -f -
pw="${POSTGRES_PASSWORD:-lab-db-pw-123}"
kubectl -n notes create secret generic notes-db \
  --from-literal=password="$pw" \
  --from-literal=db-url="postgres://notes:$pw@db:5432/notes" \
  --dry-run=client -o yaml | kubectl apply -f -
EOF
bash -n k8s/secrets.sh && ./k8s/secrets.sh
kubectl get secret notes-db -o json | jq -r '.data | keys[]'

Erwartet:

secret/notes-api unchanged
secret/notes-db created
db-url
password

Die vollständige k8s/db.yaml (headless Service plus StatefulSet) liegt im Begleitcode. Das Wesentliche:

# k8s/db.yaml (Ausschnitt) – Stand Ende Tag 7
spec:
  clusterIP: None              # Service db: headless
---
kind: StatefulSet
spec:
  serviceName: db              # liefert die DNS-Namen db-0.db, db-1.db, …
  replicas: 1
  template:
    spec:
      containers:
        - name: postgres
          image: postgres:18.6-alpine
          env:
            - name: POSTGRES_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: notes-db
                  key: password
          # … POSTGRES_USER/DB notes, resources 100m/128Mi/256Mi …
          readinessProbe:
            exec:
              command: [pg_isready, -h, 127.0.0.1, -U, notes, -d, notes]
            periodSeconds: 5
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql
  volumeClaimTemplates:        # pro Pod ein PVC: data-db-0
    - metadata:
        name: data
      spec:
        accessModes: [ReadWriteOnce]
        resources:
          requests:
            storage: 1Gi

pg_isready mit -h 127.0.0.1 prüft TCP, nicht den Unix-Socket – der temporäre Init-Server von Postgres lauscht nur auf dem Socket und meldet sonst zu früh „bereit”.

cp "$LAB/code/tag07/notes/k8s/"{db,migrate,api}.yaml k8s/
kubectl apply --dry-run=server -f k8s/db.yaml
kubectl apply -f k8s/db.yaml
sleep 3; kubectl get pvc,pod -l app.kubernetes.io/name=db
kubectl rollout status statefulset/db --timeout 180s
c='PVC:.metadata.name,STATUS:.status.phase,PV:.spec.volumeName'
kubectl get pvc -o custom-columns="$c,SIZE:.status.capacity.storage"

Erwartet (gekürzt):

service/db created (server dry run)
statefulset.apps/db created (server dry run)
service/db created
statefulset.apps/db created
NAME                              STATUS    VOLUME   CAPACITY   ACCESS MODES   …
persistentvolumeclaim/data-db-0   Pending                                      …
NAME       READY   STATUS    RESTARTS   AGE
pod/db-0   0/1     Pending   0          3s
Waiting for 1 pods to be ready...
partitioned roll out complete: 1 new pods have been updated...
PVC         STATUS   PV                                         SIZE
data-db-0   Bound    pvc-1a10d53e-4c96-4c72-a1ea-e83ed0335344   1Gi

Das StatefulSet hat aus der Vorlage data den PVC data-db-0 gemacht. Erst als der Scheduler db-0 einen Node zugeteilt hatte, legte local-path dort das PV an. Wo genau und was liegt darin?

pv=$(kubectl get pvc data-db-0 -o jsonpath='{.spec.volumeName}')
c='RECLAIM:.spec.persistentVolumeReclaimPolicy,PATH:.spec.hostPath.path'
kubectl get pv "$pv" -o custom-columns="$c"
kubectl get pod db-0 -o jsonpath='{.spec.nodeName}'; echo
kubectl exec db-0 -- ls /var/lib/postgresql /var/lib/postgresql/18

Erwartet (gekürzt):

RECLAIM   PATH
Delete    /var/local-path-provisioner/pvc-1a10d53e-…_notes_data-db-0
lab-worker
/var/lib/postgresql:
18

/var/lib/postgresql/18:
docker

Postgres 18 legt seine Daten in ein Unterverzeichnis mit der Hauptversion (/var/lib/postgresql/18/docker). Darum hängt das Volume eine Ebene höher, auf /var/lib/postgresql – so liegen bei einem späteren Major-Upgrade alte und neue Version auf demselben Volume. Die Daten liegen in einem Verzeichnis auf dem Node lab-worker; zieht der Pod um, findet er sie nur dort (ReadWriteOnce, local-path bindet das PV per Node-Affinität).

Fortschritt speichern? Kostenlos registrieren

Drill 3: Headless Service und stabile Namen

kubectl get svc db
kubectl get endpointslice -l kubernetes.io/service-name=db \
  -o custom-columns='ADDR:.endpoints[*].addresses[0],HOSTNAME:.endpoints[*].hostname'
for n in api db db-0.db; do kubectl exec deploy/web -- getent hosts $n; done

Erwartet (gekürzt):

NAME   TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)    AGE
db     ClusterIP   None         <none>        5432/TCP   54s
ADDR          HOSTNAME
10.244.2.61   db-0
10.96.246.140     api.notes.svc.cluster.local  api.notes.svc.cluster.local api
10.244.2.61       db.notes.svc.cluster.local  db.notes.svc.cluster.local db
10.244.2.61       db-0.db.notes.svc.cluster.local  db-0.db.notes.svc.cluster.local …

api löst auf eine virtuelle Service-IP (10.96.…) auf, kube-proxy verteilt dahinter. db und db-0.db lösen direkt auf die Pod-IP auf. Mit mehreren Repliken lieferte db alle Pod-IPs, db-0.db immer genau die von db-0 – so adressieren Datenbank-Cluster ihren Primary. Die IP wechselt bei jedem neuen Pod, der Name bleibt.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Migration als Job

migrate.yaml startet notes-api mit dem Argument migrate. Das Wichtigste:

# k8s/migrate.yaml (Ausschnitt) – Stand Ende Tag 7
kind: Job
spec:
  backoffLimit: 4                # höchstens 4 Wiederholungen
  ttlSecondsAfterFinished: 600   # 10 min nach dem Ende räumt Kubernetes auf
  template:
    spec:
      restartPolicy: OnFailure
      containers:
        - name: migrate
          image: notes-api:0.2.0
          args: [migrate]
          env:
            - name: NOTES_DB_URL_FILE
              value: /etc/notes/db-url
          # … resources, volumeMounts: Secret notes-db, nur der Schlüssel db-url …
kubectl apply --dry-run=server -f k8s/migrate.yaml
kubectl apply -f k8s/migrate.yaml
kubectl wait --for=condition=Complete job/migrate --timeout 120s
kubectl get job migrate
kubectl logs job/migrate
kubectl exec db-0 -- psql -U notes -d notes -c '\d notes'

Erwartet (gekürzt):

job.batch/migrate created (server dry run)
job.batch/migrate created
job.batch/migrate condition met
NAME      STATUS     COMPLETIONS   DURATION   AGE
migrate   Complete   1/1           6s         7s
time=… level=INFO msg="migration complete" table=notes
                          Table "public.notes"
   Column   |           Type           | Collation | Nullable | Default
------------+--------------------------+-----------+----------+---------
 id         | uuid                     |           | not null |
 text       | text                     |           | not null |
 created_at | timestamp with time zone |           | not null | now()

restartPolicy: OnFailure startet den Container bei Exit ungleich 0 neu, backoffLimit begrenzt das. Ein Deployment ginge hier nicht: Es würde den beendeten Container immer wieder starten.

Fortschritt speichern? Kostenlos registrieren

Drill 5: api auf Postgres umstellen

api bekommt zum Key die DB-URL – beide als Dateien aus einem projected-Volume, das mehrere Secrets in ein Verzeichnis legt:

# k8s/api.yaml (Ausschnitt) – Stand Ende Tag 7
          env:
            - name: NOTES_API_KEY_FILE
              value: /etc/notes/api-key
            - name: NOTES_DB_URL_FILE
              value: /etc/notes/db-url
      # …
      volumes:
        - name: secrets
          projected:
            sources:
              - secret:
                  name: notes-api
                  items:
                    - key: api-key
                      path: api-key
              - secret:
                  name: notes-db
                  items:
                    - key: db-url
                      path: db-url
kubectl apply -f k8s/ | grep -v unchanged
kubectl rollout status deploy/api >/dev/null
for t in eins zwei drei; do
  curl -s -X POST localhost:30080/api/notes -H 'Content-Type: application/json' \
    -d "{\"text\":\"Postgres $t\"}" >/dev/null
done
for i in 1 2 3 4 5 6; do curl -s localhost:30080/api/notes | jq -c '[.[].text]'; done
kubectl logs deploy/api | grep 'store ready'

Erwartet (gekürzt):

deployment.apps/api configured
statefulset.apps/db configured
["Postgres eins","Postgres zwei","Postgres drei"]
["Postgres eins","Postgres zwei","Postgres drei"]
["Postgres eins","Postgres zwei","Postgres drei"]
["Postgres eins","Postgres zwei","Postgres drei"]
["Postgres eins","Postgres zwei","Postgres drei"]
["Postgres eins","Postgres zwei","Postgres drei"]
Found 3 pods, using pod/api-b8f9cb55-5pr7w
time=… level=INFO msg="store ready" store=postgres

Sechsmal dieselbe Liste – der Cliffhanger von Tag 3 ist aufgelöst. Die Notizen aus Drill 1 sind weg, sie lebten nur im Speicher der alten Pods. statefulset.apps/db configured meldet kubectl apply bei jedem Lauf, ohne dass sich etwas ändert (die generation bleibt 1, db-0 startet nicht neu) – harmlos.

Achtung: Schreib erst, wenn rollout status fertig ist. Während des Rollouts bedienen die alten Speicher-Pods (preStop plus Grace Period) bestehende Keep-Alive-Verbindungen von web weiter. Eine Notiz, die dort landet, ist mit dem Pod weg.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Datenbank weg

Was passiert, wenn Postgres fehlt? Fahr db herunter:

kubectl scale statefulset db --replicas 0
kubectl wait --for=delete pod/db-0 --timeout 60s; sleep 20
kubectl get pods -l app.kubernetes.io/name=api
curl -s -o /dev/null -w '%{http_code}\n' localhost:30080/api/notes

Erwartet (gekürzt):

statefulset.apps/db scaled
pod/db-0 condition met
NAME                 READY   STATUS    RESTARTS   AGE
api-b8f9cb55-5pr7w   0/1     Running   0          84s
api-b8f9cb55-gkmrs   0/1     Running   0          80s
api-b8f9cb55-rd7w2   0/1     Running   0          77s
500

Die Readiness auf /healthz nimmt alle api-Pods aus dem Verkehr, web antwortet mit 500. Aber RESTARTS 0: Die Liveness auf /version lässt die gesunden Prozesse in Ruhe – der Beweis aus Tag 5. Und ein neuer api-Pod?

kubectl rollout restart deploy/api; sleep 40
kubectl get pods -l app.kubernetes.io/name=api
p=$(kubectl get pod -l app.kubernetes.io/name=api \
  --sort-by=.metadata.creationTimestamp -o name | tail -1)
kubectl logs "$p" --previous | tail -1

Erwartet (gekürzt):

deployment.apps/api restarted
NAME                   READY   STATUS             RESTARTS      AGE
api-79bc846579-282pv   0/1     CrashLoopBackOff   2 (25s ago)   41s
api-b8f9cb55-5pr7w     0/1     Running            0             2m6s
…
time=… level=ERROR msg="database unreachable" source=file err="failed to connect to
`user=notes database=notes`:\n\thostname resolving error: lookup db on 10.96.0.10:53:
server misbehaving…"

Ohne erreichbare Datenbank endet notes-api beim Start mit Exit 1, Kubernetes startet sie neu, RESTARTS zählt hoch – bis db wieder da ist. Das ist das Gegenstück zu depends_on aus Compose: keine Startreihenfolge, sondern Wiederholen, bis es klappt. Ohne Pod liefert der headless Service übrigens keine Adresse – daher der DNS-Fehler.

kubectl scale statefulset db --replicas 1
kubectl rollout status statefulset/db >/dev/null
kubectl rollout status deploy/api --timeout 180s >/dev/null
kubectl get pods -l app.kubernetes.io/name=api
curl -s localhost:30080/api/notes | jq -c '[.[].text]'

Erwartet (gekürzt):

statefulset.apps/db scaled
NAME                   READY   STATUS        RESTARTS      AGE
api-79bc846579-282pv   1/1     Running       4 (56s ago)   97s
api-79bc846579-8lqsb   1/1     Running       0             5s
api-79bc846579-m6659   1/1     Running       0             2s
…
["Postgres eins","Postgres zwei","Postgres drei"]

Der erste neue Pod brauchte vier Neustarts. Die übrigen kamen erst, als er bereit war – maxUnavailable: 0 hielt die alten so lange im Spiel.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Daten überleben

c='NAME:.metadata.name,UID:.metadata.uid,IP:.status.podIP'
kubectl get pod db-0 -o custom-columns="$c"
kubectl delete pod db-0
kubectl wait --for=condition=Ready pod/db-0 --timeout 120s
kubectl get pod db-0 -o custom-columns="$c"
sleep 3; curl -s localhost:30080/api/notes | jq -c '[.[].text]'

Erwartet (gekürzt):

NAME   UID                                    IP
db-0   2bf2ab00-74a1-407f-984d-87ac73817ff1   10.244.2.61
pod "db-0" deleted from notes namespace
pod/db-0 condition met
NAME   UID                                    IP
db-0   b4262687-7331-49b0-a0b9-ebbba3459cfb   10.244.2.65
["Postgres eins","Postgres zwei","Postgres drei"]

Neuer Pod, neue UID, neue IP – aber derselbe Name und derselbe PVC. Selbst das StatefulSet darfst du löschen:

kubectl get sts db -o jsonpath='{.spec.persistentVolumeClaimRetentionPolicy}'; echo
kubectl delete statefulset db
kubectl wait --for=delete pod/db-0 --timeout 60s
kubectl get pvc -o custom-columns='PVC:.metadata.name,STATUS:.status.phase'
kubectl apply -f k8s/db.yaml && kubectl rollout status statefulset/db >/dev/null
kubectl exec db-0 -- psql -U notes -d notes -tAc 'SELECT count(*) FROM notes'

Erwartet (gekürzt):

{"whenDeleted":"Retain","whenScaled":"Retain"}
statefulset.apps "db" deleted from notes namespace
pod/db-0 condition met
PVC         STATUS
data-db-0   Bound
service/db unchanged
statefulset.apps/db created
3

PVCs aus volumeClaimTemplates bleiben standardmäßig stehen. Auf genau diesem Verhalten baut der Umstieg auf Helm an Tag 10 auf.

Achtung: kubectl delete pvc data-db-0 löscht die Daten wirklich: Die Reclaim-Policy der StorageClass ist Delete, local-path entfernt dann das Verzeichnis auf dem Node. kubectl delete namespace notes nimmt die PVCs mit.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Backup und Restore-Probe

pg_dump läuft im Pod, die Ausgabe landet über kubectl exec auf deinem Mac:

kubectl exec db-0 -- pg_dump -U notes -d notes --clean --if-exists > backup.sql
ls -l backup.sql | awk '{print $5, $9}'
grep -E '^(DROP|CREATE|COPY)' backup.sql

Erwartet (gekürzt):

1644 backup.sql
DROP TABLE IF EXISTS public.notes;
CREATE TABLE public.notes (
COPY public.notes (id, text, created_at) FROM stdin;

--clean --if-exists stellt jeder Tabelle ein DROP … IF EXISTS voran – damit lässt sich das Backup auch über einen bestehenden Stand einspielen. Ein Backup, das nie zurückgespielt wurde, ist eine Hoffnung. Also die Probe in einer Wegwerf-Datenbank:

kubectl exec db-0 -- createdb -U notes probe
kubectl exec -i db-0 -- psql -q -v ON_ERROR_STOP=1 -U notes -d probe \
  < backup.sql >/dev/null
kubectl exec db-0 -- psql -U notes -d probe -tAc \
  'SELECT text FROM notes ORDER BY created_at'
kubectl exec db-0 -- dropdb -U notes probe

Erwartet:

Postgres eins
Postgres zwei
Postgres drei

-i reicht deine Standardeingabe in den Container durch – ohne -i bekäme psql nichts von backup.sql zu sehen. Ohne Passwort klappt das, weil das Postgres-Image Verbindungen über den lokalen Unix-Socket im Container vertraut.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

kubectl get pvc,svc

Erwartet: PVC data-db-0 ist Bound, der Service db hat keine Cluster-IP (None, headless).

NAME                              STATUS   VOLUME                     CAPACITY   …
persistentvolumeclaim/data-db-0   Bound    pvc-2d13ae07-f529-4fb3-…   1Gi        …

NAME          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
service/api   ClusterIP   10.96.142.49    <none>        8080/TCP         3m33s
service/db    ClusterIP   None            <none>        5432/TCP         54s
service/web   NodePort    10.96.180.246   <none>        3000:30080/TCP   3m33s
kubectl get pod db-0

Erwartet: db-0 läuft und ist bereit.

NAME   READY   STATUS    RESTARTS   AGE
db-0   1/1     Running   0          53s
kubectl logs deploy/api | grep store

Erwartet: store=postgres.

Found 3 pods, using pod/api-f9c7bb64f-s4rdx
time=… level=INFO msg="store ready" store=postgres
curl -s localhost:30080/api/notes
curl -s localhost:30080/api/notes

Erwartet: zweimal dieselbe Liste, egal welche Replik antwortet (Inhalt weicht ab).

[{"id":"c74b85b6-…","text":"bleibt in Postgres"}]
[{"id":"c74b85b6-…","text":"bleibt in Postgres"}]
grep COPY ~/k8s-lab/tag07/backup.sql

Erwartet: Das Backup aus Drill 7 enthält die Tabelle notes.

COPY public.notes (id, text, created_at) FROM stdin;

Challenge

Jemand hat versehentlich alle Notizen gelöscht. Stell sie aus backup.sql wieder her, ohne db oder api neu zu starten.

Hinweis: Das Backup enthält schon ein DROP TABLE IF EXISTS – du kannst es direkt in die Datenbank notes einspielen.

Lösung

Den Unfall nachstellen und reparieren:

kubectl exec db-0 -- psql -U notes -d notes -c 'DELETE FROM notes'
curl -s localhost:30080/api/notes; echo
kubectl exec -i db-0 -- psql -q -v ON_ERROR_STOP=1 -U notes -d notes \
  < backup.sql >/dev/null; echo "Exit: $?"
curl -s localhost:30080/api/notes | jq -c '[.[].text]'

Erwartet:

DELETE 3
[]

Exit: 0
["Postgres eins","Postgres zwei","Postgres drei"]

api merkt vom Austausch der Tabelle nichts: Sie fragt bei jedem Request neu, und database/sql baut abgebrochene Verbindungen selbst neu auf.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Datenbanken in Kubernetes betreibt man mit einem Operator (CloudNativePG, Zalando Postgres Operator): Replikation, Failover, Point-in-Time-Recovery, Upgrades („Kubernetes-Operatoren zum Anfassen”). Oder man nutzt eine verwaltete Datenbank außerhalb des Clusters.
  • local-path ist nur fürs Lab: Die Daten hängen an einem Node. In Produktion liefert ein CSI-Treiber Netz- oder verteilten Speicher (Ceph/Rook, Longhorn, Cloud-Disks) mit Snapshots über VolumeSnapshot.
  • pg_dump ist ein logisches Backup und für kleine Datenbanken gut. Für große: WAL-Archivierung mit pgBackRest oder Barman, regelmäßig getestete Restores.
  • Für produktive Daten StorageClasses mit reclaimPolicy: Retain – dann überlebt das PV auch ein versehentliches delete pvc.
  • Migrationen brauchen bei mehreren Instanzen eine Sperre und laufen in der Pipeline oder als Helm-Hook (Tag 10).