K8s CSI 驱动排障：驱动注册、Attach/Detach 异常、Multi-Attach 多挂载

CSI（Container Storage Interface） 是 K8s 对接外部存储的标准接口。理解它的组件分工，才能在”卷挂不上、卸不下、被多挂”时快速定位是哪一端的问题。

一、CSI 的组件拓扑

一个 CSI 驱动通常由两类 Pod 组成（部署在 kube-system）：

• Controller 插件（StatefulSet/Deployment，通常 1 副本）：
  • external-provisioner：处理动态供给（CreateVolume）；
  • external-attacher：处理卷的 Attach/Detach（调 ControllerPublishVolume）；
  • external-resizer：处理扩容；
  • external-snapshotter：处理快照。
• Node 插件（DaemonSet，每节点一个）：
  • node-plugin：真正在节点上把卷挂载进 Pod 的目录（NodeStageVolume / NodePublishVolume）。

二、常见排障场景

1. 卷无法 Attach / Detach（Multi-Attach error）

Multi-Attach error for volume "xxx" - Volume is already used by pod(s) ...

ReadWriteOnce（RWO）卷同一时刻只能挂在一个节点。常见于：旧 Pod 没完全停掉（还占着卷），新 Pod 调度到另一节点就会报这个错。

• 确认旧 Pod 已彻底删除；
• 极端情况：底层卷的 attach 状态残留，需在云控制台/存储端手动 detach，或重启 external-attacher 重做状态同步。

2. 卷挂载超时（Node 插件问题）

Node 插件没起来或 kubelet 没注册该 CSI 驱动，会导致 MountVolume.SetUp failed。

# kubelet 是否识别到驱动
ls /var/lib/kubelet/plugins/   # 应有 <driver-name>-reg.sock 或对应目录
kubectl get pods -n kube-system -l app=<csi-node>

3. 驱动注册失败 / Socket 缺失

CSI 驱动通过 kubelet 的插件目录下的 socket 文件 注册。若该文件缺失，kubelet 认为驱动不可用，所有依赖它的 PVC 都会失败。检查：

• CSIDriver 对象是否存在：kubectl get csidriver；
• node 插件是否把 socket 挂到了正确的 plugin 目录。

4. 扩容/快照”没反应”

确认对应的 sidecar（external-resizer / external-snapshotter）Pod 是否运行，且 StorageClass 开启了相应能力（allowVolumeExpansion / volumeSnapshotClassName）。

三、排障总览表

现象	优先查的组件
PVC Pending（供给失败）	external-provisioner 日志
调度失败 Multi-Attach	旧 Pod 是否残留 / external-attacher
挂载超时 FailedMount	node-plugin / kubelet 插件 socket
扩容不生效	external-resizer / StorageClass 开关

小结

CSI 排障关键是分端：供给看 provisioner，挂载看 node-plugin 与 kubelet 插件注册，Attach/Detach 看 attacher。RWO 卷的 Multi-Attach 错误几乎都源于旧 Pod 未彻底退出。