容器与云原生 / 系统课时
排查 PVC 长期 Pending
排查 PVC 长期 Pending
PVC 长期停在 Pending 不是一个根因,而是“尚未完成绑定”的结果。本课从 PVC 事件出发,区分正常等待、StorageClass 或 PV 匹配问题、动态供应失败、拓扑冲突与容量不足,并建立修复后的绑定验证闭环。
学习目标
- 用 PVC、StorageClass、PV 与 Pod 事件判断 Pending 属于正常等待还是故障。
- 按绑定模式定位静态匹配、动态供应、拓扑与容量问题。
- 修复后验证 PVC 已绑定,并确认 Pod 不再被卷绑定阶段阻塞。
先判断 Pending 是否真的异常
先看 PVC 自己,不要一开始就查 CSI 日志。Pending 只说明还没有得到可用 PV,真正的线索通常在 Events。如果 StorageClass 使用 WaitForFirstConsumer,且当前还没有引用该 PVC 的 Pod,Pending 往往是预期状态,而不是供应故障。
kubectl get pvc -n <NS> <PVC> -o custom-columns='NAME:.metadata.name,STATUS:.status.phase,VOLUME:.spec.volumeName,CLASS:.spec.storageClassName'
kubectl describe pvc -n <NS> <PVC>
kubectl get pvc -n <NS> <PVC> -o jsonpath='{.metadata.annotations.volume\.kubernetes\.io/selected-node}'
echo预期输出
NAME STATUS VOLUME CLASS
<PVC> Pending <SC>
...
Status: Pending
StorageClass: <SC>
Events:
<TYPE> <REASON> <TIME> <SOURCE> <MESSAGE>
<NODE_OR_EMPTY>最后一行来自延迟绑定时常见的 volume.kubernetes.io/selected-node 注解;为空并不自动代表故障,但若消费该 PVC 的 Pod 已存在,就要继续检查调度条件。

按绑定模式沿证据链分类
先读取 StorageClass 和候选 PV,再看消费该 PVC 的 Pod。PVC 未显式设置 storageClassName 不等于一定“没有 StorageClass”:集群存在默认类时,控制平面可为 PVC 补上默认 StorageClass;显式设置 storageClassName: "" 则表示请求不使用 StorageClass,只能与无类的静态 PV 匹配。
kubectl get sc -o custom-columns='NAME:.metadata.name,PROVISIONER:.provisioner,BINDING:.volumeBindingMode,RECLAIM:.reclaimPolicy'
kubectl get pv -o custom-columns='NAME:.metadata.name,STATUS:.status.phase,CAPACITY:.spec.capacity.storage,CLASS:.spec.storageClassName,MODES:.spec.accessModes,VOLUMEMODE:.spec.volumeMode'
kubectl describe pod -n <NS> <POD>预期输出
NAME PROVISIONER BINDING RECLAIM
<SC> <CSI_DRIVER> <MODE> <POLICY>
...
NAME STATUS CAPACITY CLASS MODES VOLUMEMODE
<PV_NAME> Available <SIZE> <SC> <MODE> <VOLUME_MODE>
...
Events:
<TYPE> <REASON> <TIME> <SOURCE> <SCHEDULER_MESSAGE>接下来按现象归类:
- 没有可用 StorageClass:PVC 未指定类、集群又没有默认类时,不会触发动态供应,只能等待可匹配的静态 PV;若写了不存在的类,也无法进入预期的动态供应链。
- 没有匹配的静态 PV:候选 PV 需要处于
Available,容量不小于请求值,并兼容accessModes、volumeMode、storageClassName与 PVC selector。任一条件不满足都会继续 Pending。 - 正在等待首个消费者:
WaitForFirstConsumer会把卷选择或创建延后到 Pod 参与调度时。此时应查看 Pod 的调度事件,而不是把“等待 consumer”误判成 CSI 故障。 - 拓扑无法同时满足:Pod 的
nodeSelector、required affinity、污点容忍与 StorageClassallowedTopologies、已有 PV 的nodeAffinity可能没有交集,Scheduler 因而无法完成 VolumeBinding。 - 动态供应失败:PVC 事件出现
ProvisioningFailed、CSI gRPC 错误或反复重试时,问题已经进入 external-provisioner、CSI Controller 或存储后端。 - 容量不足:静态场景表现为没有足够大的匹配 PV;动态场景通常由 CSI 驱动或存储后端返回容量、配额相关错误。
针对根因修复
无 StorageClass 时,应创建或选择正确的 StorageClass,或者准备满足声明条件的静态 PV。若 PVC 本来就要求静态绑定,不要为了“让它变绿”随意改成默认动态类。
静态 PV 不匹配时,逐项对齐容量、访问模式、卷模式、StorageClass 和 selector。对本地卷或带拓扑约束的卷,还要保证 PV nodeAffinity 与 Pod 可调度节点一致。
WaitForFirstConsumer 场景下,应先确保确实存在消费 PVC 的 Pod,再处理 Pod 调度约束。若 nodeSelector 或 required affinity 把 Pod 限制到 StorageClass 无法供应的区域,应修改调度条件或存储拓扑,而不是手工绑定一个不兼容的 PV。
出现 ProvisioningFailed 时再进入 CSI 供应链排查;认证、配额、后端容量和 CreateVolume 参数错误属于下一层证据。修复后 external-provisioner 通常会继续重试,不需要为了触发重试就盲目删除 PVC。
验证绑定闭环
修复完成后,至少同时确认 PVC 已 Bound、spec.volumeName 已写入,以及消费它的 Pod 不再因卷绑定失败而 Pending。
kubectl get pvc -n <NS> <PVC> -o custom-columns='NAME:.metadata.name,STATUS:.status.phase,VOLUME:.spec.volumeName'
kubectl get pod -n <NS> <POD> -o custom-columns='NAME:.metadata.name,PHASE:.status.phase,NODE:.spec.nodeName'预期输出
NAME STATUS VOLUME
<PVC> Bound <PV_NAME>
NAME PHASE NODE
<POD> <PHASE> <NODE>如果 PVC 已经 Bound,但 Pod 仍卡在 ContainerCreating,或事件出现 FailedAttachVolume、FailedMount,说明绑定阶段已经通过,故障边界应转向卷附加、NodePublish 或节点挂载,而不是继续把问题归因于 PVC Pending。