K8s StorageClass 动态供给（Dynamic Provisioning）失败排查

在 Kubernetes 里，手动创建 PV 再绑定 PVC 的方式在规模化场景下难以为继。StorageClass + 动态供给（Dynamic Provisioning） 让 PVC 一创建就自动按需生成后端存储卷，是生产环境的主流用法。但当供给失败时，PVC 会一直卡在 Pending。

动态供给的工作流

1. 用户创建 PVC，并在 spec.storageClassName 指定一个 StorageClass；
2. 集群里的 external-provisioner（CSI 的 provisioner sidecar）监听 PVC 事件；
3. 它调用对应 CSI 驱动的 CreateVolume，后端存储真正分配出一块卷；
4. Kubernetes 自动创建 PV 并与之绑定，PVC 变为 Bound。

排查第一步：看 PVC 事件

kubectl get pvc
kubectl describe pvc <pvc-name>

describe 的 Events 通常会直接给出失败原因，比如 failed to provision volume with StorageClass ...。

常见失败原因与对策

1. StorageClass 的 provisioner 名字写错，或对应 CSI 驱动没装

kubectl get storageclass
kubectl get pods -n kube-system | grep -i <provisioner>

• provisioner 名称必须与已部署的 CSI 驱动完全一致（如 ebs.csi.aws.com 拼写错一个字母都不行）；
• 如果驱动 Pod 没起来（镜像拉取失败、RBAC 缺失），供给自然不会发生。

2. 没有设置默认 StorageClass，而 PVC 未显式指定

kubectl get storageclass   # 看是否有 (default) 标注
kubectl patch storageclass <name> -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

PVC 不写 storageClassName 时，只有默认 StorageClass 才会接管。

3. provisioner 报错：后端拒绝（配额/权限/参数）

看 provisioner 日志：

kubectl logs -n kube-system <external-provisioner-pod> -c external-provisioner

典型问题：后端存储配额耗尽、AK/SK 权限不足、StorageClass 里的 parameters 非法（如错误的 type/fstype）。

4. 绑定模式不匹配（WaitForFirstConsumer vs Immediate）

• volumeBindingMode: Immediate：创建 PVC 立即供给；
• WaitForFirstConsumer：等到有 Pod 真正使用 PVC 才供给（拓扑感知场景常用）。

若 PVC 长期 Pending 且用了 WaitForFirstConsumer 但没有 Pod 引用它，属正常现象——先有消费方即可。

小结

动态供给失败先看 kubectl describe pvc 的 Events，再查 provisioner Pod 日志，八成是 provisioner 名错、驱动没装、或后端权限/配额问题。