PVC Pending
This status occurs when a PersistentVolumeClaim cannot bind to a PersistentVolume due to missing storage classes or unsatisfied resource parameters.
Usually happens because:
- ☑ Referenced storageClassName does not exist or is misspelled
- ☑ Static PV size parameters or accessModes fail to match the PVC criteria
- ☑ WaitForFirstConsumer binding mode is active, awaiting Pod deployment scheduling
🔍 Quick Checklist:
What is PVC Pending?
A 'PVC Pending' (PersistentVolumeClaim Pending) status indicates that the claim has been created but cannot bind to an appropriate PersistentVolume (PV). In Kubernetes v1.36 storage architectures, this binding is handled dynamically by a volume provisioner associated with the requested StorageClass, or statically by matching labels and resource sizes. Common triggers include referencing non-existent StorageClasses, requesting storage capacities exceeding physical limits, or using 'waitForFirstConsumer' binding modes which intentionally delay binding until a Pod requests the storage.
Common Causes
- Missing or wrong StorageClass: The PVC manifest references a 'storageClassName' that does not exist in the cluster.
- Unsatisfied static PV capacity or selectors: Statically defined PersistentVolumes do not match the size request or selector labels specified in the PVC.
- StorageClass waitForFirstConsumer mode: The StorageClass uses the 'volumeBindingMode: WaitForFirstConsumer' setting, meaning the PVC will remain Pending until a Pod referencing it is scheduled.
| Cause | Frequency |
|---|---|
| StorageClass name typo or missing provisioner | ⭐⭐⭐⭐⭐ |
| Dynamic volumeBindingMode is set to WaitForFirstConsumer (expected behavior) | ⭐⭐⭐⭐ |
| Static PVs size requests exceed available allocations | ⭐⭐⭐ |
Common Mistakes
- Mistyping the `storageClassName` string inside the PVC manifest, causing the controller loop to search for a non-existent provisioner.
- Panicking when a PVC remains Pending under `WaitForFirstConsumer` mode before scheduling the Pod (this is expected behavior; the volume provisioner needs to know the Pod's target node zone configuration first).
How to Fix
Kubernetes Operations & Verification
Inspect available StorageClass systems and check their volumeBindingMode properties.
# 1. List active StorageClasses
$ kubectl get storageclass
# 2. Describe StorageClass parameters
$ kubectl describe storageclass gp3Platform Specific Fixes
Check the events of the PVC and monitor CSI controller pods logs.
# 1. Inspect PVC events logs details
kubectl describe pvc data-claim
# 2. Read CSI controller provisioner logs
kubectl logs -n kube-system deploy/ebs-csi-controller -c csi-provisioner --tail=50Best Practices
- Establish default StorageClass rules inside the cluster configuration to capture empty storageClass calls.
- Verify dynamic CSI driver controllers are updated to match cloud platform API upgrades.
Frequently Asked Questions (FAQ)
Q: Why is my PVC stuck in Pending status?
This means Kubernetes cannot find or dynamically create a PersistentVolume (PV) that matches the PVC's storage class, size requests, or access modes. Run 'kubectl describe pvc <pvc-name>' to check the events.
Q: What does 'volumeBindingMode: WaitForFirstConsumer' mean?
This is a setting in the StorageClass. It tells Kubernetes not to create the volume immediately when the PVC is created, but rather wait until a Pod that uses the PVC is scheduled. This ensures the volume is created in the same zone as the node the Pod is running on. In this case, 'Pending' is normal and will resolve when you start the Pod.
Q: How do I troubleshoot static PV binding failures?
Ensure you have a PV created with a size equal to or greater than the PVC requests, matching 'accessModes' (e.g. ReadWriteOnce), and matching 'storageClassName'. if any of these mismatch, the PVC will stay Pending.
Q: Why does it say 'waiting for a volume to be created, either by external provisioner...'?
This means the dynamic volume provisioner (like AWS EBS CSI or GCP Persistent Disk driver) is either not installed or is failing to call the cloud provider's API. Check the logs of the CSI controller pod in the kube-system namespace.