Introduction

Persistent storage problems in Kubernetes usually come from a mismatch between what a claim requests and what the cluster can actually provision. When kubectl create fails or the claim stays pending, the fix is rarely the command itself; it is usually a problem in the YAML, the storage class, or the cluster storage backend.

Understand The Objects Involved

There are three pieces to check:

• a PersistentVolumeClaim, which is what your workload asks for
• sometimes a PersistentVolume, if you are using static provisioning
• often a StorageClass, if the cluster provisions storage dynamically

If any of those disagree on size, access mode, or class name, the bind will fail.

Start With A Minimal Working Claim

A simple PVC using a known storage class is the best diagnostic baseline.

1apiVersion: v1
2kind: PersistentVolumeClaim
3metadata:
4  name: demo-pvc
5spec:
6  accessModes:
7    - ReadWriteOnce
8  resources:
9    requests:
10      storage: 1Gi
11  storageClassName: standard

Create it with:

kubectl apply -f pvc.yaml
kubectl get pvc demo-pvc
kubectl describe pvc demo-pvc

kubectl describe is the important command because the event section usually explains why binding failed.

Check The Cluster Storage Setup

If the claim remains in Pending, inspect the available storage classes first.

kubectl get storageclass
kubectl describe storageclass standard

Then check existing persistent volumes.

kubectl get pv
kubectl describe pv

You are looking for these mismatches:

• requested storageClassName does not exist
• no provisioner is installed for that class
• requested access mode is unsupported
• requested size is larger than what static volumes provide

Static Provisioning Example

If your cluster does not support dynamic provisioning, define the volume manually and make the claim match it.

1apiVersion: v1
2kind: PersistentVolume
3metadata:
4  name: demo-pv
5spec:
6  capacity:
7    storage: 1Gi
8  accessModes:
9    - ReadWriteOnce
10  hostPath:
11    path: /tmp/demo-data
12  persistentVolumeReclaimPolicy: Retain
13---
14apiVersion: v1
15kind: PersistentVolumeClaim
16metadata:
17  name: demo-pvc
18spec:
19  accessModes:
20    - ReadWriteOnce
21  resources:
22    requests:
23      storage: 1Gi
24  volumeName: demo-pv

This example is useful for local development clusters. On production clusters, the volume source would usually be a real storage backend instead of hostPath.

Distinguish Create Errors From Bind Errors

There are two broad failure modes:

• 'kubectl create rejects the manifest immediately because the YAML or API fields are invalid'
• the object is created, but the controller cannot bind or provision storage

If the command itself errors out, validate the manifest:

kubectl apply --dry-run=client -f pvc.yaml
kubectl explain persistentvolumeclaim.spec

If creation succeeds but the PVC stays pending, the problem is inside the cluster control loop, not the CLI syntax.

Common Real Causes

In managed clusters, a missing or broken CSI driver is common. The storage class exists, but no provisioner is actually running. In self-managed clusters, RBAC or cloud credential problems can stop the provisioner from creating disks even though the YAML is correct.

Another frequent issue is using the wrong access mode. For example, some backends support ReadWriteOnce but not ReadWriteMany. If the claim asks for the wrong one, Kubernetes cannot match it.

Common Pitfalls

The most common mistake is assuming kubectl create failed when the real problem is visible only in the PVC events. Always run kubectl describe pvc before changing random fields.

Another mistake is copying a storage class name from another cluster. Storage classes are environment-specific. standard may exist in one cluster and not in another.

A third issue is debugging only the claim and ignoring the provisioner pods. If the CSI controller is crash-looping, no amount of PVC editing will fix the result.

Summary

• Most persistent storage issues are configuration mismatches, not kubectl command problems.
• Validate the manifest first, then inspect PVC events with kubectl describe pvc.
• Check StorageClass, PersistentVolume, and provisioner health together.
• Make sure size, access mode, and class name all line up.
• Separate client-side YAML errors from cluster-side provisioning failures.