Kubernetes里PVC一直Pending的排查方法(kubectl describe pvc看Events、StorageClass与WaitForFirstConsumer定位)

kubectl get pvc看到STATUS列一直停在Pending,引用它的Pod也卡在Pending起不来,Events里报pod has unbound immediate PersistentVolumeClaims。这种卡法碰到过不止一次,多数不是存储本身坏了,是绑定这一步没往下走。PVC要等一个容量够、accessModes对得上、storageClassName一致的PV才能Bound,缺一样就一直悬着。

这坑踩过两次。先看Events,别急着重装CSI驱动。

1、kubectl describe pvc data-db-0 -n shop,把Events那几行读完,Reason基本就定住了。常见四种:WaitForFirstConsumer后跟waiting for first consumer to be created before binding,是volumeBindingMode设成WaitForFirstConsumer的正常状态,PVC等Pod调度到节点才绑定,不算故障;FailedBinding后跟no persistent volumes available for this claim and no storage class is set,说明claim没写storageClassName、集群又没有默认StorageClass;storageclass.storage.k8s.io "fast" not found是class名字写错,或那份class建在另一个集群;ExternalProvisioning后跟waiting for a volume to be created, either by external provisioner "ebs.csi.aws.com" or manually created by system administrator,是控制面在等外部provisioner建卷。ProvisioningFailed这一条最杂,凭据、配额、后端容量的问题都塞在它的message里。

把报错串复制到日志里搜,别只盯末尾那行。Events只保留一段时间,现场遇到过describe出来Events是空的,那就没法靠Reason分诊,直接跳到查spec。

kubectl describe pvc data-db-0 -n shop
kubectl get pvc data-db-0 -n shop -o jsonpath='{.spec.storageClassName}{"\n"}{.spec.volumeName}{"\n"}{.spec.accessModes}{"\n"}{.spec.resources.requests.storage}{"\n"}'
kubectl get storageclass
kubectl get pv

2、静态供给的场景,拿spec逐项对。kubectl get pv列出的卷,容量要不小于claim的requests.storage,官方文档那个例子是100Gi的claim匹配不上50Gi的PV,绑定绝不会凑合着给个小的;accessModes要包含claim申请的模式,块存储一般只给ReadWriteOnce,申请ReadWriteMany就永远等不到;storageClassName要和claim写的一致,写成空字符串storageClassName: ""是明确禁用动态供给,只找无class的PV;selector非空时只认带对应label的PV,同时会把动态供给关掉;volumeName指到一个已经被别的claim绑走的PV,绑定也会一直悬着。上面几个字段一条jsonpath就能全打出来,不用逐个describe。

3、动态供给的场景,重点看provisioner有没有在干活。kubectl get storageclass看哪份标了default,再kubectl get sc fast -o jsonpath取provisioner和volumeBindingMode,把provisioner字段和claim注解volume.kubernetes.io/storage-provisioner对一下,两边名字不一致,claim就会挂着没人管。接着kubectl get csidriver看驱动装没装,kubectl get pods -A -o wide看controller那几个Pod是不是Running,报driver name ebs.csi.aws.com not found就是CSI压根没部署。真没起来的话,external-provisioner这个sidecar靠CreateVolume回调建PV,卡在哪一步日志里都写着,kubectl logs把csi-provisioner那个容器最后100行拉出来,多半是凭据、配额或者后端容量。

kubectl get csidriver
kubectl get pods -A -o wide | grep -i csi
kubectl get sc fast -o jsonpath='{.provisioner}{"\n"}{.volumeBindingMode}{"\n"}'
kubectl logs -n kube-system deploy/ebs-csi-controller -c csi-provisioner --tail=100
kubectl describe quota -n shop
kubectl patch pv pv-shop-data -p '{"spec":{"claimRef": null}}'

4、WaitForFirstConsumer的PVC要顺着Pod查。kubectl get pods -n shop -o wide看nodeName,空着就是调度器还没放置,去看Pod自己的FailedScheduling;Pod清单里直接写了nodeName绕过调度器,官方文档说这种claim会一直Pending,改用nodeSelector指定kubernetes.io/hostname。claim上出现volume.kubernetes.io/selected-node注解,说明节点已经选好,剩下的就是provisioning。部分云厂商和发行版在Kubernetes 1.24前后把默认StorageClass从standard调成standard-rwo,volumeBindingMode由Immediate变成WaitForFirstConsumer,升级完没建消费者Pod,PVC看着就像坏了。

5、几种不显眼的卡点。ReadWriteOnce的PV只认一个节点,Pod被调度到另一个节点就报volume node affinity conflict,跨可用区常见的是node(s) had volume node affinity conflict,要ReadWriteMany得换NFS这类共享文件系统;kubectl describe quota -n shop看命名空间配额,超了同样建不出卷;reclaimPolicy设成Retain的PV被旧claim占着,删掉Pod也不释放,得把claimRef清成null才能重新绑,上面那条kubectl patch pv就是干这个的。

实测这套describe pvc看Events的路子在Kubernetes 1.24、1.26、1.28、1.30、1.32,几个版本上没差多少,命令和Reason文案基本一致,报错串的词句会随版本微调,别照着老博客一字不差地搜。1.24的EOL是2023年7月28日,1.26是2024年2月28日,1.28是2024年10月22日,1.30是2025年7月15日,1.32是2026年2月28日,还在跑老版本的话,升级前顺手确认下默认StorageClass的volumeBindingMode。

把Events第一行和kubectl get storageclass的输出一并贴给存储插件的维护方,比反复删PVC重建省事。数据截至2026年11月。