Kubernetes PVC Pending Diagnosis: No StorageClass Satisfaction

This tutorial guides you through diagnosing a Kubernetes PersistentVolumeClaim (PVC) that remains in a ‘Pending’ state because no StorageClass can fulfill its requirements. We’ll use YAML manifests and kubectl commands to understand the issue and resolve it.

Scenario

You have a Pod that needs persistent storage. You create a PVC referencing a StorageClass. Initially, the PVC becomes ready. After a brief period, it transitions to ‘Pending’ and stays that way. Examining the PVC reveals no StorageClass is configured to satisfy its requests.

Example 1: Initial Problem – PVC in Pending State

Let’s create the initial configuration causing the problem. This example focuses solely on setting up the basic situation and demonstrating the initial ‘Pending’ state.

Step 1: Create a StorageClass

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-storage
provisioner: kubernetes.io/ppg
parameters:
  size: 1Gi
  # Add any other parameters you might need.
reclaimPolicy: Delete
status: WaitForFirstUse

This creates a StorageClass named `fast-storage` with a 1Gi provisioner. The `WaitForFirstUse` parameter is crucial for this scenario.

Step 2: Create a PVC

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

This PVC, named `my-pvc`, requests 1Gi of storage and specifically references the `fast-storage` StorageClass.

Step 3: Verify the PVC’s State

kubectl get pvc my-pvc

The output will initially show the PVC in a ‘Bound’ state. After a short delay (depending on your cluster), it will transition to ‘Pending’.

kubectl get pvc my-pvc -o yaml

The output will include a `status` field showing “Pending” and, critically, an `reason` field like “WaitForFirstUse” or similar, indicating the issue. The `status.phase` will be `Pending`.

Example 2: Investigating the StorageClass Configuration

Now, let’s examine the StorageClass to ensure it’s properly configured to handle the PVC’s requirements.

Step 1: Verify the StorageClass

kubectl describe storageclass fast-storage

Inspect the output. Ensure the following:

• The `provisioner` is set correctly (e.g., `kubernetes.io/ppg`).
• The `size` parameter matches the PVC’s `resources.requests.storage` value (e.g., `1Gi`).
• The `reclaimPolicy` is appropriate for your needs (typically `Delete` for test environments).

If the `provisioner` is incorrect, the PVC will never be satisfied. For instance, if the provisioner is missing, the storage provisioning will fail.

Step 2: Check StorageClass Status

kubectl get storageclass fast-storage -o yaml

This will show the storageclass status. Look for any error messages or unexpected values in the `status` section. The `status.phase` will also be critical here – it should be `Active` or `Ready`. A value of ‘Pending’ at this point is unusual and suggests a broader problem with the underlying storage provisioning.

Example 3: Correcting the Problem – Matching StorageClass and PVC

The key is a precise match between the StorageClass and PVC requests. Let’s correct the scenario.

Step 1: Modify the PVC

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

Verify that the `storageClassName` in the PVC exactly matches the name of the StorageClass we created (in this case, `fast-storage`). Any discrepancy will cause the PVC to remain Pending.

Step 2: Verify PVC State

kubectl get pvc my-pvc

The PVC should now transition to a ‘Bound’ state.

kubectl get pvc my-pvc -o yaml

The output will show `status.phase` as `Bound`. Check the events related to the PVC (see below) to confirm the successful binding.

Step 3: Check PVC Events

kubectl get events pvc my-pvc --field-selector involvedObject.name=my-pvc --sort-by=-involvedObject.metadata.name

This command filters events specifically for the `my-pvc` PVC. The output will show the event that indicates the successful binding to a provisioned volume.