容器与云原生 / 系统课时
追踪 Attach 与 Mount 调用链
追踪 Attach 与 Mount 调用链
Pod 已经被调度,并不代表卷已经能被容器使用。本课沿着 VolumeAttachment、ControllerPublishVolume、NodeStageVolume 与 NodePublishVolume 串起证据链,帮助你判断故障停在控制面 Attach,还是节点侧 Stage/Publish。
学习目标
- 判断 CSI 驱动是否需要 Attach,以及何时应该出现 VolumeAttachment。
- 按 Attach → Stage → Publish 的顺序定位挂载失败。
- 用 Kubernetes 对象、Pod 事件和 CSI 组件日志区分控制面与节点侧根因。
先判断链路是否包含 Attach
CSI 挂载链并不是固定四步。先查看 CSIDriver.spec.attachRequired:为 false 时,Kubernetes 跳过 Attach,没有 VolumeAttachment 属于正常现象;为 true 或未显式设置时,Attach/Detach Controller 会为目标 PV 与 Node 创建 VolumeAttachment。
VolumeAttachment 记录“这个卷应附加到这个节点”的意图与状态。external-attacher 监听该对象并调用 CSI Controller 的 ControllerPublishVolume。调用成功后,status.attached 变为 true,驱动返回的 publish_context 会供后续节点侧操作使用。
沿对象和事件建立证据链
下面的主检查假设 Pod app-0 在 demo 命名空间中通过 PVC data 使用 CSI PV。按现场名称修改变量后执行:
NS="demo"
POD="app-0"
PVC="data"
NODE=$(kubectl -n "$NS" get pod "$POD" -o jsonpath='{.spec.nodeName}')
PV=$(kubectl -n "$NS" get pvc "$PVC" -o jsonpath='{.spec.volumeName}')
DRIVER=$(kubectl get pv "$PV" -o jsonpath='{.spec.csi.driver}')
HANDLE=$(kubectl get pv "$PV" -o jsonpath='{.spec.csi.volumeHandle}')
printf 'node=%s\npv=%s\ndriver=%s\nvolumeHandle=%s\n' "$NODE" "$PV" "$DRIVER" "$HANDLE"
kubectl get csidriver "$DRIVER" -o custom-columns='NAME:.metadata.name,ATTACH_REQUIRED:.spec.attachRequired'
kubectl get volumeattachment -o custom-columns='NAME:.metadata.name,ATTACHER:.spec.attacher,NODE:.spec.nodeName,PV:.spec.source.persistentVolumeName,ATTACHED:.status.attached'
kubectl -n "$NS" get events --field-selector "involvedObject.kind=Pod,involvedObject.name=$POD" --sort-by=.metadata.creationTimestamp -o custom-columns='TIME:.metadata.creationTimestamp,TYPE:.type,REASON:.reason,OBJECT:.involvedObject.name,MESSAGE:.message'预期输出
node=<VALUE>
pv=<VALUE>
driver=<VALUE>
volumeHandle=<ID>
NAME ATTACH_REQUIRED
<VALUE> true
NAME ATTACHER NODE PV ATTACHED
<VALUE> <VALUE> <VALUE> <VALUE> true
TIME TYPE REASON OBJECT MESSAGE
<TIME> Normal SuccessfulAttachVolume app-0 <VALUE>名称、时间和事件文本会因集群与 kubectl 版本不同而变化。关键是把 Pod 的 spec.nodeName、PVC 对应 PV、PV 的 CSI 驱动与 VolumeAttachment 的节点和 PV 对齐。若 attachRequired=false,则不应期待对应 VolumeAttachment 或 SuccessfulAttachVolume。

从 Attach 切到 Stage 与 Publish
当 status.attached=true 后,控制面 Attach 已经完成,排查重点应转到 Pod 所在节点。kubelet 通过 CSI socket 调用 Node Plugin;如果驱动在 NodeGetCapabilities 中声明 STAGE_UNSTAGE_VOLUME,kubelet 会先执行 NodeStageVolume,把卷准备到节点级 staging 路径,再为 Pod 执行 NodePublishVolume。
NodeStageVolume 常承担设备发现、格式化、文件系统挂载或网络卷准备等节点级工作;NodePublishVolume 则把已经准备好的卷发布到具体 Pod 的目标路径。驱动未声明 Stage/Unstage 能力时,没有 NodeStageVolume 也是正常路径。
按失败位置判断根因
| 证据 | 更可能停在哪一层 | 下一处检查 |
|---|---|---|
VolumeAttachment.status.attached=false 且有 attachError |
ControllerPublishVolume 或后端 Attach |
external-attacher、CSI Controller、存储后端 |
一直没有对应 VolumeAttachment,且 attachRequired=true |
Attach/Detach Controller 或对象关联 | PV、Node、控制面事件与日志 |
attached=true,Pod 持续 FailedMount |
节点侧 Stage/Publish | kubelet 与 CSI Node Plugin |
Node Plugin 日志显示 NodeStageVolume 失败 |
设备、文件系统、staging path 或节点依赖 | 设备可见性、文件系统工具、挂载参数 |
NodeStageVolume 成功而 NodePublishVolume 失败 |
Pod 目标路径或发布上下文 | target path、只读模式、权限、Secret |
修复后不要只看 Pod 是否变成 Running。重新执行主检查,确认需要 Attach 的驱动对应 VolumeAttachment 已为 attached=true,Pod 不再持续产生新的 FailedAttachVolume 或 FailedMount;再用 CSI 组件日志确认此前失败的 RPC 已成功返回,形成“对象状态 + RPC 阶段 + Pod 结果”的闭环。