容器与云原生 / 系统课时

排查 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 分别执行。

bash
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

预期输出

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

VolumeAttachment 从 Kubernetes 对象到后端卷的排障链路

用下面的命令把这些对象串起来。<...> 是需要替换的实际值。

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

预期输出

text
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,再查看同一时间窗口的日志。

bash
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

预期输出

text
<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 对象和事件链稳定恢复。

bash
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

预期输出

text
<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 错误,并能继续进入挂载和容器启动阶段。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查 VolumeAttachment 卡住

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

登录哪都通