Kubernetes PVC Pending Diagnosis: No StorageClass Satisfaction

This tutorial guides you through diagnosing and resolving a Kubernetes PersistentVolumeClaim (PVC) that remains in a ‘Pending’ state due to the absence of a suitable StorageClass. We will use YAML manifests and `kubectl` commands to illustrate the troubleshooting process.

Scenario: PVC Stuck in Pending

A new Pod is failing to start. The Pod’s logs don’t reveal any issues, and the Pod itself is running, but it’s stuck in a pending state. Inspecting the PVC reveals it’s in the ‘Pending’ state with a message indicating no StorageClass could be found to satisfy the claim. This is a common issue when StorageClasses aren’t correctly configured or when the cluster doesn’t have any StorageClasses.

Example 1: Initial Investigation – PVC Status

The first step is to examine the PVC’s status using `kubectl get pvc`. This reveals the ‘Reason’ and ‘Message’ fields, pinpointing the core problem.

kubectl get pvc my-pvc -n default
NAME          STATUS   VOLUME          CAPACITY   ACCESS MODES   STORAGECLASS   STORAGE MEDIUM   RECLAIM POLICY   AGE
my-pvc        Pending  default/my-volume   1Gi        RWO            null           local            Delete            10m

The output shows ‘Reason: Failed’ and ‘Message: no storageclass configured’.

Example 2: Listing StorageClasses and Their Parameters

Now, let’s check if any StorageClasses exist and if their parameters match the PVC’s requirements. Use `kubectl get storageclass` to list available StorageClasses.

kubectl get storageclass
NAME          PROVISIONER
null          kubernetes.io/null
standard      kubernetes.io/standard

In this case, we only have ‘null’ and ‘standard’ StorageClasses. The PVC’s claim is set to ‘null’, but the StorageClass is configured to use a provisioner. Let’s investigate the `standard` storageclass.

kubectl describe storageclass standard
Name:           standard
Selector:        functional.cattle.io/storage-provisioner
Reclaim Policy:  Delete
Provisioner:     kubernetes.io/standard
IsDefault:       true
...

The ‘standard’ StorageClass uses the `kubernetes.io/standard` provisioner. This means Kubernetes will attempt to automatically create a volume using a default provisioner that’s configured elsewhere (not part of this focused diagnosis).

Example 3: Creating a Suitable StorageClass and Updating the PVC

To resolve the issue, we need to create a StorageClass that satisfies the PVC’s requirements. Let’s define a StorageClass that utilizes the `kubernetes.io/standard` provisioner and that is compatible with our PVC.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: my-storageclass
provisioner: kubernetes.io/standard
reclaimPolicy: Delete
volumeBindingMode: Immediate
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: my-storageclass
  resources:
    requests:
      storage: 1Gi
  ... #other spec fields

Now, apply the new StorageClass and the updated PVC definition.

kubectl apply -f pvc-storageclass.yaml

After applying the manifest, check the PVC’s status again:

kubectl get pvc my-pvc -n default
NAME          STATUS   VOLUME          CAPACITY   ACCESS MODES   STORAGECLASS   STORAGE MEDIUM   RECLAIM POLICY   AGE
my-pvc        Pending  default/my-volume   1Gi        RWO            my-storageclass  local            Delete            2m

The PVC’s status has changed to ‘Bound’ now, indicating that the StorageClass successfully provisioned a volume.

Conclusion

By systematically checking the PVC’s status, listing available StorageClasses, and creating a suitable StorageClass that matches the PVC’s requirements, we were able to resolve the ‘Pending’ state and allow the Pod to start successfully. This process highlights the importance of properly configuring StorageClasses in Kubernetes to ensure persistent storage is available for your applications.