Kubernetes PVC Pending lösen: StorageClass und Provisioner debuggen

TL;DR

PVC bleibt Pending? Prüfen Sie in dieser Reihenfolge: Existiert die StorageClass? Läuft der Provisioner-Pod? Ist die Quota erreicht? In 90% der Fälle fehlt die StorageClass oder der Provisioner kann kein Volume erstellen. kubectl describe pvc zeigt die Ursache in den Events.

4 von 5 PVC-Pending-Problemen haben dieselbe Ursache

Eine fehlende oder falsche StorageClass. Der Rest verteilt sich auf Provisioner-Fehler, Quota-Limits und falsche AccessModes. Hier ist der systematische Weg zur Lösung.

Erster Schritt -- immer:

# PVC-Status und Events prüfen
kubectl describe pvc my-pvc -n my-namespace

# Verfügbare StorageClasses anzeigen
kubectl get storageclass

Die Events-Sektion am Ende von kubectl describe pvc verrät fast immer die Ursache.

Ursache 1: StorageClass existiert nicht

Symptom in den Events:

Events:
  Warning  ProvisioningFailed  storageclass.storage.k8s.io "fast-ssd" not found

Das PVC referenziert eine StorageClass, die im Cluster nicht existiert.

# Alle StorageClasses auflisten
kubectl get sc

# Default StorageClass identifizieren (hat die Annotation "is-default-class: true")
kubectl get sc -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations.storageclass\.kubernetes\.io/is-default-class}{"\n"}{end}'

Lösung: Entweder die fehlende StorageClass anlegen oder das PVC auf eine vorhandene StorageClass ändern:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: standard  # Auf vorhandene SC ändern
  resources:
    requests:
      storage: 10Gi

Keine Default StorageClass gesetzt

Wenn das PVC keine storageClassName angibt und keine Default StorageClass existiert, bleibt es ewig Pending -- ohne hilfreiche Fehlermeldung.

# Default StorageClass setzen
kubectl patch storageclass standard \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

Ursache 2: Provisioner läuft nicht

Die StorageClass existiert, aber der zugehörige Provisioner-Pod ist down oder fehlerhaft.

# Provisioner der StorageClass herausfinden
kubectl get sc standard -o jsonpath='{.provisioner}'
# Ausgabe z.B.: kubernetes.io/aws-ebs oder rancher.io/local-path

# Provisioner-Pods prüfen (Beispiel für verschiedene Provisioner)
kubectl get pods -n kube-system | grep -i provisioner
kubectl get pods -n kube-system | grep -i csi

Wenn der Provisioner-Pod nicht läuft oder in CrashLoopBackOff ist, kann kein Volume erstellt werden. Prüfen Sie die Logs:

# Provisioner-Logs anschauen (Beispiel EBS CSI)
kubectl logs -n kube-system deployment/ebs-csi-controller --tail=50

Ursache 3: ResourceQuota oder LimitRange erreicht

In Namespaces mit ResourceQuota kann die Storage-Quota erschöpft sein.

# Quota im Namespace prüfen
kubectl get resourcequota -n my-namespace
kubectl describe resourcequota -n my-namespace

Typische Ausgabe bei erreichter Quota:

Name:                    storage-quota
Resource                 Used    Hard
--------                 ----    ----
requests.storage         95Gi    100Gi
persistentvolumeclaims   9       10

Hier sind 95 von 100 Gi verbraucht. Ein neues PVC mit 10Gi würde die Quota überschreiten.

Lösung: Quota erhöhen oder nicht mehr benötigte PVCs löschen.

Ursache 4: AccessMode passt nicht

Nicht jeder Storage-Typ unterstützt jeden AccessMode.

Wenn Sie ReadWriteMany mit einem Block-Storage-Provisioner anfordern, bleibt das PVC Pending.

# AccessMode des PVC prüfen
kubectl get pvc my-pvc -o jsonpath='{.spec.accessModes}'

Statisches Provisioning: PV manuell matchen

Wenn kein dynamischer Provisioner vorhanden ist, müssen Sie das PV manuell erstellen. Damit PVC und PV sich finden, müssen StorageClass, AccessMode und Capacity übereinstimmen:

# PersistentVolume erstellen
apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  storageClassName: manual
  hostPath:
    path: /data/my-pv
---
# PVC, das dieses PV matcht
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: manual
  resources:
    requests:
      storage: 10Gi

Debugging-Checkliste

Wenn nichts offensichtlich ist, gehen Sie diese Liste durch:

1. kubectl describe pvc -- Events lesen
2. kubectl get sc -- Existiert die StorageClass?
3. kubectl get pods -A | grep -i csi -- Läuft der Provisioner?
4. kubectl get resourcequota -n <ns> -- Quota erreicht?
5. kubectl get pv -- Gibt es ein passendes PV (bei statischem Provisioning)?
6. Cloud-Provider-Logs prüfen (IAM-Rechte, Disk-Limits)

FAQ

Warum bleibt mein PVC auch nach Stunden Pending ohne Event?

Wenn weder Events noch Fehler angezeigt werden, fehlt meistens die Default StorageClass. Ohne StorageClass und ohne explizite storageClassName im PVC passiert einfach nichts -- Kubernetes wartet stillschweigend.

Kann ich die StorageClass eines bestehenden PVC ändern?

Nein. Die StorageClass ist nach der Erstellung unveränderlich. Sie müssen das PVC löschen und neu erstellen. Sichern Sie vorher die Daten, falls das PVC bereits gebunden war.

Was bedeutet WaitForFirstConsumer bei der StorageClass?

Mit volumeBindingMode: WaitForFirstConsumer bleibt das PVC absichtlich in Pending, bis ein Pod es nutzt. Das ist kein Fehler, sondern gewollt -- es stellt sicher, dass das Volume in der richtigen Availability Zone erstellt wird.

Mein PVC ist Bound, aber der Pod kann es nicht mounten. Was nun?

Das ist ein anderes Problem. Prüfen Sie kubectl describe pod -- häufige Ursachen sind Multi-Attach-Fehler (Volume hängt noch an einem anderen Node) oder fehlende CSI-Node-Plugins.

Wenn Ihre Pods nach dem PVC-Fix im Status Pending bleiben, liegt es oft an Resource Limits. Unser Pod Pending Troubleshooting Guide zeigt Ihnen die nächsten Schritte.