kubernetes resource_error ai_generated true

persistentvolumeclaim is stuck in Pending state

ID: kubernetes/pvc-stuck-pending-no-storage-class

Also available as: JSON · Markdown · 中文

82%Fix Rate

87%Confidence

1Evidence

2023-03-01First Seen

Version Compatibility

Version	Status	Introduced	Deprecated	Notes
Kubernetes 1.28.x	active	—	—	—
Kubernetes 1.29.x	active	—	—	—
CSI drivers v1.30.x	active	—	—	—

Root Cause

The PersistentVolumeClaim cannot bind because the requested storage class does not exist, the provisioner is not deployed, or no matching PersistentVolume is available.

generic

中文

PersistentVolumeClaim 无法绑定，因为请求的存储类不存在、Provisioner 未部署或没有可用的匹配 PersistentVolume。

Official Documentation

https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims

Workarounds

85% success Check StorageClass existence: `kubectl get storageclass`. If the requested class (e.g., 'fast') is missing, create it: `kubectl apply -f - <<EOF apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: fast provisioner: kubernetes.io/aws-ebs parameters: type: gp3 EOF`
```
Check StorageClass existence: `kubectl get storageclass`. If the requested class (e.g., 'fast') is missing, create it: `kubectl apply -f - <<EOF
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast
provisioner: kubernetes.io/aws-ebs
parameters:
  type: gp3
EOF`
```
80% success If using a CSI driver, verify the driver is deployed: `kubectl get csidrivers`. If missing, install the driver (e.g., EBS CSI driver: `kubectl apply -k "github.com/kubernetes-sigs/aws-ebs-csi-driver/deploy/kubernetes/overlays/stable/?ref=master"`).
```
If using a CSI driver, verify the driver is deployed: `kubectl get csidrivers`. If missing, install the driver (e.g., EBS CSI driver: `kubectl apply -k "github.com/kubernetes-sigs/aws-ebs-csi-driver/deploy/kubernetes/overlays/stable/?ref=master"`).
```
90% success Describe the PVC for detailed events: `kubectl describe pvc <pvc-name> -n <namespace>`. Look for 'waiting for first consumer to be created before binding' which indicates dynamic provisioning is waiting for a pod. If so, create a pod that uses the PVC.
```
Describe the PVC for detailed events: `kubectl describe pvc <pvc-name> -n <namespace>`. Look for 'waiting for first consumer to be created before binding' which indicates dynamic provisioning is waiting for a pod. If so, create a pod that uses the PVC.
```

中文步骤

检查 StorageClass 是否存在：`kubectl get storageclass`。如果请求的类（例如 'fast'）缺失，创建它：`kubectl apply -f - <<EOF
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast
provisioner: kubernetes.io/aws-ebs
parameters:
  type: gp3
EOF`

如果使用 CSI 驱动，验证驱动是否部署：`kubectl get csidrivers`。如果缺失，安装驱动（例如 EBS CSI 驱动：`kubectl apply -k "github.com/kubernetes-sigs/aws-ebs-csi-driver/deploy/kubernetes/overlays/stable/?ref=master"`）。

描述 PVC 以获取详细事件：`kubectl describe pvc <PVC名称> -n <命名空间>`。查找 'waiting for first consumer to be created before binding'，这表示动态配置正在等待 Pod。如果是，创建一个使用该 PVC 的 Pod。

Dead Ends

Common approaches that don't work:

Delete and recreate the PVC with the same spec. 85% fail
Recreating the same PVC without fixing the storage class or provisioner will result in the same Pending state.
Manually create a PersistentVolume without matching the PVC's storage class or size. 70% fail
A manually created PV must match the PVC's storage class, access modes, and size (or be larger) to bind. Mismatched PVs will remain unbound.
Set storageClassName to empty string to use default class without verifying existence. 60% fail
If no default StorageClass exists, the PVC will still be Pending. Use `kubectl get storageclass` to verify.