longhorn volume 附件失败显示 “failed to attach volume” 的几种根因

Longhorn Volume附件失败的常见原因包括：节点未就绪或缺少Longhorn组件；iSCSI或Multipath配置冲突；Volume处于不支持attach的状态；CSI Driver或kubernetes VolumeAttachment资源异常。

ailed to attach volume”，通常不是单一原因导致，而是涉及节点状态、存储后端、Kubernetes 资源调度或 Longhorn 自身组件协同等多个环节。以下是最常见且可验证的几类根因及对应排查方向：

节点未就绪或缺少 Longhorn 组件

Volume 无法 attach 的首要前提是目标节点必须满足 Longhorn 运行条件：

• 节点需处于 Ready 状态（kubectl get node 检查），且未被污点（taint）阻断调度；
• 该节点上必须运行 longhorn-manager 和 longhorn-engine（即 longhorn-csi-plugin 和 instance-manager-e）Pod；
• 若节点是新加入集群或重启过，检查 instance-manager-e-xxx 是否已成功启动（kubectl -n longhorn-system get pod -o wide | grep instance-manager-e）；
• 节点上 /var/lib/longhorn/ 目录需可写，SElinux 或磁盘配额限制可能导致 instance-manager 初始化失败。

iSCSI 或 Multipath 配置冲突

Longhorn 默认通过 iSCSI 将 volume attach 到节点，若底层存在干扰，attach 流程会卡在连接阶段：

• 节点上已存在其他 iSCSI initiator（如 open-iscsi 手动登录了其他 target），可能抢占 session 或占用端口；
• 系统启用了 multipathd 服务，它会自动接管 iSCSI 设备并重命名设备路径（如从 /dev/sdb 变为 /dev/mapper/mpatha），导致 Longhorn 无法识别原始块设备；
• 解决方法：在 Longhorn 节点上禁用 multipath（systemctl stop multipathd && systemctl disable multipathd），或确保 /etc/multipath.conf 中排除 Longhorn 使用的 IQN（如设置 blacklist { wwid "*longhorn*" }）。

Volume 处于不支持 attach 的状态

并非所有 volume 状态都允许 attach，尤其在异常操作后容易残留不可用状态：

• volume 当前状态为 detached 是正常前提，但若显示 attaching 卡住超过 2 分钟，大概率是 engine 启动失败或 replica 同步中断；
• volume 的 frontend 设置为 blockdev（默认）时，要求节点有可用的空闲块设备名（如 /dev/sdb），若该设备名已被占用或内核未识别，attach 会静默失败；
• replica 数量不足（例如设置 replica=3，但只有 2 个 healthy replica），Longhorn 默认拒绝 attach（除非开启 allow-recurring-job-while-volume-detached 且 volume 处于 degraded 状态）；
• 检查 volume 详情页中的 Conditions 字段，重点关注 Scheduled、RestoreRequired、Robustness 是否为 healthy。

CSI Driver 或 Kubernetes VolumeAttachment 资源异常

Attach 行为由 CSI driver 触发，并依赖 Kubernetes 的 VolumeAttachment 对象协调，任一环节断裂都会报错：

• 确认 longhorn-csi-plugin Pod 在目标节点上运行正常，且其日志中无 NodeStageVolume 或 NodePublishVolume 报错；
• 执行 kubectl get volumeattachment，查找对应 volume 的 attachment 记录，观察 attached 字段是否为 false，attacher 是否为 driver.longhorn.io；
• 若 VolumeAttachment 存在但 status.attached=false，说明 CSI driver 明确拒绝了请求，此时应查看 csi-plugin 日志（kubectl -n longhorn-system logs -l app=longhorn-csi-plugin）；
• Kubernetes kubelet 若配置了 --feature-gates=CSIMigration=false（旧版本默认），而 Longhorn v1.4+ 要求启用 CSI migration 支持，也可能导致 attach 被忽略。