CSI横陈系列挂载失败常见原因？

Question

CSI（Container Storage Interface）在使用“横陈系列”存储后端时，挂载失败的常见原因之一是节点侧未正确安装或配置存储插件客户端。例如，缺少必要的NFS或iSCSI工具包、多路径服务未启动，或kubelet未启用CSI相关特性门控。此外，存储后端IP不可达、LUN未正确映射至目标节点、CHAP认证信息错误等也会导致卷挂载失败。需检查NodePlugin日志、系统dmesg及multipath状态以定位具体问题。

Answer 1

1. CSI挂载失败的常见现象与初步排查路径

当使用“横陈系列”存储后端时，Kubernetes集群中的Pod在尝试挂载CSI卷时可能出现VolumeBindingFailed、MountVolume.SetUp failed或rpc error: code = Internal desc = mount failed等错误。这些现象通常指向节点侧（NodePlugin）的问题。

初步排查应从以下方向入手：

• 检查Pod事件日志：kubectl describe pod <pod-name>
• 查看对应CSI Node Plugin的容器日志（通常位于kube-system命名空间）
• 确认目标节点是否具备访问存储后端网络的能力
• 验证kubelet是否启用了CSI相关特性门控

2. 节点侧客户端配置缺失：基础组件依赖分析

CNI插件仅负责网络，而CSI插件在执行挂载操作时依赖底层操作系统提供的存储协议支持。若节点未安装必要的工具包，挂载流程将在准备阶段中断。

组件类型	所需软件包	作用说明
NFS	nfs-utils, rpcbind	用于NFS共享目录的挂载和RPC通信
iSCSI	iscsi-initiator-utils, open-iscsi	发起iSCSI会话，发现并登录目标LUN
多路径	device-mapper-multipath, multipath-tools	实现链路冗余与I/O负载均衡
文件系统工具	xfsprogs, e2fsprogs	格式化与检查ext4/xfs文件系统

3. kubelet特性门控与CSI运行时支持

Kubernetes默认可能未启用某些CSI关键特性，尤其是在较旧版本中。必须确保以下特性门控已开启：

KUBELET_FEATURE_GATES="CSINodeInfo=true,CSIDriverRegistry=true,CSIVolumeHealth=true,KubeletPluginsWatcher=true"

该配置需在kubelet启动参数中显式声明。若未启用CSINodeInfo，Controller会认为节点不支持CSI；若KubeletPluginsWatcher关闭，则无法自动注册NodePlugin。

可通过如下命令验证当前节点状态：

kubectl get nodes -o jsonpath='{.items[*].status.conditions[?(@.type=="CSIStorageCapacity")]}'
kubectl get csinodes <node-name> -o yaml

4. 存储后端可达性与LUN映射验证流程

即使节点配置完整，若存储阵列未正确导出资源，挂载仍会失败。以下是系统化的验证流程图：

graph TD A[开始诊断] --> B{存储IP是否可达?} B -- 否 --> C[检查防火墙/路由/NIC绑定] B -- 是 --> D{iSCSI Target能否发现?} D -- 否 --> E[验证iscsiadm discovery] D -- 是 --> F{LUN是否映射到该节点?} F -- 否 --> G[联系存储管理员配置ACL/LUN Masking] F -- 是 --> H{CHAP认证信息正确?} H -- 否 --> I[更新Secret中的username/password] H -- 是 --> J[继续检查multipath与udev规则]

5. CHAP认证与安全凭证管理

“横陈系列”存储常启用双向CHAP以增强安全性。若Kubernetes Secret中提供的用户名或密码错误，iSCSI登录将被拒绝。

典型错误日志片段：

iscsiadm: Could not login to [iface: default, target: iqn.2006-08.com.hengchen:storage.lun0, portal: 192.168.10.100,3260].
iscsiadm: reason: Login authentication failed
kernel: connection1:0: detected conn error (1020)

解决方案包括：

• 确认Secret中数据编码为base64
• 检查用户名是否包含域前缀（如iqn.2006-08.com.hengchen:initiator）
• 在节点上手动测试登录：iscsiadm -m node -T <iqn> -p <ip>:3260 --login

6. 多路径服务状态监控与故障恢复

企业级存储通常通过多个光纤通道或iSCSI路径连接，需依赖dm-multipath服务进行路径聚合。若服务未运行，可能导致设备识别不稳定。

常用诊断命令：

systemctl status multipathd
multipath -ll
lsblk | grep mpath

预期输出应显示类似：

mpatha (3600a0b8000c7b3f70000000000000000) dm-3 HENGCHE,NVMe Disk
size=100G features='1 queue_if_no_path' hwhandler='1 alua' wp=rw
|-+- policy='service-time 0' prio=50 status=active
| |- 2:0:0:0 sda 8:0  active ready running
|-+- policy='service-time 0' prio=10 status=enabled
  |- 3:0:0:0 sdb 8:16 active ready running

若无输出或多路径状态为failed，需重启服务并检查/etc/multipath.conf中是否包含厂商特定配置。

7. 日志交叉分析：NodePlugin、dmesg与系统日志联动

定位深层问题需结合三层日志：

1. CSI Node Plugin容器日志：反映gRPC调用上下文与插件逻辑错误
2. dmesg/kernel log：暴露SCSI命令超时、路径断开、设备拒绝等底层异常
3. /var/log/messages 或 journalctl：记录multipathd、iscsid等守护进程行为

示例关联场景：

NodePlugin日志: "failed to attach disk: rpc error"
dmesg: "connection1:0: ping timeout of 5 secs"
journalctl: "iscsid: login rejected with response 0x03: Login failure"

此组合表明CHAP失败导致内核层连接中断，进而引发插件调用崩溃。