《Kubernetes 分布式系统原理深入解析》12.2 写确认与实际生效的差距

一次写返回 ack 只代表 spec 已持久化,控制器是否观察到(observedGeneration 追平)与副本是否就绪是两码事。本节剖析 apiserver 持久化确认、控制器生效、数据平面收敛三个层次,并用 readpath 包的 WriteAck 验证 Acked/EffectApplied/FullyReconciled 三态。

12.2 写确认与实际生效的差距

第 12.1 节讲了读路径,本节讲写路径最容易误判的一环:「写成功」不等于「写生效」。kubectl apply 返回成功、apiserver 给出一个 resourceVersion,这只说明 spec 被 etcd 持久化了;控制器有没有看到它、副本有没有变成它,是两件完全独立的事。本节把「一次写从确认到生效」拆成三个层次,用 Acked / EffectApplied / FullyReconciled 三个判定刻画它们,并回答「什么时候可以说一个对象真正收敛到了目标」。

一次写要过四道关

从用户敲下命令到集群真正变成目标状态,一次写要依次跨过四道关:

关卡谁完成标志对应判定
持久化确认apiserver返回的 resourceVersion > 0Acked
控制器观察到控制器status.observedGeneration 追上 metadata.generationEffectApplied
副本被调度拉起scheduler/kubeletPod 被创建并运行—
副本就绪收敛kubelet/控制器就绪副本数 = 期望副本数FullyReconciled

这四道关常常被混为一谈,但它们的时间差可以很大:第一关是毫秒级(apiserver 落库),第二关取决于控制器调谐周期(秒级),第四关取决于镜像拉取、启动、健康检查(数十秒到分钟级)。「写确认」只保证第一关过了,后面三关都还是未知数。

Ack:持久化 ≠ 生效

WriteAck.AckRV 是 apiserver 写返回的 resourceVersion。lab 的 Acked() 判定就是 AckRV > 0——有 RV 即代表这次写被 etcd 的多数派持久化,且排序在历史写之后。这是「写确认」的准确含义:

func (w *WriteAck) Acked() bool { return w.AckRV > 0 }

注意 ack 说的是「spec 落库了」,不是「集群变成那样了」。一个 Deployment 把 replicas 从 2 改成 10,apiserver 立刻确认这次写——但此刻集群里仍然只有 2 个副本。ack 的语义边界是「写被接受并持久化」,越过这条线就是自欺欺人。 这也是 12.1 节 Fresh 判定的配对:ack 给你 writtenRV,用它去读能确认「写可见」,但「可见」不等于「已执行」。

observedGeneration:控制器「看到」的版本

控制器怎么证明「我看到了这次写」?Kubernetes 用 metadata.generation 与 status.observedGeneration 一对字段记账:

  • metadata.generation:每次 spec 被修改就 +1(第 12.3 节细讲),是「期望版本」的计数器。
  • status.observedGeneration:控制器最近一次调谐时处理到的 generation,是「已看到版本」的记录。

lab 的 EffectApplied() 判定正是这两者的比较:

func (w *WriteAck) EffectApplied() bool { return w.ObservedGen >= w.DesiredGen }

ObservedGen >= DesiredGen 意味着「控制器已经处理过这次写所对应的 spec」。但这里有个容易忽略的细节:observedGeneration 追上 generation,只说明控制器「读到了」新 spec,不保证它把集群推到了目标。控制器读完 spec 后发现还要等调度、等镜像,它照样把 observedGeneration 对齐——因为「观察」与「执行完成」是两件事。这正是为什么需要第三层判定。

副本就绪:数据平面收敛

ReadyReplicas >= DesiredReplicas 是第三层判定——数据平面真正收敛。它不再问「spec 被看到了吗」,而是问「实际运行的副本数到了吗」。lab 把它并进 FullyReconciled:

func (w *WriteAck) FullyReconciled() bool {
    return w.EffectApplied() && w.ReadyReplicas >= w.DesiredReplicas
}

FullyReconciled 是三个条件同时成立:ack 已给出、控制器已观察到、就绪副本已达标。用状态矩阵看三态的关系:

AckedEffectAppliedFullyReconciled含义
是是是完全收敛,可以放心
是是否spec 看到了,副本还在滚动
是否否控制器还没开始处理
否否否写都没成功

这个矩阵揭示了最重要的工程判断:FullyReconciled 是唯一值得信任的「完成」标志,Acked 与 EffectApplied 都只是中间状态。发布系统、自动化测试如果以「写返回成功」判定完成,会把仍在滚动的 Deployment 当成已上线。

三态切换:用 lab 的 Observe 走一遍

lab 的 Observe() 模拟控制器完成一次调谐——把 ObservedGen 对齐到 DesiredGen。跟着 TestWriteAckVersusEffect 走一遍三态切换:

步骤AckedEffectAppliedFullyReconciled
初始:AckRV=42、DesiredGen=3、ObservedGen=2、Ready=1/3是否否
调 Observe() 后是是否
就绪副本拉到 3是是是

每一步都有独立意义:第一行是「写已持久化但控制器还没处理」,第二行是「控制器看到 spec 但副本还没拉起」,第三行才是「全部收敛」。三态之间没有捷径——你不能跳过 EffectApplied 直接得到 FullyReconciled,因为副本就绪的前提是控制器把新 spec 付诸执行。

副本就绪 ≠ 控制器已处理:反向陷阱

TestWriteAckDoesNotImplyRollout 展示的是三态矩阵里最容易被忽略的一格:副本就绪了,但 observedGeneration 还没追上。场景:DesiredGen=1, ObservedGen=0, DesiredReplicas=3, ReadyReplicas=3——3 个副本都 Ready,但控制器还停在 generation 0。

这怎么可能?旧 spec 的副本本来就是 3 个就绪的,新 spec(generation 1)写进来后,控制器还没来得及调谐,ReadyReplicas 依然是 3——它统计的是「当前运行的副本」,不是「新 spec 对应的副本」。就绪副本数是现状的测量,generation 是期望的记账,两者的比较必须在控制器调谐之后才有意义。所以 FullyReconciled 坚持两个条件都要满足——任何一个为否,都不能宣布收敛。

这个陷阱在「只加副本数」的发布里特别隐蔽:replicas 2→3,新 Pod 还没建,readyReplicas 就已是 2 等于旧 spec 的期望,若拿「当前就绪副本 ≥ 旧期望」当完成判据,就会误判。判断完成必须用「新 spec 的期望」去比「当前就绪副本」,这正是 FullyReconciled 把 EffectApplied 作为前置条件的理由。

用 kubectl 观察差距

这些层次在命令行里都能看到。以一个 Deployment 为例:

kubectl get deployment web -o jsonpath='{.metadata.generation}{"\t"}{.status.observedGeneration}{"\t"}{.status.readyReplicas}{"\t"}{.spec.replicas}{"\n"}'

四个值依次是 generation / observedGeneration / readyReplicas / spec.replicas。判断规则:

观察结果判断
observed < generation控制器还没处理新 spec,滚动未开始
observed = generation 且 ready < spec正在滚动,未收敛
observed = generation 且 ready = spec完全收敛

假设输出是 4 3 3 5:generation 4、observed 3,说明控制器还在处理一次旧调谐(或还没轮到新 spec);ready 3、spec 5,说明副本还在拉起。再等几秒重跑,若变成 4 4 5 5,三态齐备、发布收敛。一次输出无法判断趋势,两次输出之间的变化才是状态机推进的证据——这是把三态判定用进脚本时的基本姿势。

这条命令是发布验收的最实用工具:别问「apply 成功了吗」,问「generation 对齐了吗、就绪副本到了吗」。两个数字都对齐,发布才算真的完成。

时序:从 ack 到收敛要多久

三态之间的时间差不是随机的,它由几个可估算的环节组成。以一个 replicas 3→5 的发布为例:

环节耗时量级说明
apiserver 落库返回 ack毫秒一次 etcd 提交
控制器感知并调谐秒取决于调谐周期与队列延迟
新副本被调度毫秒~秒scheduler 绑定 Pod 到节点
镜像拉取 + 容器启动数秒~分钟镜像在本地则快,冷拉则慢
健康检查通过、标记就绪数秒readinessProbe 周期 × 通过次数

把这几段相加,就得到「写确认到完全收敛」的预期时长。给发布脚本设超时时,按这几段之和再留余量,而不是拍一个固定秒数。这也是为什么 FullyReconciled 判定必须容忍异步——收敛是一个有界但不可精确预测的过程,过早判完成会误报,过晚判完成会拖慢发布。

时序还有一个派生结论:「写确认到生效的差距」本质是「异步控制循环的延迟」。Kubernetes 把「接受写」与「执行写」解耦,用控制器在两者之间兜底——这个解耦是它能承受高频写的前提,代价就是本节讲的:你不能从 ack 推断生效。

写确认的工程清单

检查项说明
发布脚本以 FullyReconciled 判完成以 ack 判完成会把未收敛当已上线
等待 observedGeneration 追上 generation没追上 = 控制器还没看
再等就绪副本达到期望没达到 = 数据平面没收敛
超时设置要覆盖滚动时长镜像拉取 + 启动 + 健康检查的总和
失败时回滚到上一 generation回滚也是写,同样要等收敛

最后一条提醒:回滚也是一次写。回滚到旧 spec,generation 会再加 1,observedGeneration 又要重新追。任何状态的变更都要过同一套收敛判定,回滚没有豁免。

三个常见误解

  • 「apiserver 返回成功就是写生效了,集群已经变成那样」——错误。返回成功只代表 spec 被持久化(Acked),控制器是否观察到、副本是否就绪完全是另两回事。
  • 「observedGeneration 追上了 generation 就等于发布完成」——错误。那只说明控制器读到了新 spec(EffectApplied),副本可能还在滚动,必须等 FullyReconciled。
  • 「就绪副本数等于期望副本数就是收敛了」——错误。就绪副本数是现状测量,新 spec 可能还没被控制器处理;只有 observedGeneration 与就绪副本双达标才算收敛。

一句话总结本节

一次写从确认到生效要依次跨过持久化(Acked)、控制器观察到(EffectApplied)、副本就绪(FullyReconciled)三关,三关的时间差可达分钟级。「写成功」只承诺第一关;判断发布完成,必须看到第三关。

下一节把生成器的两个字段讲透:resourceVersion 与 generation/observedGeneration 各自怎么判断「最新」。

本节 lab

本节的两个测试落在 readpath 包的 WriteAck 上,验证「ack 与生效的差距、完全收敛的三态」。WriteAck 把四道关里的三关压缩成三个判定函数,测试跑的就是这三个判定在不同状态下各自为真还是为假:

cd private/labs/k8s-net-lab
go test ./readpath -run TestWriteAckVersusEffect -v
go test ./readpath -run TestWriteAckDoesNotImplyRollout -v
  • TestWriteAckVersusEffect:AckRV=42、DesiredGen=3、ObservedGen=2、DesiredReplicas=3、ReadyReplicas=1,断言 Acked() 为真、EffectApplied() 与 FullyReconciled() 为假;调 Observe() 后断言 EffectApplied() 为真、FullyReconciled() 仍为假;把 ReadyReplicas 拉到 3 后断言 FullyReconciled() 为真——共 7 条断言,覆盖「持久化 ack ≠ 生效、观察 ≠ 就绪、双达标才收敛」。
  • TestWriteAckDoesNotImplyRollout:AckRV=50、DesiredGen=1、ObservedGen=0、ReadyReplicas=3/3,断言 EffectApplied() 与 FullyReconciled() 都为假——2 条断言,对应「副本就绪不代表控制器已处理新 spec」。

两个测试合起来画出了完整的判定图谱:ack 通过不意味着生效,生效不意味着就绪,就绪也不意味着收敛——四个条件环环相扣,缺一不可。

两个测试跑完见 ok k8s-net-lab/readpath。这就是「ack / 观察 / 收敛」三态写确认的最小闭环。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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