《Kubernetes 分布式系统原理深入解析》2.1 UID、resourceVersion 与 generation 语义

K8s 对象上有三个元数据字段,各自回答不同的问题:UID 标识『是哪个对象』、resourceVersion 标识『哪一次写入』、generation 标识『spec 变化了多少代』。本节精确拆解三者的语义边界——RV 每次写都变、Gen 只有 spec 变才变、UID 终身不变——并说明它们分别服务什么场景(乐观锁、控制器收敛判定、observedGeneration 对照)。lab 用 api/object.go 与 api/store.go 验证三者的变化规则。

2.1 UID、resourceVersion 与 generation 语义

K8s 对象上有三个元数据字段,长得像、行为却完全不同。本节把它们拆开:各自回答什么问题、各自随什么变化、各自服务什么场景。理解这三者,是理解整个「版本化并发控制」的前提。

三个字段,三个问题

字段回答的问题变化规则
uid是哪个对象(身份)终身不变
resourceVersion哪一次写入(版本)每次写都 +1
generationspec 变化到第几代(代际)仅 spec 变时 +1

一句话区分:UID 是身份证号,RV 是修订号,Generation 是代次。身份证号终身不变,修订号每改一版变一次,代次只在「内容方案」改变时前进。

UID:对象的不变身份

metadata.uid 在对象创建时生成,之后永不改变——即使对象被反复更新、甚至删了重建(重建是新对象,新 UID)。

UID 的用途:

  • 事件关联:watch 事件里的对象带 UID,客户端可以判断「这条事件是不是同一个对象的变化」,而不是靠名字。
  • OwnerReference 的唯一键:RS 通过 UID 认领自己的 Pod,而不是靠 label(label 可能撞车,UID 不会)。
  • 跨生命周期追踪:即使 Pod 被删除再被 RS 重建,它们的名字可能相同但 UID 不同——控制器能区分「这是新 Pod 还是旧 Pod」。

设计要点:名字是寻址(addressable),UID 是身份(identity)。同名对象在重建后是不同个体,凡是需要「持久关联」的地方都必须用 UID。

resourceVersion:每一次写入的版本

metadata.resourceVersion 是对象在 etcd 层面的版本号。规则:

  • 每次成功的写(spec 或 status 变化)都会分配一个新 RV。
  • RV 全局单调递增(在 apiserver/etcd 层面),不限于单个对象。
  • 客户端必须携带 RV 才能更新:Update 携带旧 RV,若服务器上已变则返回 409。

RV 背后就是卷一的 mvcc revision:etcd 为每次写分配 revision,K8s 把它暴露为对象的 resourceVersion。两者的数值可能不同(apiserver 可能做映射),但语义一致:单调、全局有序、每次写递增。

RV 的用途:

  • 乐观锁:更新前读 RV,更新时比对(卷二 2.2 节)。
  • Watch 游标:list 返回当前 RV,watch 从该 RV 续增量(卷二 3.1 节)。
  • 一致性判定:对象是否「比我看到的更新」,比较 RV 即可(相等则未见变化)。

关键点:RV 变不代表「spec 变了」,也可能只是 status 被控制器更新了。它是「写入版本」,不是「内容」版本。

generation:spec 的代际

metadata.generation 只随 spec 变化,status 变化不递增。它的引入是为了解决 RV 的不足:

  • RV 每次写都变,但很多写是控制器写的 status——对用户没有意义。
  • 用户想知道「我改的 spec,控制器跟上没有」。Generation 就回答这个:spec 每变一次 +1,控制器处理后把 observedGeneration 追平。

典型用法:

metadata:
  generation: 3
status:
  observedGeneration: 3   # 控制器已处理到第 3 代

当 status.observedGeneration == metadata.generation 时,说明控制器已看到最新 spec;否则说明还有待处理的变化(或控制器在重试中)。这是判断「声明是否已生效」的权威依据。

注意 Generation 的边界:它不比较内容。如果用户把 replicas 从 3 改到 3(内容相同),apiserver 也可能递增 Generation(因为写请求发生了)。真实实现中,apiserver 只有在 spec 字节差异时才递增 Generation——但用户驱动不了「内容等价却递增」的情况,所以通常认为「Generation 反映 spec 更新的次数」。

三者如何协同:一个滚动更新的例子

考虑一次滚动更新:

  1. 用户 kubectl set image(改 spec)→ Deployment.Generation 3→4。
  2. 控制器看到 Generation 4 的对象,创建新 RS。
  3. 控制器把 status.observedGeneration 更新为 4。
  4. 用户查询:observedGeneration==4 说明控制器已看到我的修改。

整个过程中:

  • UID 不变:还是同一个 Deployment。
  • RV 变了很多次:每次控制器写 status 都变。
  • Generation 只从 3 到 4:只有用户那一次 spec 修改触发了递增。

这就是三者的分工:UID 跟踪身份,RV 跟踪每次写,Generation 跟踪「需要控制器响应的 spec 代次」。

从 mvcc revision 到 resourceVersion 的映射

resourceVersion 不是 etcd revision 的直接别名,理解这层映射有助于判断「RV 到底有多可信」:

层版本标识语义
etcdrevision全局单调,每次写 +1
apiserver 对象resourceVersion对象的当前写入版本
watch 事件每条事件带 RV事件的顺序编号

apiserver 在写入对象时,从 etcd 的写入响应拿到 revision,把它存为对象的 resourceVersion。对同一个 apiserver 而言,resourceVersion 与 revision 数值上可以一致(单存储);但对多 apiserver + 不同 etcd 后端(如存储层做了缓存/聚合),数值可能不同,语义才是关键:单调、全局有序、每次写递增。

所以判断「两个对象谁更新」用 RV 比较是可靠的(同一 apiserver 视角下);跨 apiserver 比较 RV 没有绝对意义——它们都对齐到同一个 etcd revision 序列上,数值仍是可比的。这正是 kubectl 拿到 --watch 时依赖 RV 续接的原因:它只关心「从某个点之后发生了什么」。

observedGeneration:声明与执行的对照

status 里的 observedGeneration 是控制器「我已处理到第几代 spec」的报告。用伪代码看控制器的对照逻辑:

if obj.Status.ObservedGeneration != obj.Generation {
    // 控制器还没处理到用户最新的 spec:重新调谐
    enqueue(obj.Name)
    return
}
// 已处理到最新代:检查其他字段是否达成(如 readyReplicas == replicas)

这个对照回答了声明式系统的核心问题:用户的声明,控制器执行到哪一步了? 只有 observedGeneration == generation 时,控制器才真正「看到并开始处理」最新声明;否则即使 readyReplicas 看起来对了,也可能是旧一代的遗留状态。

用 UID 判断「是不是同一个对象」

名字会被复用,UID 不会。这是 K8s 里「身份」与「寻址」的分离,具体场景最有说服力:

考虑一个 Deployment 的 Pod 被删除后重建:

时刻事件Pod 名字Pod UID
t1Pod 创建web-abc121111-…
t2Pod 被删——
t3RS 重建 Podweb-abc12(名字相同)2222-…

名字都是 web-abc12,但 UID 不同。凡是需要「持久关联」的地方必须用 UID:

  • OwnerReference:RS 认领 Pod 用 UID。若用名字,Pod 重建后 RS 会误认领「新 Pod 是同一个」,导致重复管控。
  • 事件关联:watch 事件携带对象的 UID,客户端区分「同名的旧对象 vs 新对象」。
  • 日志/审计:以 UID 为关联键,避免同名重建混淆。

反过来,resourceVersion 也随每次写变化,但 UID 不变。所以「判断是否同一个对象」看 UID,「判断是否更新」看 RV,「判断 spec 是否更新」看 Generation——三者各司其职,不可混用。

三个常见误解

  • 「RV 变了 = spec 变了」——错误。RV 随任何写(包括 status)变化;要判断 spec 变化看 Generation。
  • 「Generation 每次更新都 +1」——错误。只有 spec 变化才递增;纯 status 更新不动 Generation。
  • 「UID 等于名字」——错误。名字可被重建复用,UID 唯一且终身不变;凡持久关联必须用 UID。

一个组合判读:RV 变但 Gen 不变说明什么

实操中遇到「对象 RV 变了、Generation 没变」,最可能的解释是有人只写了 status。这本身不是异常:

观察推断是否正常
RV↑, Gen 不变写的是 status(控制器)正常
RV↑, Gen↑spec 被改(用户)正常
RV 不变没有任何写正常
Gen↑ 但 observedGeneration 未追平控制器还没处理收敛中

最后一个场景要警惕:observedGeneration < generation 说明控制器滞后或失败。这是「看状态」时的第一检查项——先看代次是否追平,再看副本数是否达标。追平之前的「就绪数达标」可能只是旧一代的遗留状态。

本节 lab

本节验证三者的变化规则:UID 不变、RV 递增、Generation 仅 spec 变化时递增:

cd private/labs/k8s-ctrl-lab
go test ./api -run 'TestRVMonotonic|TestGenerationStatus' -v
  • TestRVMonotonic:Create 后 Update,断言 UID 不变、RV 从 1 到 2、Generation 从 1 到 2(spec 变了)。
  • TestGenerationStatus:UpdateStatus 后断言 Generation 不变、RV 递增——正是「status 写不推进代次」的规则。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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