How to Fix PVC Pending in Kubernetes: Quick Troubleshooting Guide

A PersistentVolumeClaim (PVC) stays in Pending state when Kubernetes cannot find or create a matching PersistentVolume (PV). To fix this, ensure a suitable StorageClass exists and your PVC matches its parameters, or manually create a matching PV.

Why This Happens

A PVC remains pending because Kubernetes cannot find a PersistentVolume that meets the claim's requirements. This usually happens if no PV exists with the requested size, access mode, or storage class, or if dynamic provisioning is not set up correctly.

yaml

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: fast-storage

Output

Status: Pending
Reason: no persistent volumes available for this claim and no storage class is set for dynamic provisioning

The Fix

Check if a matching StorageClass exists and supports dynamic provisioning. If not, create a PersistentVolume manually that matches the PVC's requirements. Also, verify the storageClassName in the PVC matches an existing StorageClass.

yaml

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-storage
provisioner: kubernetes.io/aws-ebs
parameters:
  type: gp2
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: fast-storage

Output

PVC 'my-pvc' status: Bound
PersistentVolume dynamically provisioned or matched successfully

Prevention

Always define and verify StorageClasses before creating PVCs. Use dynamic provisioning to avoid manual PV creation. Regularly check cluster storage resources and monitor PVC and PV statuses to catch issues early.

• Use kubectl get storageclass to list available classes.
• Match PVC storageClassName exactly.
• Set resource requests carefully to match available PVs.

Related Errors

Other common storage errors include:

• Failed to provision volume: Check provisioner logs and permissions.
• Volume is already used by another pod: Ensure access modes allow multiple mounts if needed.
• Insufficient storage capacity: Increase PV size or add more storage.

Key Takeaways

PVC stays pending when no matching PersistentVolume or StorageClass is found.

Ensure StorageClass exists and matches PVC's storageClassName for dynamic provisioning.

Manually create a PersistentVolume if dynamic provisioning is not available.

Regularly verify storage resources and PVC/PV statuses to prevent issues.

Match PVC resource requests and access modes with available PersistentVolumes.