# persistentvolumeclaim 卡在 Pending 状态

- **ID:** `kubernetes/pvc-stuck-pending-no-storage-class`
- **领域:** kubernetes
- **类别:** resource_error
- **验证级别:** ai_generated
- **修复率:** 82%

## 根因

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

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| Kubernetes 1.28.x | active | — | — |
| Kubernetes 1.29.x | active | — | — |
| CSI drivers v1.30.x | active | — | — |

## 解决方案

1. ```
   检查 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`
   ```
2. ```
   如果使用 CSI 驱动，验证驱动是否部署：`kubectl get csidrivers`。如果缺失，安装驱动（例如 EBS CSI 驱动：`kubectl apply -k "github.com/kubernetes-sigs/aws-ebs-csi-driver/deploy/kubernetes/overlays/stable/?ref=master"`）。
   ```
3. ```
   描述 PVC 以获取详细事件：`kubectl describe pvc <PVC名称> -n <命名空间>`。查找 'waiting for first consumer to be created before binding'，这表示动态配置正在等待 Pod。如果是，创建一个使用该 PVC 的 Pod。
   ```

## 无效尝试

- **Delete and recreate the PVC with the same spec.** — Recreating the same PVC without fixing the storage class or provisioner will result in the same Pending state. (85% 失败率)
- **Manually create a PersistentVolume without matching the PVC's storage class or size.** — 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. (70% 失败率)
- **Set storageClassName to empty string to use default class without verifying existence.** — If no default StorageClass exists, the PVC will still be Pending. Use `kubectl get storageclass` to verify. (60% 失败率)