2.1 UID、resourceVersion 与 generation 语义
K8s 对象上有三个元数据字段,长得像、行为却完全不同。本节把它们拆开:各自回答什么问题、各自随什么变化、各自服务什么场景。理解这三者,是理解整个「版本化并发控制」的前提。
三个字段,三个问题
| 字段 | 回答的问题 | 变化规则 |
|---|---|---|
uid | 是哪个对象(身份) | 终身不变 |
resourceVersion | 哪一次写入(版本) | 每次写都 +1 |
generation | spec 变化到第几代(代际) | 仅 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 更新的次数」。
三者如何协同:一个滚动更新的例子
考虑一次滚动更新:
- 用户
kubectl set image(改 spec)→ Deployment.Generation 3→4。 - 控制器看到 Generation 4 的对象,创建新 RS。
- 控制器把
status.observedGeneration更新为 4。 - 用户查询:
observedGeneration==4说明控制器已看到我的修改。
整个过程中:
- UID 不变:还是同一个 Deployment。
- RV 变了很多次:每次控制器写 status 都变。
- Generation 只从 3 到 4:只有用户那一次 spec 修改触发了递增。
这就是三者的分工:UID 跟踪身份,RV 跟踪每次写,Generation 跟踪「需要控制器响应的 spec 代次」。
从 mvcc revision 到 resourceVersion 的映射
resourceVersion 不是 etcd revision 的直接别名,理解这层映射有助于判断「RV 到底有多可信」:
| 层 | 版本标识 | 语义 |
|---|---|---|
| etcd | revision | 全局单调,每次写 +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 |
|---|---|---|---|
| t1 | Pod 创建 | web-abc12 | 1111-… |
| t2 | Pod 被删 | — | — |
| t3 | RS 重建 Pod | web-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 写不推进代次」的规则。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。