A pod is stuck because its PVC stays Pending — diagnose and fix it
A pod will not start; it is stuck waiting on its volume. You check the PVC and describe it. Explain what a Pending PVC means, name the most likely causes, and give the fix for the event shown.
$ kubectl get pvc
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
data-app Pending fast-ssd 6m
$ kubectl describe pvc data-app
...
Events:
Type Reason Age Message
---- ------ ---- -------
Warning ProvisioningFailed 6m storageclass.storage.k8s.io "fast-ssd" not foundDiagnose the cause and give the fix.
A Pending PVC never bound: provisioning could not satisfy the claim. The describe event says StorageClass fast-ssd is not found, so no provisioner ran. Other causes: no default StorageClass, or no PV matching the claim. Fix: reference an existing StorageClass, or set a default.
- ✗Blaming the pod or image when the event points at storage provisioning
- ✗Ignoring the describe events, which name the exact provisioning failure
- ✗Assuming a Pending PVC will bind on its own without a valid StorageClass
- →How would the diagnosis change if there were no ProvisioningFailed event at all?
- →How do you mark a StorageClass as the cluster default?
Solution
1. What Pending means
A PVC in Pending is an unbound claim: Kubernetes neither found nor created a PV for it. The first step is always to read its events:
$ kubectl describe pvc data-app
Events:
Warning ProvisioningFailed 6m storageclass.storage.k8s.io "fast-ssd" not found2. Diagnosis
The event names the cause directly: the PVC references storageClassName: fast-ssd, which does not exist, so no provisioner acted. The usual causes of Pending:
- an unknown
storageClassNameis referenced (our case); - there is no default StorageClass and no name was given;
- a static setup with no PV matching the requested size and access mode.
3. The fix
Reference a class that exists (check kubectl get storageclass), or mark one default:
$ kubectl get storageclass
$ kubectl patch storageclass standard \
-p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'Then recreate the PVC with a valid storageClassName (or rely on the default). The provisioner now creates a PV, the PVC moves to Bound, and the pod starts.
