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 storageclassErwartet (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: 1Gipg_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/18Erwartet (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; doneErwartet (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-urlkubectl 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 statusfertig 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/notesErwartet (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 -1Erwartet (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-0löscht die Daten wirklich: Die Reclaim-Policy der StorageClass istDelete, local-path entfernt dann das Verzeichnis auf dem Node.kubectl delete namespace notesnimmt 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.sqlErwartet (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 probeErwartet:
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,svcErwartet: 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-0Erwartet: db-0 läuft und ist bereit.
NAME READY STATUS RESTARTS AGE
db-0 1/1 Running 0 53s
kubectl logs deploy/api | grep storeErwartet: 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/notesErwartet: 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.sqlErwartet: 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_dumpist 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 versehentlichesdelete pvc. - Migrationen brauchen bei mehreren Instanzen eine Sperre und laufen in der Pipeline oder als Helm-Hook (Tag 10).