Issue#

A pod that mounts a PersistentVolumeClaim never starts and stays in Pending. kubectl describe pod shows:

Warning FailedScheduling default-scheduler 0/3 nodes are available: pod has unbound immediate PersistentVolumeClaims. preemption: 0/3 nodes are available: 3 Preemption is not helpful for scheduling.

The PVC is also Pending, and kubectl describe pvc shows:

Warning FailedBinding persistentvolume-controller no persistent volumes available for this claim and no storage class is set

Cause#

The PVC does not set storageClassName, and the cluster has no default StorageClass. Kubernetes has nothing to provision a volume with, and no matching static PV exists, so the claim never binds.

This is common on kubeadm and bare-metal clusters, which do not ship a provisioner. It also happens when the default StorageClass annotation was removed or the provisioner was uninstalled.

Solution#

  1. Check which StorageClasses exist and whether one is marked (default):
kubectl get storageclass
  1. If a StorageClass exists but none is the default, mark it as the default:
kubectl patch storageclass <name> \ -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "true"}}}'
  1. If no StorageClass exists, install a provisioner. For single-node or lab clusters, Rancher's local-path-provisioner works well:
kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/master/deploy/local-path-storage.yaml kubectl patch storageclass local-path \ -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "true"}}}'

Note: local-path stores data on the node's disk, so volumes are tied to that node. For production, use your cloud or storage vendor's CSI driver, such as Longhorn, Ceph RBD, or a cloud provider CSI driver.

  1. Fix the existing PVC:

  2. On Kubernetes 1.28+, a PVC with no storageClassName field is assigned the new default automatically.

  3. If the PVC has storageClassName: "", it explicitly asks for no class and will never use the default. Because the field cannot be changed after creation, delete and recreate the claim with the class set:
apiVersion: v1 kind: PersistentVolumeClaim metadata: name: data spec: accessModes: - ReadWriteOnce storageClassName: local-path resources: requests: storage: 5Gi
kubectl delete pvc data -n <namespace> kubectl apply -f pvc.yaml -n <namespace>

Tip: Only one StorageClass should be marked default. If two are marked, the most recently created one wins, which can be confusing. Remove the annotation from the other one by setting it to "false".

Verify#

kubectl get storageclass kubectl get pvc -n <namespace> kubectl get pods -n <namespace>

Exactly one StorageClass should show (default), and the PVC STATUS should be Bound. The pod should leave Pending and start.

Note: If the StorageClass uses volumeBindingMode: WaitForFirstConsumer, as local-path does, the PVC stays Pending until a pod that uses it is scheduled. That is expected.