容器与云原生 / 系统课时

排查 FailedMount 与挂载超时

排查 FailedMount 与挂载超时

卷已经 Attach,但 Pod 仍长期停在 ContainerCreating 并持续出现 FailedMount,说明故障大多已经进入节点侧挂载路径。本课从 Pod 事件出发,串联 kubelet、CSI Node Plugin、Stage/Publish、主机文件系统与网络依赖,建立一条可验证的排障证据链。

学习目标

  • 区分 Attach 未完成与 Attach 成功后的节点挂载故障
  • 根据事件和 Node Plugin 日志判断失败发生在 Stage、Publish、文件系统还是网络
  • 用最少的节点侧检查验证设备、挂载点与存储端连通性

从 Pod 事件确定挂载失败位置

先确认 Pod 已经调度到具体节点,再按时间顺序读取事件。若仍持续出现 FailedAttachVolume,应先回到 Attach 链路;若 Attach 已完成而主要错误变成 FailedMount,才进入本课的节点挂载路径。

bash
NS='default'
POD='<POD_NAME>'

kubectl -n "$NS" get pod "$POD" -o wide
kubectl -n "$NS" get events --field-selector involvedObject.kind=Pod,involvedObject.name="$POD" --sort-by=.lastTimestamp
kubectl -n "$NS" describe pod "$POD"

预期输出

text
NAME         READY   STATUS              NODE
<POD_NAME>   0/1     ContainerCreating   <NODE_NAME>

Warning  FailedMount  <TIME>  kubelet  MountVolume.SetUp failed for volume "<VOLUME_NAME>": <ERROR>

实际事件可能写成等待挂载超时、设备挂载失败或 CSI RPC 错误。此时先记录 Node 名、卷名、错误原文和时间点,后续所有日志与主机检查都围绕同一组证据查询,避免把不同 Pod 或不同重试轮次混在一起。

串起 kubelet 到 Node Plugin 的证据链

kubelet 通过节点上的 CSI Unix Socket 调用 Node Plugin。若驱动声明 STAGE_UNSTAGE_VOLUME 能力,常见路径是先执行 NodeStageVolume,将卷准备到节点级 staging 路径,再执行 NodePublishVolume,把卷发布到 Pod 的目标路径;未声明该能力的驱动可能直接调用 NodePublishVolume。

FailedMount 从 kubelet 到存储后端的节点侧排障层级

先把 Pod 对应的 PV、CSI Driver 与 Node 串起来,再检查该 Node 的 CSINode 是否注册了目标驱动,以及节点上是否运行着对应的 Node Plugin。

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}')"

printf 'PV=%s\nNODE=%s\nDRIVER=%s\n' "$PV" "$NODE" "$DRIVER"
kubectl get csinode "$NODE" -o custom-columns='DRIVER:.spec.drivers[*].name,NODE_ID:.spec.drivers[*].nodeID' | grep -F "$DRIVER"
kubectl get pods -A --field-selector spec.nodeName="$NODE" -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,CONTAINERS:.spec.containers[*].name' | grep -Ei 'csi|storage'

预期输出

text
PV=<PV_NAME>
NODE=<NODE_NAME>
DRIVER=<CSI_DRIVER>
<CSI_DRIVER>   <CSI_NODE_ID>
<CSI_NAMESPACE>   <CSI_NODE_POD>   <CONTAINER_LIST>

这里的 printf 必须按 PV、NODE、DRIVER 三个字段分别输出,三个 %s 与后三个参数一一对应。若其中任一值为空,应先修复对象关联关系,而不是继续向节点文件系统深入。

如果 CSINode 中找不到驱动,优先检查 node-driver-registrar、驱动 Socket 和 Node Plugin DaemonSet 的调度状态;此时继续研究文件系统没有意义。如果驱动已注册且 Node Plugin 正常,再进入 RPC 日志。

用日志区分 Stage 与 Publish

节点插件容器名由具体驱动决定。定位 Node Plugin Pod 后,查看故障时间附近的驱动日志,并把 volume_id、target path 和 gRPC 错误与 Pod 事件中的时间点对齐。

bash
CSI_NS='<CSI_NAMESPACE>'
NODE_POD='<CSI_NODE_POD>'
DRIVER_CONTAINER='<DRIVER_CONTAINER>'

kubectl -n "$CSI_NS" logs "$NODE_POD" -c "$DRIVER_CONTAINER" --since=10m

预期输出

text
<TIME> ... NodeStageVolume ... volume_id=<VOLUME_ID> ...
<TIME> ... rpc error: code = <GRPC_CODE> desc = <ERROR>

如果错误停在 NodeStageVolume,重点检查设备是否已经出现在节点、卷是否需要格式化、fsType 是否受支持、文件系统检查是否卡住,以及 staging 路径是否存在异常挂载。若 Stage 成功而 NodePublishVolume 失败,则重点检查 Pod target path、只读或读写能力、Secret、fsGroup 或权限,以及 bind mount 行为。

检查主机文件系统与网络依赖

块存储在 Node Plugin 已拿到设备后,仍可能被主机层阻塞,例如设备未出现、fsType 不匹配、文件系统损坏、设备忙或内核 I/O 错误。具有节点访问权限时,可先做只读检查;不要直接手工卸载 kubelet 管理的目录。

bash
sudo lsblk -f
sudo findmnt
sudo dmesg | tail -n 80

预期输出

text
NAME   FSTYPE   UUID   MOUNTPOINTS
<DEV>  <FSTYPE> <ID>   <PATH>
...
<DEVICE_OR_FILESYSTEM_MESSAGE>

实际设备名与挂载路径因驱动而异。若 dmesg 出现 I/O error、filesystem error 或设备反复消失,应优先处理主机或后端设备问题,而不是通过重启 Pod 掩盖症状。

网络存储则要把同一条链继续追到 DNS、路由、防火墙和服务端。NodeStageVolume 或 NodePublishVolume 返回 DeadlineExceeded 时,只有先确认节点到存储端的解析与端口可达,才能进一步判断是否是存储服务变慢。NFS、iSCSI、SMB 等协议还依赖各自的节点客户端工具与认证配置,应按实际驱动要求核对。

修复后验证挂载闭环

修复驱动注册、节点依赖、文件系统或网络问题后,重新观察同一 Pod。无需追求某条固定的成功日志,核心是新的 FailedMount 不再产生,卷完成 Publish,容器最终进入 Running。

bash
kubectl -n '<NAMESPACE>' get pod '<POD_NAME>' -w

预期输出

text
NAME         READY   STATUS              RESTARTS
<POD_NAME>   0/1     ContainerCreating   <VALUE>
<POD_NAME>   1/1     Running             <VALUE>

如果状态仍不前进,就以最新事件时间为起点重新回查 Node Plugin,而不是继续使用旧日志。一个可靠的结论必须同时解释:为什么 kubelet 当时挂载失败、修复改变了哪一层,以及修复后该层的错误为何不再出现。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查 FailedMount 与挂载超时

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

登录哪都通