容器与云原生 / 系统课时

追踪动态供应调用链

追踪动态供应调用链

动态供应卡住时,最有效的方法不是从某个 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 动态供应到 PV 绑定时序

先确认 PVC 与 StorageClass 是否能触发供应

从对象关系开始检查。下面命令读取 PVC 使用的 StorageClass、绑定模式、实际 provisioner,以及当前 PVC 是否已经有选定节点或绑定 PV。

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

预期输出:

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

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

预期输出:

text
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 容器日志。

bash
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 与日志格式会不同):

text
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 能关联到真实后端卷。这样才能证明动态供应链已经完整走通。

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

目录与阅读设置

阅读设置

17

记录一个想法

追踪动态供应调用链

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

登录哪都通