《Kubernetes 分布式系统原理深入解析》12.3 resourceVersion/observedGeneration 判断「最新」

resourceVersion 是 apiserver 全局单调的写序号,watch 增量推进缓存只前进不后退;generation 每次 spec 写入 +1,observedGeneration 由控制器追平,追平才算最新。本节剖析三种版本号各自的语义与判据,并用 readpath 包的 ReadPath/Object 验证 watch 增量推进、generation 对齐与过期判定。

12.3 resourceVersion/observedGeneration 判断「最新」

第 12.1 节与 12.2 节都用到了版本号,但没有正面回答一个问题:Kubernetes 里有好几种「版本」,各自表达什么「最新」? metadata.resourceVersion、metadata.generation、status.observedGeneration 名字都带「版本」色彩,语义却完全不同。本节把它们逐一拆开,讲清三者的推进规则、判定判据,以及为什么「generation 追平」才是控制器意义上真正的「最新」。

三种版本号的分工

先把三个字段摆在同一条线上,看各自记录什么:

字段谁在递增递增条件回答的问题
resourceVersionapiserver任何一次写(包括 status 更新)「这个对象的最新一次写入序号」
generationapiserver仅 spec 变更「期望状态改了多少次」
observedGeneration控制器控制器完成一次调谐「控制器已经处理到哪个 spec 版本」

注意三者的关键差异:resourceVersion 任何写都递增——包括控制器自己写 status;generation 只对 spec 变更递增——status 更新不改变 generation;observedGeneration 是控制器写给 status 的记账。一个对象被控制器频繁更新 status 时,resourceVersion 会飞快增长而 generation 不动——这正说明「RV 大」不代表「spec 新」。

resourceVersion:apiserver 全局单调的写序号

resourceVersion 是 apiserver 的全局 revision:每次对象被创建/更新/删除,它都取一个比所有先前写更大的值。它的语义是**「这个写在整个存储里的序号」**,而不是「这个对象被改了多少次」。同一对象连改三次 status,RV 涨三次;别的对象写一次,RV 也涨一次——RV 是集群级的,不是对象级的。

RV 的两个关键性质,第 12.1 节已经用过:

  • 全局单调:大 RV 必然比小 RV 新,跨对象可比。
  • 可作读判据:seenRV >= writtenRV 判定读到的状态是否包含某次写。

但 RV 不能回答「控制器处理到哪了」——它是存储层的写序号,控制器是否消费了它,RV 一无所知。这正是需要 generation 与 observedGeneration 的原因:RV 告诉你「写发生了」,后两个告诉你「写被处理了」。

watch 增量推进:缓存如何追着 RV 走

第 12.1 节讲了 watch 推进缓存的机制,这里补上它与「判断最新」的关系。客户端缓存靠 watch 事件流推进 RV,lab 的 ApplyWatch 是这条推进的最小实现:

func (p *ReadPath) ApplyWatch(rv int64) {
    if rv > p.ClientRV {
        p.ClientRV = rv
    }
}

只前进不后退是这个函数唯一的正确性保证:watch 重连可能重放旧事件,若允许倒退,缓存会回到旧版本,Fresh 判定就失效了。TestWatchIncrementalSync 演示了三步推进——ApplyWatch(13)、ApplyWatch(16) 把缓存从 10 推到 16,乱序的 ApplyWatch(5) 被拒绝。缓存的最新性由「最近一个已处理事件」决定,而事件处理是异步的,所以缓存永远可能落后于 apiserver 的真实 RV。

判断「缓存是否最新」不能用时间,只能用版本:要么比较缓存 RV 与某次写的 writtenRV(Fresh),要么等 watch 事件推进到位。这正是 12.1 节「版本比较不是时间比较」的延续——这里补上了「推进是异步的、可能落后的」这一面。

generation:spec 的写入计数器

generation 的语义只有一句话,但它是最容易被误用的字段:每次 spec 被修改,generation +1;status 的修改不触发。 它的价值在于提供「期望状态的版本」:

场景操作generationresourceVersion
创建 Deployment第一次写1某值
改 replicasspec 变更2更大值
控制器更新 statusstatus 变更仍为 2更大值
再改镜像spec 变更3更大值

lab 的 Object.Generation 就是这个计数器。Generation 每次 spec 写后 +1,它是「第几次写期望状态」的账本——控制器回滚、缩扩容、改环境变量,每一次都是一个新的 generation。正因为 status 更新不递增 generation,generation 才能稳定地代表「期望」,不会被控制器自己的状态回写污染。

observedGeneration:控制器追平才算最新

observedGeneration 是控制器写给 status 的:「我已处理的最近一个 spec 版本」。lab 的 IsCurrent 是判断控制器是否追平的判据:

func (o *Object) IsCurrent() bool { return o.ObservedGeneration >= o.Generation }

ObservedGeneration >= Generation 的意思是「控制器至少处理到了当前 spec」。这是控制器意义上的「最新」——不是存储最新,不是缓存最新,而是「控制面已经按这份 spec 工作过」。CatchUp() 模拟控制器完成一次调谐:把 ObservedGeneration 对齐到 Generation。

一个值得强调的细节:IsCurrent 用 >= 而不是 ==。为什么允许大于?因为状态可能比 spec 更「前」——比如控制器处理完 generation 5 的 spec 后,把 observedGeneration 写成 5;如果接下来一次 spec 写又把 generation 推进到 6 但很快又回滚,或者控制器按 generation 6 的 spec 调谐完成后再无写入,observedGeneration 有时会短暂等于或超过某些中间值。>= 保证「不会把已追平的控制器误判成滞后」——这是保守而安全的判据。

三种「最新」的判据对照

把三种版本号放进「什么算最新」的框架,判据各不相同:

想回答的问题用哪个字段判据
我的读包含某次写吗resourceVersionseenRV >= writtenRV
缓存追到最新写了吗resourceVersionwatch 推进到目标 RV
控制器看到最新 spec 了吗generation / observedGenerationobservedGeneration >= generation
发布真正收敛了吗全部FullyReconciled(第 12.2 节)

这张表是排障的索引:用户报「改了没生效」,先确定他说的「生效」是哪一层——若他在意「数据读到的对不对」,看 RV;若在意「控制器有没有开始处理」,看 observedGeneration;若在意「发布完没完」,看第 12.2 节的三态。用错字段去判断,结论必然错位。

控制器代码里的标准判据

controller-runtime 的控制器里,「判断是否需要处理」有一套标准写法,把三个版本号串起来。核心模式是只在 spec 变化时干活:

if obj.Generation != obj.Status.ObservedGeneration {
    // spec 变更了,需要调谐
    reconcile(obj)
}
obj.Status.ObservedGeneration = obj.Generation // 调谐完对齐

这个模式比「每次 event 都调谐」高效,因为它把「无关的 status 变化」挡在门外——控制器自己写 status 会推 RV、触发新的 watch 事件,若每次事件都调谐,控制器会陷入自我触发的死循环。generation 比较是天然的去重机制:status 变化不递增 generation,比较结果不变,控制器无事可做。 这正是 generation 存在的工程价值——它让「期望变化」从「所有变化」里被分离出来。

版本号的生命周期管理

三个版本号还有一个容易被忽略的管理面:它们都由谁写、写进哪一栏。

字段写入者写入位置谁负责维护
resourceVersionapiservermetadata客户端不可写,只可读
generationapiservermetadata客户端不可写,只可读
observedGeneration控制器status控制器调谐后显式写

客户端代码永远不要试图直接改 resourceVersion 或 generation——它们是 apiserver 维护的只读字段,写入会被忽略或报错。observedGeneration 则相反:控制器必须记得在调谐结束时把它对齐,否则下一轮调谐会以为 spec 又变了,重复做无用功。忘记写 observedGeneration 是控制器常见的 bug——状态收敛了但 status 永远显示「未追平」,监控和发布判定随之误报。

组合场景:改 spec 后的一系列判定

用一个完整场景串起三个版本号:Deployment 当前 generation=7、observedGeneration=7(已收敛)。运维改 replicas,spec 写进去:

时刻generationobservedGenerationresourceVersion判定
写前77r1已收敛
写后瞬间87r2控制器未处理(滞后)
控制器调谐后88r3控制器已追平
副本就绪后88r4完全收敛

注意 resourceVersion 在每次状态变化(包括控制器写 status)都涨,从 r1 一路到 r4;而 generation 只在第一步 spec 写时从 7 变 8,之后不再动。RV 是「这行数据更新过几次」的流水,generation 是「期望改了几次」的账本——用 RV 判断「控制器处理到没」会得到错误答案,因为控制器写 status 也推 RV。

用 kubectl 直接看版本号

三个版本号都能在命令行里直接观察,这通常是排障第一步:

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

输出三列依次是 RV、generation、observedGeneration。几个快速判断:

  • 第一列持续变大、后两列不动:大概率是控制器在写 status(或频繁 event),spec 没变。
  • 第二列大于第三列:spec 刚改过,控制器还没追平。
  • 第二列等于第三列:控制器已追平,可以接着看副本数判断是否收敛。

注意这个命令读的是 apiserver 缓存,返回的 RV 是「读时刻」的——它本身也会随后续写推进。观察版本号是排障,不是事务:一次快照只能判断状态机的当前相位,要看趋势就隔几秒重跑。

三个常见误解

  • 「resourceVersion 越大,对象越新,控制器一定处理过」——错误。RV 是存储写序号,任何写(包括控制器自己的 status 更新)都会推它;控制器是否处理过某次 spec,RV 不承载这个信息。
  • 「generation 每次写都会 +1,status 也算」——错误。generation 只对 spec 变更递增,status 更新不改变 generation,这是它区别于 RV 的关键。
  • 「observedGeneration 追上 generation 就代表状态收敛了」——错误。追平只代表控制器看到并处理了最新 spec,副本是否就绪(FullyReconciled)还要另看。

一句话总结本节

resourceVersion 是 apiserver 全局单调的写序号,watch 增量只前进不后退地推进缓存;generation 是 spec 写入计数器,status 更新不触发;observedGeneration 由控制器追平,追平才算控制器意义上的最新。判断「最新」先问清是哪一层的最新——存储层看 RV,期望层看 generation,处理层看 observedGeneration。

至此卷四从跨集群负载均衡、Leader 选举、一致性边界一路讲到读路径、写确认与版本号。这一章的落点是同一个主题:分布式系统里「看到的状态」与「真实的状态」之间总有差距,而版本号是把差距变成可判定问题的工具。

本节 lab

本节的三个测试落在 readpath 包的 ReadPath 与 Object 上,验证「watch 增量推进、generation 对齐、过期判定」三条语义:

cd private/labs/k8s-net-lab
go test ./readpath -run TestWatchIncrementalSync -v
go test ./readpath -run TestGenerationCurrent -v
go test ./readpath -run TestObservedGenerationStaleSpec -v
  • TestWatchIncrementalSync:缓存 RV=10,ApplyWatch(13)、ApplyWatch(16) 推进到 16,乱序 ApplyWatch(5) 不倒退,且 Fresh(Read(LayerClientCache), 16) 为真——3 条断言,对应「watch 增量推进、只进不退、追平后可读到新值」。
  • TestGenerationCurrent:Generation=5、ObservedGeneration=4 断言 IsCurrent() 为假;CatchUp() 后断言为真——2 条断言,对应「observed 追平 generation 才算最新」。
  • TestObservedGenerationStaleSpec:Generation=7、ObservedGeneration=7(已追平)后把 generation 写到 8,断言 IsCurrent() 为假——1 条断言,对应「新 spec 一来,旧 observed 立即过期」。

三个测试跑完见 ok k8s-net-lab/readpath。这就是「RV 推进缓存 + generation/observedGeneration 判新旧」的最小闭环。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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