《Kubernetes 分布式系统原理深入解析》7.2 attach/detach 的分布式协调

块卷的 attach/detach 是一道分布式协调题:单写者独占要求同一卷不能同时 attach 到两个节点,detach 必须以 umount 为前提,节点漂移与超时重试则是协调器要啃的硬骨头。本节拆解这套状态机。lab 用 csi 包验证独占 attach 与「先卸载后 detach」两条规则。

7.2 attach/detach 的分布式协调

7.1 节给了 CSI 的接口契约,但「同一时刻只有一个节点能用这块云盘」这个不变量,不是接口能保证的——它需要分布式协调。块卷的 attach/detach 本质是一个多节点争抢单个资源的问题:谁 attach 了卷,别人就得让;谁要 detach,必须确认没有人在用。

本节拆解这套协调的三个硬约束:单写者独占、detach 必须先 umount、漂移与超时重试。

单写者独占:attach 是排他的

块存储的 ControllerPublishVolume 语义是排他的——卷 attach 到节点 A 后,节点 B 再 attach 必须失败。lab 的 Controller.Attach 用一行断言实现这套逻辑:

if cur, ok := c.Attached[volID]; ok && cur != nodeID {
    return false // 已被其他节点占用
}

这不是保守,而是块卷的物理现实:云盘底层是单写者存储(第 6.3 节),两个节点同时挂载并写入,文件系统会被两个互不可见的写入者撕裂。attach 排他 + 访问模式 RWO,是「单写者」在 K8s 里的双重落实——一个在卷级,一个在声明级。

真实集群里 attach 的协调由 csi-attacher 完成:它维护 VolumeAttachment 对象,把「卷 → 节点」的期望状态持久化在 API 服务器,再调用 CSI 把期望变成现实。期望状态在 etcd,现实状态在插件——二者以对象状态收敛。

VolumeAttachment:期望状态长什么样

VolumeAttachment 是 attach 协调的持久化载体,它的形态值得一看:

apiVersion: storage.k8s.io/v1
kind: VolumeAttachment
metadata:
  name: csi-74e1b9d1b8a48bdb01
spec:
  nodeName: node-01
  source:
    persistentVolumeName: pv-ebs-01
  attacher: ebs.csi.aws.com
status:
  attached: true
  attachmentMetadata:
    devicePath: /dev/nvme1n1

spec 是期望(卷该 attach 到 node-01),status.attached 是现实(云厂商确认 attach 完成)。协调器的循环是:读期望 → 调 CSI → 写现实 → 再读期望。nodeName 与 source.persistentVolumeName 两个字段合在一起,就是「谁在用哪块卷」的权威答案——单写者独占正是靠这个对象的唯一性实现的。

detach 的硬前提:必须先 umount

detach 不是「把 attach 记录删掉」那么简单。协调器必须确认:卷已经不被任何容器使用,才允许与节点解绑。 lab 的 Detach 直接编码了这条规则:

if _, mounted := n.Mounted[volID]; mounted {
    return false // 还挂着卷,不许 detach
}

反例是灾难性的:卷还挂在容器的路径上就直接 detach,kubelet 可能在 detach 完成前的瞬间继续写盘——写进一个已经不属于本节点的卷,数据丢失且无感知。所以规范强制 detach 的时序是:

  1. Pod 删除,kubelet 执行 NodeUnpublishVolume(卸载)。
  2. 确认节点上没有任何挂载残留。
  3. 才允许 csi-attacher 执行 ControllerUnpublishVolume(detach)。

lab 的 TestDetachRequiresUnmount 走的就是这条链:先断言「挂着卷时 Detach 返回 false」,再卸载,再断言「卸载后 Detach 返回 true」。先卸载、后 detach,是卷安全释放的不可违反顺序。

失败模式对照:每一步都可能坏

协调不是线性成功,每一步都可能坏。把整条链路的失败模式摊开:

阶段失败形态现象协调器反应
attach云 API 超时VolumeAttachment 卡在 pending幂等重试
attach后端不支持返回能力错误快速失败并报错
mount挂载点冲突Pod 卡 ContainerCreatingkubelet 重试
umount有进程占用卸载失败等占用进程退出后重试
detach节点失联detach 挂起等节点恢复或强制隔离
detach卸载残留detach 返回 false先补卸载再重试

每一行的共同点是「重试而不是放弃」:协调器把失败当作需要收敛的中间态,而不是终态。唯一不可重试的,是违反不变量(比如在挂载残留时强行 detach)——那需要人工介入。

漂移(migration):卷从一个节点搬到另一个

有状态 Pod 被驱逐或重新调度后,卷要跟着 Pod「漂移」——但这在块存储上是受限的:

漂移步骤动作失败点
旧节点detach(先卸载)节点失联时 detach 卡死
新节点attach跨可用区 attach 失败(6.2 节)
新节点mount挂载点冲突或文件系统未清理

漂移的正确姿势是「先旧后新」:只有旧节点完成 detach,新节点才能 attach——这是单写者语义在漂移中的延续。漂移不是并行切换,而是串行交接,交接窗口里卷处于「无人持有」的中间态,这既是安全窗口,也是不可用窗口。

一个节点驱逐场景走查

把漂移走一遍完整的场景:节点 node-02 要维护,管理员执行 kubectl drain node-02。

步骤发生的事状态
1kubelet 收到驱逐,Pod 进入终止Pod Terminating
2kubelet 执行 NodeUnpublishVolume卷从容器路径卸载
3Pod 删除,PVC 仍保留(6.2 节)PVC Bound 不动
4csi-attacher 对 node-02 执行 detach卷与 node-02 解绑
5调度器把 Pod 放到 node-01Pod Pending → 新节点
6csi-attacher 在 node-01 执行 attach卷在新节点就位
7新 kubelet 执行 mountPod Running

注意第 3 步与第 5 步之间,卷是「无主」的——这正是串行交接的窗口。若第 4 步因为 node-02 失联而卡住,整个队列停在第 5 步,直到节点恢复或管理员强制隔离。drain 一个挂块卷的节点,排障时第一看 detach 有没有完成。

超时重试:协调器把期望状态熬成现实

分布式协调的日常不是「一次成功」,而是「反复重试直到收敛」。attach/detach 的每个步骤都可能失败:云 API 超时、插件崩溃、节点假死。协调器应对失败的方式是幂等重试:

场景协调器行为收敛目标
attach 超时重试 ControllerPublishVolume(幂等)VolumeAttachment 状态变为 Attached
detach 超时重试 ControllerUnpublishVolume卷从节点解绑,Attachment 消失
节点失联标记 NodeNotReady,detach 挂起等节点恢复或强制隔离

关键设计是操作幂等:ControllerPublishVolume 重复调用不会产生副作用,重试多少次都安全。配合期望状态对象,协调器永远「向期望收敛」而不是「追着瞬态跑」——即使卷的中间状态乱成一团,最终也会被重试推进到期望。

协调器的高可用:谁在跑 attach

attach/detach 协调器不是单点:它作为控制面组件,自身也要高可用。两种形态各有取舍:

形态运行位置选举
内置 controller(attach/detach controller)控制面随 API server 高可用
独立 csi-attacherDeployment 多副本Leader 选举,同一时刻一个 active

VolumeAttachment 对象的唯一性保证无论哪个协调器副本在跑,都不会出现「两个协调器同时 attach 同一卷」——对象级锁先于操作级锁。协调器本身是可替换的,不变量由对象与协议承载,不挂在某个进程身上。这也是为什么卷协调比「在代码里加锁」更可靠:进程会崩,锁会丢,但对象状态一直在 etcd 里等着收敛。

状态机小结:从 Pod 调度到卷就位

把 7.1 的时序与本节约束拼起来,得到完整状态机:

阶段协调者关键不变量
Pod 调度到节点调度器卷拓扑(可用区)与节点匹配
attach 请求csi-attacher卷未被其他节点独占
attach 执行Controller 插件成功或幂等重试
mountNode 插件stage/publish 顺序执行
umountNode 插件卷不再被容器使用
detachcsi-attacher节点已无挂载残留
卷释放Controller 插件未 attach 才能 DeleteVolume

每一行的不变量都是下一行的前提。lab 的 Attach/Detach/Publish/Unpublish 四个方法就是这个状态机的原子件——它们单独正确,拼起来才成闭环。

三个常见误解

  • 「detach 就是把 VolumeAttachment 对象删掉,操作很快」——错误。detach 必须等 umount 完成后才能执行,卸载残留会让 detach 失败或拒绝;删对象只是删期望,现实要另算。
  • 「同一个卷可以同时 attach 到两个节点,反正 CSI 支持多 attach」——错误。CSI 多 attach 只存在于支持多写者的后端;块卷的 attach 排他由协调器强制,双 attach 会撕裂数据。
  • 「节点失联了,detach 会立刻超时并自动完成」——错误。节点失联时 detach 往往挂起,等节点恢复或强制隔离;超时重试保证的是收敛方向,不是时间保证。

一句话总结本节

attach/detach 的分布式协调围绕三个不变量展开:attach 排他守住单写者,detach 以 umount 为前提守住安全释放,幂等重试把期望状态熬成现实。卷的每次移动都是串行交接,不是并行切换——这正是块存储一致性的代价与承诺。

下一节给存储画上句点:快照、克隆与一致性组。快照要求卷已 attach,克隆从快照派生,一致性组坚持 all-or-nothing。

本节 lab

本节用 csi 包的两个测试验证「独占 attach」与「先卸载后 detach」两条协调规则:

cd private/labs/k8s-net-lab
go test ./csi -run TestAttachExclusiveSingleWriter -v
go test ./csi -run TestDetachRequiresUnmount -v
  • TestAttachExclusiveSingleWriter:断言首次 Attach("vol-1", "node-a") 成功,再断言 Attach("vol-1", "node-b") 失败——2 个断言,对应「单写者独占,不变量由协调器强制」。
  • TestDetachRequiresUnmount:卷挂着时断言 Detach 返回 false;Unpublish 断言卸载成功;卸载后断言 Detach 返回 true——3 个断言,对应「先卸载、后 detach 的不可违反顺序」。

两个测试共 5 个断言,跑完见 ok k8s-net-lab/csi。这套「独占 + 顺序」的协调语义,是块卷在分布式环境里安全的全部秘密。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图