12.2 写确认与实际生效的差距
第 12.1 节讲了读路径,本节讲写路径最容易误判的一环:「写成功」不等于「写生效」。kubectl apply 返回成功、apiserver 给出一个 resourceVersion,这只说明 spec 被 etcd 持久化了;控制器有没有看到它、副本有没有变成它,是两件完全独立的事。本节把「一次写从确认到生效」拆成三个层次,用 Acked / EffectApplied / FullyReconciled 三个判定刻画它们,并回答「什么时候可以说一个对象真正收敛到了目标」。
一次写要过四道关
从用户敲下命令到集群真正变成目标状态,一次写要依次跨过四道关:
| 关卡 | 谁完成 | 标志 | 对应判定 |
|---|---|---|---|
| 持久化确认 | apiserver | 返回的 resourceVersion > 0 | Acked |
| 控制器观察到 | 控制器 | status.observedGeneration 追上 metadata.generation | EffectApplied |
| 副本被调度拉起 | scheduler/kubelet | Pod 被创建并运行 | — |
| 副本就绪收敛 | 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 已给出、控制器已观察到、就绪副本已达标。用状态矩阵看三态的关系:
| Acked | EffectApplied | FullyReconciled | 含义 |
|---|---|---|---|
| 是 | 是 | 是 | 完全收敛,可以放心 |
| 是 | 是 | 否 | spec 看到了,副本还在滚动 |
| 是 | 否 | 否 | 控制器还没开始处理 |
| 否 | 否 | 否 | 写都没成功 |
这个矩阵揭示了最重要的工程判断:FullyReconciled 是唯一值得信任的「完成」标志,Acked 与 EffectApplied 都只是中间状态。发布系统、自动化测试如果以「写返回成功」判定完成,会把仍在滚动的 Deployment 当成已上线。
三态切换:用 lab 的 Observe 走一遍
lab 的 Observe() 模拟控制器完成一次调谐——把 ObservedGen 对齐到 DesiredGen。跟着 TestWriteAckVersusEffect 走一遍三态切换:
| 步骤 | Acked | EffectApplied | FullyReconciled |
|---|---|---|---|
| 初始: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 / 观察 / 收敛」三态写确认的最小闭环。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。