容器与云原生 / 系统课时

排查 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 往往是预期状态,而不是供应故障。

bash
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

预期输出

text
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 已存在,就要继续检查调度条件。

PVC Pending 根因定位流程

按绑定模式沿证据链分类

先读取 StorageClass 和候选 PV,再看消费该 PVC 的 Pod。PVC 未显式设置 storageClassName 不等于一定“没有 StorageClass”:集群存在默认类时,控制平面可为 PVC 补上默认 StorageClass;显式设置 storageClassName: "" 则表示请求不使用 StorageClass,只能与无类的静态 PV 匹配。

bash
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>

预期输出

text
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>

接下来按现象归类:

  1. 没有可用 StorageClass:PVC 未指定类、集群又没有默认类时,不会触发动态供应,只能等待可匹配的静态 PV;若写了不存在的类,也无法进入预期的动态供应链。
  2. 没有匹配的静态 PV:候选 PV 需要处于 Available,容量不小于请求值,并兼容 accessModes、volumeMode、storageClassName 与 PVC selector。任一条件不满足都会继续 Pending。
  3. 正在等待首个消费者:WaitForFirstConsumer 会把卷选择或创建延后到 Pod 参与调度时。此时应查看 Pod 的调度事件,而不是把“等待 consumer”误判成 CSI 故障。
  4. 拓扑无法同时满足:Pod 的 nodeSelector、required affinity、污点容忍与 StorageClass allowedTopologies、已有 PV 的 nodeAffinity 可能没有交集,Scheduler 因而无法完成 VolumeBinding。
  5. 动态供应失败:PVC 事件出现 ProvisioningFailed、CSI gRPC 错误或反复重试时,问题已经进入 external-provisioner、CSI Controller 或存储后端。
  6. 容量不足:静态场景表现为没有足够大的匹配 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。

bash
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'

预期输出

text
NAME    STATUS   VOLUME
<PVC>   Bound    <PV_NAME>
NAME    PHASE     NODE
<POD>   <PHASE>   <NODE>

如果 PVC 已经 Bound,但 Pod 仍卡在 ContainerCreating,或事件出现 FailedAttachVolume、FailedMount,说明绑定阶段已经通过,故障边界应转向卷附加、NodePublish 或节点挂载,而不是继续把问题归因于 PVC Pending。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查 PVC 长期 Pending

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通