容器与云原生 / 系统课时
排查 VolumeAttachment 卡住
排查 VolumeAttachment 卡住
Pod 已调度且 PVC/PV 已绑定,却反复出现 FailedAttachVolume,说明故障已进入 Attach 链路。本课从 VolumeAttachment 追到 attacher、节点身份和后端卷,定位阻塞并验证修复。
学习目标
- 判断故障是否真的发生在 CSI Attach 阶段,而不是调度或节点挂载阶段
- 沿
PV → VolumeAttachment → external-attacher → ControllerPublishVolume → 后端卷建立证据链 - 在不破坏卷状态的前提下修复陈旧挂载、节点身份或控制器异常
先确认它真的是 Attach 阶段
先看 Pod 事件。如果 PVC 已经 Bound、Pod 已有 spec.nodeName,但事件反复出现 FailedAttachVolume、AttachVolume.Attach failed 或 Attach 超时,才继续排查 VolumeAttachment。如果 CSIDriver.spec.attachRequired 为 false,Kubernetes 会跳过 Attach,问题应转向 kubelet 与 Node Plugin 的挂载链路。
下面命令假设 Pod 只使用一个待排查 PVC;多卷 Pod 应为每个 PVC 分别执行。
NS='default'
POD='<POD_NAME>'
PVC='<PVC_NAME>'
kubectl -n "$NS" get pod "$POD" -o wide
kubectl -n "$NS" get pvc "$PVC"
kubectl -n "$NS" get events --field-selector involvedObject.kind=Pod,involvedObject.name="$POD" --sort-by=.lastTimestamp预期输出
NAME READY STATUS NODE
<POD_NAME> 0/1 ContainerCreating <NODE_NAME>
NAME STATUS VOLUME CAPACITY ACCESS MODES
<PVC_NAME> Bound <PV_NAME> <VALUE> <VALUE>
Warning FailedAttachVolume <TIME> attachdetach-controller AttachVolume.Attach failed for volume "<PV_NAME>": <ERROR>实际事件文案会因驱动和版本不同而变化,但关键证据是:Pod 已落到节点,PVC 已绑定,失败发生在 attach 而不是 provision 或 mount。
沿 VolumeAttachment 追到 ControllerPublish
需要 Attach 的 CSI 卷会形成一条明确链路:PV 给出驱动名和 volumeHandle,目标 Pod 给出 Kubernetes Node 名,VolumeAttachment 表达“把这个 PV 附加到这个节点”的意图,external-attacher 再调用驱动的 ControllerPublishVolume 并更新 status.attached。

用下面的命令把这些对象串起来。<...> 是需要替换的实际值。
NS='default'
POD='<POD_NAME>'
PVC='<PVC_NAME>'
PV="$(kubectl -n "$NS" get pvc "$PVC" -o jsonpath='{.spec.volumeName}')"
NODE="$(kubectl -n "$NS" get pod "$POD" -o jsonpath='{.spec.nodeName}')"
DRIVER="$(kubectl get pv "$PV" -o jsonpath='{.spec.csi.driver}')"
HANDLE="$(kubectl get pv "$PV" -o jsonpath='{.spec.csi.volumeHandle}')"
printf 'PV=%s\nNODE=%s\nDRIVER=%s\nHANDLE=%s\n' "$PV" "$NODE" "$DRIVER" "$HANDLE"
kubectl get csidriver "$DRIVER" -o jsonpath='{.spec.attachRequired}{"\n"}'
kubectl get csinode "$NODE" -o jsonpath='{range .spec.drivers[*]}{.name}{"\t"}{.nodeID}{"\n"}{end}' | grep -F "$DRIVER"
kubectl get volumeattachment -o custom-columns='NAME:.metadata.name,PV:.spec.source.persistentVolumeName,NODE:.spec.nodeName,ATTACHER:.spec.attacher,ATTACHED:.status.attached,ERROR:.status.attachError.message' | grep -F "$PV"预期输出
PV=<PV_NAME>
NODE=<NODE_NAME>
DRIVER=<CSI_DRIVER>
HANDLE=<VOLUME_HANDLE>
true
<CSI_DRIVER> <CSI_NODE_ID>
<VOLUMEATTACHMENT_NAME> <PV_NAME> <NODE_NAME> <CSI_DRIVER> false <ERROR>若 ATTACHED=true,Attach 已完成,下一步应排查 Node Plugin 的 Stage/Publish;若 ATTACHED=false 且 ERROR 有内容,优先按错误定位。VolumeAttachment.spec.nodeName 是 Kubernetes Node 名,而后端真正使用的实例标识通常来自该节点 CSINode 中对应驱动的 nodeID,两者不能想当然地等同。
看 external-attacher 与后端错误
status.attachError 只保留结果,external-attacher 日志通常能看到具体 CSI RPC、重试和 gRPC 状态。先找到含 csi-attacher 容器的 Controller Pod,再查看同一时间窗口的日志。
kubectl get pods -A -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,CONTAINERS:.spec.containers[*].name' | grep -F 'csi-attacher'
CSI_NS='<CSI_NAMESPACE>'
CONTROLLER_POD='<CSI_CONTROLLER_POD>'
kubectl -n "$CSI_NS" logs "$CONTROLLER_POD" -c csi-attacher --since=10m预期输出
<CSI_NAMESPACE> <CSI_CONTROLLER_POD> <CONTAINER_LIST>
<TIME> ... ControllerPublishVolume ... volume=<VOLUME_HANDLE> node=<CSI_NODE_ID> ...
<TIME> ... rpc error: code = <GRPC_CODE> desc = <ERROR>常见根因可以直接按证据归类:NotFound 常见于卷 ID 或实例 ID 不存在;InvalidArgument、FailedPrecondition 常见于拓扑、访问模式或卷当前状态不允许附加;PermissionDenied 指向云 API 权限;DeadlineExceeded 更像控制器到后端 API 的网络或后端延迟。若后端显示卷仍附加在旧实例,还要确认旧节点是否已经真正卸载,避免把“陈旧 Attach”误处理成新的并发挂载。
修复时按责任边界下手
如果 external-attacher 不健康,先恢复 Controller 工作负载、Leader Election 和访问后端所需的凭据;如果 CSINode 缺少该驱动或 nodeID 与云实例不匹配,修复节点侧 CSI 注册或节点身份,而不是修改 PV。
后端卷若卡在 attaching、detaching 或仍绑定旧实例,应先确认旧工作负载已停止且没有有效写入,再按存储厂商流程解除陈旧附加。对于有可用区或拓扑限制的块存储,还要核对卷位置与目标 Node 的拓扑是否兼容。
验证解除阻塞
修复后不要只看 Pod 是否“偶尔启动”,还要确认 Attach 对象和事件链稳定恢复。
kubectl get volumeattachment -o custom-columns='NAME:.metadata.name,PV:.spec.source.persistentVolumeName,NODE:.spec.nodeName,ATTACHED:.status.attached' | grep -F '<PV_NAME>'
kubectl -n '<NAMESPACE>' get pod '<POD_NAME>'
kubectl -n '<NAMESPACE>' get events --field-selector involvedObject.kind=Pod,involvedObject.name='<POD_NAME>' --sort-by=.lastTimestamp预期输出
<VOLUMEATTACHMENT_NAME> <PV_NAME> <NODE_NAME> true
NAME READY STATUS RESTARTS
<POD_NAME> 1/1 Running <VALUE>
<TIME> Normal SuccessfulAttachVolume ... AttachVolume.Attach succeeded for volume "<PV_NAME>"事件名称和文案可能因版本或驱动不同而变化;最终标准是 VolumeAttachment 与后端附加状态一致,Pod 不再产生新的 Attach 错误,并能继续进入挂载和容器启动阶段。