Tag 10: Storage
Ziel: Du gehst bei Volume-Fehlern die Kette Pod → PVC → PV → Provisioner → Knoten ab und findest die Daten eines Volumes auf der Platte. · Dauer: ca. 75 min · Voraussetzung: Tag 6
Briefing
- Der Pod sagt nur „unbound PersistentVolumeClaims“. Die eigentliche Antwort steht am PVC (Events) und beim Provisioner (Log).
local-pathbindet erst, wenn ein Pod das PVC benutzt (WaitForFirstConsumer), und legt das Volume als Verzeichnis auf dem Knoten an, auf dem der Pod landet. Ab dann hängt jeder Pod mit diesem PVC an diesem Knoten.ReadWriteOnceheißt: ein Knoten, nicht ein Pod.emptyDirmitsizeLimitist kein Kontingent, sondern eine Räumungsgrenze.
| Fehlerbild | Symptom | Wo die Antwort steht |
|---|---|---|
| StorageClass falsch | Pod und PVC Pending |
Event am PVC |
| RWO auf zwei Knoten | zweiter Pod Pending |
PersistentVolume's node affinity |
| Rechte | Exit 1, Permission denied |
ls -ln im Volume |
| emptyDir zu klein | Pod Evicted |
.status.message |
Drill 1: Die StorageClass gibt es nicht
Einbauen:
# auf cp1
mkdir -p ~/debug/tag10 && cd ~/debug/tag10
kubectl create namespace tag10
cat > klasse.yaml <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata: {name: daten, namespace: tag10}
spec:
storageClassName: local-storage
accessModes: [ReadWriteOnce]
resources: {requests: {storage: 1Gi}}
---
apiVersion: v1
kind: Pod
metadata: {name: db, namespace: tag10}
spec:
containers:
- name: app
image: busybox:1.37
command: [sh, -c, 'date >> /daten/start.log; sleep infinity']
volumeMounts: [{name: daten, mountPath: /daten}]
volumes:
- name: daten
persistentVolumeClaim: {claimName: daten}
EOF
kubectl apply -f klasse.yamlSymptom:
# auf cp1
kubectl -n tag10 get pod db
kubectl -n tag10 events --for pod/db | tail -1Erwartet (Zeile umbrochen):
NAME READY STATUS RESTARTS AGE
db 0/1 Pending 0 8s
8s Warning FailedScheduling Pod/db 0/3 nodes are available: pod has
unbound immediate PersistentVolumeClaims. not found
Untersuchen: eine Station weiter, zum PVC:
# auf cp1
kubectl -n tag10 get pvc daten | cut -c1-80
kubectl -n tag10 describe pvc daten | sed -n '/^Events/,$p'
kubectl get storageclass | cut -c1-80Erwartet (Zeile umbrochen):
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTES
daten Pending local-storage <unset>
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning ProvisioningFailed 6s (x2 over 9s) persistentvolume-controller
storageclass.storage.k8s.io "local-storage" not found
NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUME
local-path rancher.io/local-path Delete WaitForFirstConsumer false
Ursache: Das PVC verlangt
local-storage, im Cluster heißt die Klasse
local-path. Anders als in Tag 3 ist die Klasse gesetzt,
also unveränderlich.
Fix: PVC und Pod löschen, mit richtigem Namen neu anlegen – noch sind keine Daten darin:
# auf cp1
kubectl -n tag10 delete pod db --wait=false
kubectl -n tag10 delete pvc daten
sed -i 's/local-storage/local-path/' klasse.yaml
kubectl apply -f klasse.yaml
kubectl -n tag10 wait pod/db --for=condition=ReadyNachweis:
# auf cp1
kubectl -n tag10 get pvc daten | cut -c1-88Erwartet:
NAME STATUS VOLUME CAPACITY ACCESS MODES ST
daten Bound pvc-2dcf8a8d-a00b-4484-82da-cc2f02d1af4c 1Gi RWO lo
Fortschritt speichern? Kostenlos registrieren
Drill 2: Vom PVC zum Verzeichnis auf dem Knoten
Die Events des PVC erzählen, was zwischen „Pending“ und „Bound“ passiert ist:
# auf cp1
kubectl -n tag10 events --for pvc/daten | cut -c1-88Erwartet (gekürzt):
LAST SEEN TYPE REASON OBJECT MES
9s (x3 over 26s) Warning ProvisioningFailed PersistentVolumeClaim/daten sto
8s Normal WaitForFirstConsumer PersistentVolumeClaim/daten wai
8s (x2 over 8s) Normal ExternalProvisioning PersistentVolumeClaim/daten Wai
8s Normal Provisioning PersistentVolumeClaim/daten Ext
3s Normal ProvisioningSucceeded PersistentVolumeClaim/daten Suc
Die erste Zeile stammt noch vom gelöschten PVC aus Drill 1:
events --for sucht nach Art und Name, nicht nach dem
einzelnen Objekt. WaitForFirstConsumer ist kein Fehler:
Erst wenn der Scheduler einen Knoten für den Pod gewählt hat, legt der
Provisioner das Volume an – dort. Ein PVC ohne Pod bleibt mit
local-path absichtlich Pending. Was der
Provisioner tut, steht in seinem Log:
# auf cp1
kubectl -n local-path-storage logs deploy/local-path-provisioner --since=5m \
| grep 'tag10_daten' | cut -c1-88Erwartet (gekürzt):
time="2026-11-20T08:45:09Z" level=info msg="Creating volume pvc-2dcf8a8d-a00b-4484-82da-
time="2026-11-20T08:45:14Z" level=info msg="Volume pvc-2dcf8a8d-a00b-4484-82da-cc2f02d1a
Scheitert dort etwas (Pfad nicht beschreibbar, Helper-Pod abgelehnt), steht es in genau diesen Zeilen. Jetzt das PV selbst: Pfad und Knoten.
# auf cp1
PV=$(kubectl -n tag10 get pvc daten -o jsonpath='{.spec.volumeName}')
kubectl describe pv $PV | grep -E 'Path:|Term 0'Erwartet (Zeile umbrochen):
Term 0: kubernetes.io/hostname in [worker1]
Path: /opt/local-path-provisioner/pvc-2dcf8a8d-a00b-4484-82da-cc2f02d1af4c
_tag10_daten
Und auf dem Knoten nachsehen (Knoten aus deiner Ausgabe):
# auf cp1
ssh -n worker1 "sudo cat /opt/local-path-provisioner/${PV}_tag10_daten/start.log"Erwartet:
Fri Nov 20 08:45:17 UTC 2026
Warum? Das Verzeichnis heißt
<PV>_<Namespace>_<PVC>. So findest du
Daten auch nach dem Löschen des PVC wieder – aber nur mit
reclaimPolicy: Retain. Bei local-path ist der
Standard Delete: Dann entfernt der Provisioner das
Verzeichnis zusammen mit dem PV.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Ein Volume, zwei Knoten
Einbauen: Zwei Replikas, die nicht auf demselben Knoten laufen sollen, teilen sich ein PVC:
# auf cp1
cat > rwo.yaml <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata: {name: web-daten, namespace: tag10}
spec:
storageClassName: local-path
accessModes: [ReadWriteOnce]
resources: {requests: {storage: 1Gi}}
---
apiVersion: apps/v1
kind: Deployment
metadata: {name: web, namespace: tag10}
spec:
replicas: 2
selector: {matchLabels: {app: web}}
template:
metadata: {labels: {app: web}}
spec:
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector: {matchLabels: {app: web}}
topologyKey: kubernetes.io/hostname
containers:
- name: web
image: nginxinc/nginx-unprivileged:1.29
volumeMounts: [{name: daten, mountPath: /usr/share/nginx/html}]
volumes:
- name: daten
persistentVolumeClaim: {claimName: web-daten}
EOF
kubectl apply -f rwo.yamlSymptom (nach etwa 20 Sekunden):
# auf cp1
kubectl -n tag10 get pods -l app=web -o wide | cut -c1-72Erwartet:
NAME READY STATUS RESTARTS AGE IP NODE
web-76779759cc-7lvvt 1/1 Running 0 25s 10.42.2.56 worker2
web-76779759cc-mdhg5 0/1 Pending 0 25s <none> <none>
Untersuchen:
# auf cp1
P=$(kubectl -n tag10 get pods -l app=web --field-selector=status.phase=Pending -o name)
kubectl -n tag10 events --for $P | tail -1
kubectl get pv $(kubectl -n tag10 get pvc web-daten -o jsonpath='{.spec.volumeName}') \
-o jsonpath='{.spec.nodeAffinity.required.nodeSelectorTerms[0].matchExpressions[0]}'
echoErwartet (Zeile umbrochen):
21s (x2 over 21s) Warning FailedScheduling Pod/web-76779759cc-mdhg5 0/3 nodes
are available: 1 node(s) didn't match pod anti-affinity rules, 2 node(s) didn't match
PersistentVolume's node affinity. preemption: ...
{"key":"kubernetes.io/hostname","operator":"In","values":["worker2"]}
Ursache: 1 + 2 = 3, wie in Tag 3. Das Volume liegt
auf worker2, also passt nur worker2 – dort
läuft aber schon der erste Pod, und die Anti-Affinity verbietet den
zweiten. Ein lokales Volume kann nicht mit dem Pod wandern.
Fix: Jede Replika braucht ihr eigenes Volume – das
ist ein StatefulSet mit volumeClaimTemplates:
# auf cp1
kubectl -n tag10 delete -f rwo.yaml
cat > rwo-sts.yaml <<'EOF'
apiVersion: apps/v1
kind: StatefulSet
metadata: {name: web, namespace: tag10}
spec:
replicas: 2
serviceName: web
selector: {matchLabels: {app: web}}
template:
metadata: {labels: {app: web}}
spec:
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector: {matchLabels: {app: web}}
topologyKey: kubernetes.io/hostname
containers:
- name: web
image: nginxinc/nginx-unprivileged:1.29
volumeMounts: [{name: daten, mountPath: /usr/share/nginx/html}]
volumeClaimTemplates:
- metadata: {name: daten}
spec:
storageClassName: local-path
accessModes: [ReadWriteOnce]
resources: {requests: {storage: 1Gi}}
EOF
kubectl apply -f rwo-sts.yaml
kubectl -n tag10 rollout status sts/webNachweis:
# auf cp1
kubectl -n tag10 get pods -l app=web -o wide | cut -c1-72
kubectl -n tag10 get pvc -o custom-columns=NAME:.metadata.name,STATUS:.status.phaseErwartet:
NAME READY STATUS RESTARTS AGE IP NODE
web-0 1/1 Running 0 16s 10.42.0.66 cp1
web-1 1/1 Running 0 8s 10.42.2.59 worker2
NAME STATUS
daten Bound
daten-web-0 Bound
daten-web-1 Bound
Warum die Anti-Affinity? Ohne sie hätte der Scheduler beide Pods auf
worker2 gesetzt, und beide hätten das Volume gemeinsam
beschrieben: ReadWriteOnce erlaubt einen
Knoten, beliebig viele Pods darauf. Nur
ReadWriteOncePod beschränkt auf einen Pod.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Permission denied
Einbauen: Ein Init-Container legt als root ein Unterverzeichnis an, die Anwendung läuft als Benutzer 1000:
# auf cp1
cat > rechte.yaml <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata: {name: notizen, namespace: tag10}
spec:
storageClassName: local-path
accessModes: [ReadWriteOnce]
resources: {requests: {storage: 1Gi}}
---
apiVersion: apps/v1
kind: Deployment
metadata: {name: notizen, namespace: tag10}
spec:
replicas: 1
selector: {matchLabels: {app: notizen}}
template:
metadata: {labels: {app: notizen}}
spec:
initContainers:
- name: vorbereiten
image: busybox:1.37
command: [sh, -c, 'mkdir -p /data/notizen']
volumeMounts: [{name: daten, mountPath: /data}]
containers:
- name: app
image: busybox:1.37
command: [sh, -c, 'date >> /data/notizen/log.txt && sleep infinity']
securityContext: {runAsUser: 1000, runAsGroup: 1000}
volumeMounts: [{name: daten, mountPath: /data}]
volumes:
- name: daten
persistentVolumeClaim: {claimName: notizen}
EOF
kubectl apply -f rechte.yamlSymptom (nach etwa 30 Sekunden):
# auf cp1
kubectl -n tag10 get pods -l app=notizen
kubectl -n tag10 logs deploy/notizenErwartet:
NAME READY STATUS RESTARTS AGE
notizen-76c48fc666-zl5xz 0/1 Error 2 (20s ago) 30s
Defaulted container "app" out of: app, vorbereiten (init)
sh: can't create /data/notizen/log.txt: Permission denied
Untersuchen: Der Container stürzt sofort ab,
exec geht nicht. Eine Kopie des Pods mit anderem Befehl
(Tag 6) zeigt Benutzer und Rechte:
# auf cp1
P=$(kubectl -n tag10 get pod -l app=notizen -o jsonpath='{.items[0].metadata.name}')
kubectl -n tag10 debug $P --copy-to=notizen-dbg --container=app \
-- sh -c 'id; ls -ldn /data /data/notizen; sleep 3600'
sleep 8
kubectl -n tag10 logs notizen-dbg -c app
kubectl -n tag10 delete pod notizen-dbg --wait=falseErwartet:
uid=1000 gid=1000 groups=1000
drwxrwxrwx 3 0 0 4096 Nov 20 08:42 /data
drwxr-xr-x 2 0 0 4096 Nov 20 08:42 /data/notizen
pod "notizen-dbg" deleted from tag10 namespace
Ursache: Das Volume selbst ist offen
(local-path legt es mit 0777 an), das
Unterverzeichnis gehört aber root mit 755. Benutzer 1000
darf darin nichts anlegen.
Der Reflex wäre fsGroup. Probier es:
# auf cp1
kubectl -n tag10 patch deploy notizen --type=merge \
-p '{"spec":{"template":{"spec":{"securityContext":{"fsGroup":1000}}}}}'
sleep 25
kubectl -n tag10 logs deploy/notizen -c app | tail -1Erwartet:
deployment.apps/notizen patched
sh: can't create /data/notizen/log.txt: Permission denied
fsGroup wirkt nur bei Volume-Typen, deren Besitz das
kubelet verwaltet (etwa emptyDir, viele CSI-Treiber).
local-path liefert hostPath-Volumes – dort
ändert das kubelet nichts.
Fix: Der Init-Container übergibt das Verzeichnis:
# auf cp1
kubectl -n tag10 patch deploy notizen --type=json -p '[{"op": "replace",
"path": "/spec/template/spec/initContainers/0/command/2",
"value": "mkdir -p /data/notizen && chown 1000:1000 /data/notizen"}]'
kubectl -n tag10 rollout status deploy/notizenNachweis:
# auf cp1
kubectl -n tag10 exec deploy/notizen -c app -- sh -c \
'ls -ldn /data/notizen; cat /data/notizen/log.txt'Erwartet:
drwxr-xr-x 2 1000 1000 4096 Nov 20 08:43 /data/notizen
Fri Nov 20 08:43:50 UTC 2026
Fortschritt speichern? Kostenlos registrieren
Drill 5: emptyDir läuft über
Einbauen:
# auf cp1
cat > cache.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata: {name: export, namespace: tag10}
spec:
replicas: 1
selector: {matchLabels: {app: export}}
template:
metadata: {labels: {app: export}}
spec:
containers:
- name: export
image: busybox:1.37
command: [sh, -c, 'dd if=/dev/zero of=/cache/export.tmp bs=1M count=80;
sleep infinity']
volumeMounts: [{name: cache, mountPath: /cache}]
volumes:
- name: cache
emptyDir: {sizeLimit: 50Mi}
EOF
kubectl apply -f cache.yamlSymptom: Gut eine halbe Minute läuft der Pod, dann:
# auf cp1
sleep 45
kubectl -n tag10 get pods -l app=exportErwartet:
NAME READY STATUS RESTARTS AGE
export-57d669d6f4-bd9bv 1/1 Running 0 3s
export-57d669d6f4-kvbdh 0/1 ContainerStatusUnknown 1 42s
Untersuchen:
# auf cp1
kubectl -n tag10 get pods -l app=export -o custom-columns=NAME:.metadata.name,\
PHASE:.status.phase,REASON:.status.reason,MSG:.status.messageErwartet (Zeile umbrochen):
NAME PHASE REASON MSG
export-57d669d6f4-bd9bv Running <none> <none>
export-57d669d6f4-kvbdh Failed Evicted Usage of EmptyDir volume "cache" exceeds
the limit "50Mi".
Ursache: Das kubelet misst die Belegung von
emptyDir regelmäßig. Überschreitet sie
sizeLimit, räumt es den ganzen Pod
(Evicted), statt nur den Schreibvorgang abzulehnen. Der
ReplicaSet-Controller ersetzt ihn – und der Nachfolger schreibt
dieselben 80 MiB. Der Status ContainerStatusUnknown ist
irreführend; die Wahrheit steht in .status.reason und
.status.message.
Fix:
# auf cp1
kubectl -n tag10 patch deploy export --type=json -p '[{"op": "replace",
"path": "/spec/template/spec/volumes/0/emptyDir/sizeLimit", "value": "128Mi"}]'
kubectl -n tag10 rollout status deploy/export
kubectl -n tag10 delete pods --field-selector=status.phase=FailedNachweis (nach einer Minute):
# auf cp1
kubectl -n tag10 get pods -l app=export
kubectl -n tag10 exec deploy/export -- du -sh /cacheErwartet:
NAME READY STATUS RESTARTS AGE
export-54fcf64cd9-nc5hn 1/1 Running 0 48s
80.0M /cache
Warum löschen? Geräumte Pods bleiben als Failed stehen,
bis jemand sie entfernt oder die Garbage Collection zuschlägt (RKE2: ab
1000 beendeten Pods, Kubernetes-Standard 12 500).
Fortschritt speichern? Kostenlos registrieren
Übung: Speed-Drills
- Zeig alle PVCs im Cluster, die nicht
Boundsind. Zeitziel: 15 s - Zeig, auf welchem Knoten das Volume von
daten-web-1liegt. Zeitziel: 30 s - Zeig die letzten drei Zeilen des Provisioner-Logs. Zeitziel: 15 s
- Zeig alle
Failed-Pods im Cluster. Zeitziel: 15 s
Lösung
# auf cp1
kubectl get pvc -A --no-headers | grep -v Bound
PV=$(kubectl -n tag10 get pvc daten-web-1 -o jsonpath='{.spec.volumeName}')
kubectl describe pv $PV | grep 'Term 0'
kubectl -n local-path-storage logs deploy/local-path-provisioner --tail=3 | cut -c1-88
kubectl get pods -A --field-selector=status.phase=FailedErwartet (gekürzt):
Term 0: kubernetes.io/hostname in [worker2]
time="2026-11-20T08:53:29Z" level=info msg="Start of helper-pod-create-pvc-1c9249c8-7993
time="2026-11-20T08:53:29Z" level=info msg="End of helper-pod-create-pvc-1c9249c8-7993-4
I1120 08:53:29.985671 1 event.go:389] "Event occurred" object="tag10/notizen" fiel
No resources found
grep -v Bound gibt nichts aus – alle PVCs sind
gebunden.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
# auf cp1
kubectl -n tag10 get podsErwartet:
NAME READY STATUS RESTARTS AGE
db 1/1 Running 0 5m
export-54fcf64cd9-nc5hn 1/1 Running 0 2m
notizen-fbffff858-m894d 1/1 Running 0 4m
web-0 1/1 Running 0 5m
web-1 1/1 Running 0 5m
Challenge
Ein Kollege will db „auf einen ruhigeren Knoten“
umziehen und legt den Pod mit nodeSelector auf
worker2 neu an. Er bleibt Pending. Finde die
Ursache und bring db mit seinen Daten wieder zum
Laufen.
# auf cp1
kubectl -n tag10 delete pod db
cat > umzug.yaml <<'EOF'
apiVersion: v1
kind: Pod
metadata: {name: db, namespace: tag10}
spec:
nodeSelector: {kubernetes.io/hostname: worker2}
containers:
- name: app
image: busybox:1.37
command: [sh, -c, 'date >> /daten/start.log; sleep infinity']
volumeMounts: [{name: daten, mountPath: /daten}]
volumes:
- name: daten
persistentVolumeClaim: {claimName: daten}
EOF
kubectl apply -f umzug.yamlHinweis: Wo liegt das Volume von
daten?
Lösung
# auf cp1
kubectl -n tag10 events --for pod/db | tail -1
kubectl get pv $(kubectl -n tag10 get pvc daten -o jsonpath='{.spec.volumeName}') \
-o jsonpath='{.spec.nodeAffinity.required.nodeSelectorTerms[0].matchExpressions[0]}'
echoErwartet (Zeile umbrochen):
6s Warning FailedScheduling Pod/db 0/3 nodes are available: 1 node(s)
didn't match PersistentVolume's node affinity, 2 node(s) didn't match Pod's node
affinity/selector. preemption: ...
{"key":"kubernetes.io/hostname","operator":"In","values":["worker1"]}
Das Volume liegt auf worker1, der Pod soll auf
worker2 – mit local-path geht das nicht. Der
Pod muss zurück; ein echter Umzug hieße Daten kopieren und ein neues PVC
anlegen.
# auf cp1
kubectl -n tag10 delete pod db
kubectl apply -f klasse.yaml
kubectl -n tag10 wait pod/db --for=condition=Ready
kubectl -n tag10 exec db -- cat /daten/start.logErwartet:
pod "db" deleted from tag10 namespace
persistentvolumeclaim/daten unchanged
pod/db created
pod/db condition met
Fri Nov 20 08:45:17 UTC 2026
Fri Nov 20 08:52:31 UTC 2026
Zwei Zeilen: Die Daten vom ersten Start sind noch da.
Fortschritt speichern? Kostenlos registrieren
Aufräumen
# auf cp1
kubectl delete namespace tag10
sleep 15
kubectl get pvErwartet:
namespace "tag10" deleted
No resources found
reclaimPolicy: Delete: Mit den PVCs verschwinden PVs und
Verzeichnisse auf den Knoten. Direkt nach dem Löschen stehen die PVs
noch einige Sekunden als Released da, bis der Helper-Pod
des Provisioners die Verzeichnisse entfernt hat.
Interview-Notiz
- Pod
Pendingwegen PVC – wo schaust du? Events am PVC, dann StorageClass und Provisioner-Log; bei lokalen Volumes dienodeAffinitydes PV. - Was heißt ReadWriteOnce? Ein Knoten darf schreibend
mounten, nicht ein Pod; für „genau ein Pod“ gibt es
ReadWriteOncePod. - Permission denied trotz
fsGroup?fsGroupgreift nicht bei jedem Volume-Typ (z. B.hostPath); dann per Init-Container oder Image-Benutzer lösen.
Enterprise-Notiz
local-pathist für Labore und Caches gedacht. Produktiv ein CSI-Treiber mit Replikation (Longhorn, Ceph, Cloud-Disks), damit Pods mit ihren Daten den Knoten wechseln können.reclaimPolicy: Retainfür Datenbank-Klassen, sonst löscht ein versehentlicheskubectl delete pvcdie Daten.- Alarme auf
kubelet_volume_stats_available_bytesund auf geräumte Pods;emptyDir-Grenzen bewusst setzen und dokumentieren. - Für Datenbanken ein Operator (z. B. CloudNativePG) statt eines selbst gebauten StatefulSets.