容器与云原生 / 系统课时
追踪动态供应调用链
追踪动态供应调用链
动态供应卡住时,最有效的方法不是从某个 Pod 日志开始猜,而是沿 PVC、StorageClass、CreateVolume、PV 和绑定状态逐段取证。本篇给出一条可复用的检查链,帮助你判断问题停在调度前、CSI 调用中,还是 PV 写回与绑定阶段。
学习目标
- 追踪 PVC 从创建到
CreateVolume、PV 生成和最终绑定的完整链路。 - 用 API 对象、事件和 Sidecar 日志判断供应动作停在哪一段。
- 正确识别
WaitForFirstConsumer导致的预期 Pending,避免把等待调度误判为故障。
动态供应不是 API Server 直接创建后端卷
PVC 引用 StorageClass 后,匹配该 provisioner 的 external-provisioner 会接管供应请求。它把容量、访问模式、StorageClass 参数以及必要的拓扑信息组装成 CreateVolume 请求,通过共享 Unix Domain Socket 调用 CSI Controller Driver;驱动再向真实存储后端创建卷。
CreateVolume 成功后,external-provisioner 根据返回的卷标识创建 PV,PV 的 spec.csi.driver 指向驱动名,spec.csi.volumeHandle 保存后端卷标识。随后 Kubernetes 的绑定控制逻辑完成 PV 与 PVC 的一对一绑定,PVC 的 spec.volumeName 最终指向该 PV。

先确认 PVC 与 StorageClass 是否能触发供应
从对象关系开始检查。下面命令读取 PVC 使用的 StorageClass、绑定模式、实际 provisioner,以及当前 PVC 是否已经有选定节点或绑定 PV。
NAMESPACE="<NAMESPACE>"
PVC="<PVC>"
SC="$(kubectl -n "$NAMESPACE" get pvc "$PVC" -o jsonpath='{.spec.storageClassName}')"
if [ -n "$SC" ]; then
MODE="$(kubectl get storageclass "$SC" -o jsonpath='{.volumeBindingMode}')"
PROVISIONER="$(kubectl get storageclass "$SC" -o jsonpath='{.provisioner}')"
printf 'storageClass=%s\nbindingMode=%s\nprovisioner=%s\n' "$SC" "${MODE:-Immediate}" "$PROVISIONER"
else
printf 'storageClass=<EMPTY>\n'
fi
kubectl -n "$NAMESPACE" get pvc "$PVC" -o 'custom-columns=NAME:.metadata.name,STATUS:.status.phase,VOLUME:.spec.volumeName,SELECTED_NODE:.metadata.annotations.volume\.kubernetes\.io/selected-node'预期输出:
storageClass=<STORAGE_CLASS>
bindingMode=<BINDING_MODE>
provisioner=<DRIVER_NAME>
NAME STATUS VOLUME SELECTED_NODE
<PVC> <STATUS> <PV_NAME> <NODE>若这里得到空 StorageClass,先确认 PVC 是显式设置了 storageClassName: "",还是集群没有为省略该字段的 PVC 注入默认 StorageClass;前一种情况会禁用动态供应。若绑定模式是 WaitForFirstConsumer,在没有可调度的消费 Pod 之前保持 Pending 可以是正常行为;当调度器选定节点后,PVC 上的 volume.kubernetes.io/selected-node 会成为判断拓扑供应是否已经启动的重要证据。
确认 CreateVolume 之后是否生成 PV
PVC 进入 Bound 后,可以从 spec.volumeName 反向检查 PV。这个步骤验证“后端卷已经有对应 Kubernetes 表示”以及驱动返回的卷标识是否落到了 volumeHandle。
PV="$(kubectl -n "$NAMESPACE" get pvc "$PVC" -o jsonpath='{.spec.volumeName}')"
kubectl get pv "$PV" -o 'custom-columns=NAME:.metadata.name,PHASE:.status.phase,DRIVER:.spec.csi.driver,HANDLE:.spec.csi.volumeHandle,CLAIM_NS:.spec.claimRef.namespace,CLAIM:.spec.claimRef.name'预期输出:
NAME PHASE DRIVER HANDLE CLAIM_NS CLAIM
<PV_NAME> Bound <DRIVER_NAME> <VOLUME_HANDLE> <NAMESPACE> <PVC>如果 CreateVolume 已成功但始终没有 PV,应优先检查 external-provisioner 在创建 PV 时是否遇到 API 权限、冲突或写入错误。若 PV 已存在但 PVC 未绑定,则继续核对 PV 的 claimRef、StorageClass、访问模式和 VolumeMode,而不是重复创建后端卷。
用事件和 Sidecar 日志锁定卡点
对象状态告诉你“停在哪里”,事件和日志用来解释“为什么停”。先看 PVC Events,再查看负责该驱动的 Controller Pod 中 csi-provisioner 容器日志。
kubectl -n "$NAMESPACE" describe pvc "$PVC"
CSI_NAMESPACE="<CSI_NAMESPACE>"
CONTROLLER_POD="<CONTROLLER_POD>"
kubectl -n "$CSI_NAMESPACE" logs "$CONTROLLER_POD" -c csi-provisioner --since=10m预期输出(不同驱动的 Reason 与日志格式会不同):
Events:
Type Reason Message
<TYPE> <REASON> <MESSAGE>
<CSI_PROVISIONER_LOG_LINES>排查时按证据顺序收敛:没有有效 StorageClass 就先修 PVC 或默认类;WaitForFirstConsumer 尚未选节点就查 Pod 调度;已经进入 CreateVolume 但返回参数、容量、拓扑或超时错误,就查 StorageClass 参数、驱动 Controller 日志与存储后端;CreateVolume 成功却无法创建 PV,则转向 external-provisioner 的 Kubernetes API 权限与对象写回。
最终闭环不是“日志里出现 success”这一句话,而是 PVC 为 Bound、spec.volumeName 指向唯一 PV,PV 的 spec.csi.driver 与 StorageClass provisioner 对应,并且 volumeHandle 能关联到真实后端卷。这样才能证明动态供应链已经完整走通。