12.3 resourceVersion 背后的 mvcc
12.2 节建立了乐观锁的底层:mod_revision 比较,冲突返回 409。本节把这条链路完整化——K8s 对象上的 resourceVersion 字段,就是该对象最近一次写入的 etcd revision(mod_revision)的字符串投影;List、watch、410 Gone、续页全都建立在这一个数字上。理解 12.1 的版本树与 12.2 的乐观锁之后,resourceVersion 不再是「一个神秘的字符串」,而是一个可推导的存储事实。
几乎所有 K8s 开发者都见过 resourceVersion 出现在 kubectl 冲突提示、informer 日志或对象 YAML 里,但很少有人意识到它背后是 etcd 的版本树。本节的任务是把这个字段「拆开」:它如何生成、如何被 Update 消费、如何被 List/watch 消费、以及它何时失效(410)。四个问题回答完,K8s 对象版本语义就算真正讲透了。
resourceVersion:mod_revision 的字符串投影
K8s 对象 metadata.resourceVersion 的底层就是 mvcc 里该键的 mod_revision——第 12.1 节 Get 返回的 (value, modRev, ok) 三元组里,modRev 在 API 表面被序列化成字符串。lab 的 TestMVCCGetReturnsLatestWithModRev 正是这个投影的最小验证:Put("k", "v1")、Put("k", "v2") 之后,Get("k") 返回 v2@2——最新值与 mod_revision 2 一起返回,这个 2 就是对象 resourceVersion 的底层数字。
resourceVersion 的三个性质,每个都要记牢:
- 同一对象每次更新,RV 递增:每次成功写都推进该键的 mod_revision,所以对象越新的 RV 越大;
- 跨对象无全局顺序意义:对象 A 的 RV=100 与对象 B 的 RV=5 不能比较谁更「新」——A 在第 100 次写被改过、B 在第 5 次写被改过,两者最后一次被改的时刻互不可比;
- RV 比较只在单对象内有效:判断「这个对象的两个版本谁更新」,只能用同一对象的两份 RV 比大小。
这条「单对象有效」性质在实际排障里很重要:两个 Deployment 的 RV 分别是 1000 与 5,不能据此推断前者更新——前者只是所在对象最近被写时全局写序号恰好在 1000,后者在序号 5 时被写,两者最后一次被写的先后要用 etcd 的写时记录判断,而不是 RV 互比。
为什么 K8s 用 revision 而不是全局时间戳来做这个字段?因为 revision 是写序号,天然满足「每次写都递增」;时间戳则受时钟影响(第 3 章讲过 NTP 偏移与 HLC),同一秒内的多次写无法靠时间戳区分先后。revision 由 etcd 单一来源颁发、单调、无时钟依赖,是判断「最新」的可靠依据。
还有一层精度问题要说明。第 12.1 节讲过,真实 etcd 的 revision 是 {main, sub} 二元组:main 是全局写序号,sub 是同一事务内多 key 的子序号。K8s 对象上序列化出来的 resourceVersion 主要取 main 的十进制数字。一个直接推论:同一个 etcd 事务里先后写入的两个对象,resourceVersion 可能相同(共享同一个 main)。这对大多数场景无影响——不同对象的 RV 本来就不可比——但在「怀疑两个对象是否在同一时刻写入」的场景(如事务性迁移)里,仅凭 RV 无法判断,需要看 etcd 侧更细的记录。
resourceVersion 在 API 里是字符串而不是整数,这一点也值得留意。K8s 的设计理由主要是向前兼容:保留将来调整序列化格式(例如携带 sub、或改用别的版本算法)的空间,避免客户端把 RV 当数字解析后产生依赖。客户端应该把 RV 视为「不透明的不变体」——比较相等、带回 Update,而不是解析它的数值。
对象被删除后 RV 会发生什么?第 12.1 节讲过,Delete 追加墓碑并推进 mod_revision,但 Get 返回「不存在」。因此在 K8s API 表面,删除后对象连同它的 resourceVersion 一并消失——RV 只对「仍存在的对象」有意义。watch 客户端会收到 Delete 事件,事件的 ObjectMeta.ResourceVersion 是删除产生的那个版本号,这可以用于精确确认「删除发生在哪个写之后」,但也意味着删除事件无法靠旧 RV 重放——这正是 410 与全量 relist 存在的原因。
Update 携带 RV 的乐观锁
一个带 resourceVersion 的 Update 在 apiserver 内部的完整路径是:校验对象 → 读取 etcd 中该键当前的 mod_revision → 与请求携带的 resourceVersion 比较 → 一致则写、不一致返回 409 Conflict。这正是 12.2 节 CASModRev 的语义,区别只在 apiserver 把「比较失败」翻译成 HTTP 层可见的 409。
两个典型的更新结果:
| 请求 | 携带 RV | 当前 mod_revision | 结果 |
|---|---|---|---|
| 正常更新 | 5 | 5 | 成功,对象到 rev6 |
| 冲突更新 | 5 | 7(别人已改) | 409,对象不变 |
冲突后客户端重读最新对象、拿到新的 resourceVersion 再重试——控制器用 informer 缓存的最新状态重算 diff,正是 12.2 说的「重读重算」路径。kubectl 的 apply 与 edit 同样遵守:edit 保存时带上下文里读到的 RV,若期间被他人修改则提示冲突。
409 的触发频率在大型集群里是一个可观测信号:单对象被多个写者频繁竞争时,apiserver 的请求日志会出现成对的 409。健康集群里 409 是罕见事件;如果某类资源持续高冲突,通常意味着设计问题——多个控制器反复改同一对象而没有拆分冲突域,例如两个控制器同时管理同一个 Deployment 的 replicas。把冲突域拆开(不同控制器写不同字段,或换用 patch 精准更新字段)往往比无脑重试更有效。
kubectl 的 apply 是一个特殊的 Update:它在客户端做三方合并(上次 apply 的配置、当前对象、本次改动),合并结果仍以 Update 提交、仍带当前对象的 resourceVersion。所以 apply 同样受乐观锁约束——两个终端同时 kubectl apply 同一对象,后提交者收到 409,需要重新 apply。这也说明 resourceVersion 的校验是 apiserver 写路径的统一入口,与客户端用哪种合并策略无关。
Create 是 Update 的特例:CASModRev(key, 0, value) 表示「仅当 key 不存在(mod_revision 视为 0)才创建」。K8s 的 Create 同样语义——对象已存在返回 409(或 500 系的 AlreadyExists 语义),绝不覆盖已有对象。这也解释了为什么 Create 请求不需要带 resourceVersion:它校验的是「不存在」,而不是「某个版本」。细想一步:如果 Create 也允许带 RV 并做「版本校验」,那它就和「基于某版本的覆盖」没区别了——K8s 用 Create/Update 的职责分离,把「创建」与「更新」的乐观锁语义清晰切开。
乐观锁同样覆盖子资源写:Deployment 的 status、Pod 的 status 都是独立的 etcd key,它们的 Update 同样带 resourceVersion 并做 mod_revision 比较。这意味着主资源与状态子资源是两套独立的版本序列——主对象的 spec 更新与 status 更新互不干扰、各自推进自己的 RV。控制器写 status 时带的是 status 的 RV,而不是主对象的 RV,混用会导致莫名的 409。这是 K8s 多写者场景里最容易踩的坑之一。
List 带 resourceVersion 的语义
List 请求可以携带 resourceVersion,它的语义是「从该 revision 读取一份快照」。在 etcd 侧,这对应 RangeRequest 的 revision 字段——mvcc 的 GetAtRev 按指定版本回溯,返回的是该时刻的键值集合,而不是当前状态。lab 的 TestMVCCReadHistoricalAtRevision 已验证过这种「读快照」的原子行为,List 就是把它推广到全库范围。
带与不带 RV 的 List 差异,衔接第 10.3 节的读模式讨论:
| List 形态 | 底层路径 | 一致性 |
|---|---|---|
| 不带 resourceVersion | apiserver watch cache 快照 | 弱一致,可能旧几个事件 |
| 带 resourceVersion | 回落 etcd,从该 revision 读 | 线性一致快照 |
续页(pagination)是带 RV 读最实际的应用:kubectl get pods 翻页时,continue token 编码了「下一页从哪个 revision 继续」,保证翻页过程不重不漏。apiserver 的 pagingList 在 etcd 侧就是一次带 revision 的 Range,取回该点快照后按 limit 截断、返回 continue。
不带 RV 的 List 默认由 watch cache 快照服务(第 10.3 节讲过 Cacher 结构),它消费 watch 事件流、可能比 etcd 当前状态旧几个事件。带 RV 的 List 回落 etcd 走线性一致读——代价是多一次往返,收益是「读到确定时刻」的快照。工程上两者各有用途:控制器日常调谐用 watch cache 快照(快、旧一点无妨),需要精确状态(校验、迁移、审计)时带 RV 回落。
还有第三个选项值得记录:resourceVersion="0" 与 resourceVersion="" 在 K8s List 语义里不完全等同。空字符串表示「走默认路径」(通常是 watch cache 快照);显式的 0 在部分实现里表示「尽量从最新状态读」,两者的落地行为取决于 apiserver 的版本与资源类型。对控制器开发者,最稳妥的约定是:不指定 RV 就用默认缓存路径,需要精确快照就带一个明确的非零 RV,避免依赖「0 的特殊语义」。
List 响应本身也会带 metadata.resourceVersion——这是本次快照读的位置(读时主 revision)。把响应头 RV 记下来,作为下一次 List 或 watch 的起点,就是 informer 增量同步的标准姿势;不记录它,每次 List 都是全量快照,事件丢失也无从接续。这个「拿 RV、存起来、下一次带上」的循环,是 K8s 控制面所有增量逻辑的基础。
注意 List 的 resourceVersion 与对象自身的 resourceVersion 不是一回事:List 的 RV 是快照位置,对象自身的 RV 是对象最后一次写。一个返回快照的 List 里,各对象的 RV 可能各不相同——它们在不同时刻最后一次被写,只是「读」发生在同一快照点上。反过来说,List 响应头里的 RV 是「本次快照读的主 revision」,把它带回下一次 List 或作为 watch 起点是合法且常用的——这正是 informer 初始同步的「先 List 拿 RV、再从 RV 建 watch」模式。
watch 对 RV 的消费方式值得单独说一句:watch 请求带 resourceVersion 表示「从该版本之后订阅」,不带则表示「从当前开始」。带 RV 的 watch 依赖该版本未被压缩(否则 410),所以它的 RV 通常来自最近一次 List 的快照位置——这样 List 与 watch 首尾相接,事件流连续。第 13 章会展开 watch 的版本区间与事件序,这里只需记住:RV 是 List 与 watch 之间传递状态的桥梁,快照位置必须落在保留区间内。
compaction 导致旧 RV 过期:410 Gone
历史不是无限保留的。第 9.3 节与 12.1 节讲过,压缩(compact)丢弃 ≤ compactedTo 的版本。一旦客户端读一个已被压缩的 revision,etcd 返回 ErrCompacted,K8s 侧翻译成 HTTP 410 Gone。
lab 的 TestMVCCCompactedRevisionRejected 验证了这个边界:Put a@1、b@2、c@3 后 Compact(2),读 GetAtRev("a", 1) 返回 ErrCompacted;未压缩的 c@3 仍可读;所有版本都被压掉的 key a 不可见。三个断言对应三种客户端命运:旧 RV 读失败、新版本正常读、被压 key 视为不存在。
K8s 里最常见的 410 场景是 informer:它持有一个很久的 resourceVersion 尝试 relist 或重建 watch,但该版本已被压缩。收到 410 后 informer 强制全量 relist 再重建 watch——功能上能自愈,但对大型集群是一次数千个对象的下载。第 9.3 节强调「auto-compaction-retention 必须大于最长的 watch 存活窗口」,正是为了把 410 的触发概率压到最低。
410 与 409 需要区分清楚:409 是乐观锁冲突(版本存在但已过期,重读即可),410 是版本不存在(已被压缩,无法定位到该历史点,必须重新 List 全量)。前者重试成本低,后者可能是一次全量下载。客户端对两者的处理也因此不同——409 重读重试、410 全量 relist,写代码时不能混用。
错误文本也能帮助定位:etcd 侧报 etcdserver: mvcc: required revision has been compacted,K8s 侧转成 410 Gone。排障时若在 apiserver 日志看到这段 etcd 错误,先确认 auto-compaction 参数与客户端缓存时长——大概率是 retention 太短或客户端离线太久,而不是 etcd 本身故障。lab 的 ErrCompacted 就是这段语义的最小形态,注释里也明确标注了它对应 etcd mvcc 的 mvcc.ErrCompacted。
410 之后的恢复动作要配合版本策略:informer 收到 410 会重新 List 拿到一个新 RV、再建 watch,整个过程自动完成,但期间缓存短暂清空、事件可能错过。对这个窗口敏感的组件(如依赖连续事件的计数器)需要考虑在 relist 期间暂缓决策,或在 relist 完成后补一次全量比对。
压缩导致的 410 有一个隐蔽的放大场景:长时间离线的节点(例如 kubelet 断连数小时)恢复后带着旧 RV 重建状态,如果 retention 设置过短(几十分钟),几乎必然触发全量 relist。这解释了为什么 K8s 官方推荐 8h 的 retention——它要让「最坏情况的离线恢复」也能在未压缩区间内完成。
压缩的微观行为(lab 的 TestMVCCCompactRemovesOldVersions)还能回答一个运维问题:为什么压缩后某些对象会「凭空消失」?答案是「最新版本被压掉」。lab 里 key a 只有 a@1、a@2 两个版本,Compact(2) 把两者都压掉,a 从存储消失——它的最新版本已不在保留区间。对 K8s 而言,如果一个对象在压缩点之前被创建、之后从未更新,压缩可能把它连同全部历史一起清掉;如果它之后还更新过,则保留区间内至少有一个版本,对象仍可见。这正是「压缩点永远只删过去的版本、不碰当前版本」在单对象层面的展开。
注意压缩点是全局的:lab 的 compactedTo 对所有 key 生效,etcd 的压缩也是全库范围。不存在「只压缩 key A、保留 key B 的历史」的细粒度压缩——要么都在保留区间内,要么都不可读。这个全局性决定了 K8s 无法按对象定制保留时长,只能统一用 auto-compaction 参数(第 9.3 节的 periodic 或 revision 模式)控制整库的保留窗口。这也是为什么「某类资源需要更长历史」的需求(如审计)通常要靠外部事件源或专门的镜像表,而不是调大整库的 retention。
为什么不能依赖对象自增字段判断最新
有些系统用「对象内自增计数器」或 updatedAt 时间戳判断最新。这两类方案在分布式场景都有缺陷,对比 revision 看看差距:
| 判新手段 | 单调性 | 时钟依赖 | 并发冲突检测 | 跨对象可比 |
|---|---|---|---|---|
| 应用层时间戳 | 弱(同秒重复) | 有(NTP/偏移) | 无 | 近似但不可靠 |
| 应用层自增计数器 | 有 | 无 | 弱(并发同基数) | 无 |
| etcd revision | 强(每次写 +1) | 无 | 强(mod_revision 比较) | 无(但无需) |
时间戳的弱点在第 3 章已经展开:时钟可能回拨、不同机器不可比、同秒多次更新无法排序。自增计数器的问题更隐蔽:如果它存在对象内部、由客户端递增,两个并发客户端可能基于同一个基数各自 +1,得到相同的「最新计数」,冲突检测失效。revision 由 etcd 在 apply 时统一颁发、全局单调,不存在「两个客户端取到同一版本号」的可能——这正是乐观锁成立的前提。
另一个候选是内容哈希(如对对象 JSON 取 hash 作为版本)。哈希的问题在于它无法表达「写」本身:两个客户端把对象写成相同内容时,哈希相同、检测不到并发;而一个客户端把对象改回旧值,哈希又回到旧值——这正是 12.2 节提过的 ABA 问题。revision 不受内容影响,它只反映「被写过」这个事实,因此无论内容如何变化,每次写都产生新的版本号。这也是「版本」与「指纹」的本质区别:版本描述历史,指纹描述状态。
最后对比「对象自身的自增字段」还有一个现实层面:K8s 对象是共享的,任何客户端都可以改它。如果版本号存在对象内部、由客户端自增,恶意或错误的客户端可以任意伪造版本号,乐观锁形同虚设。revision 存在 etcd 存储层、由服务端颁发,客户端只能「读回」而不能「写入」,这是它可靠的又一原因——权威性来自存储,不来自客户端。
把这些反面方案串起来看,一个模式浮现:「最新」的判断必须由共识(或等价的全序机制)背书。时间戳靠物理时钟、自增字段靠客户端纪律、内容哈希靠内容本身,三者都缺少「单一权威、全局递增」的背书;revision 由 Raft 共识后的 apply 统一推进,权威性与全序性来自共识层。这正是第 4 章「共识」与第 12 章「存储」在概念上的接缝——共识保证了「版本号有序」,mvcc 把这个有序性变成「可查询的历史」。
「跨对象无需可比」也要解释清楚:K8s 从不靠两个对象的 RV 大小判断先后,需要的是「同一对象的版本比较」(乐观锁)与「全库的快照位置」(List/watch)。前者用单对象 RV,后者用读时主 revision,两者都由 etcd 的单调计数提供,只是取用方式不同。
把「需要可比」与「无需可比」的应用场景分开列一张表,避免在实现里用错:
| 需求 | 用什么 | 例子 |
|---|---|---|
| 同一对象的版本先后 | 该对象的 RV 比较 | Update 乐观锁、watch 事件排序 |
| 全库的快照位置 | 读时主 revision | List 续页、watch 起点 |
| 两个对象谁先写入 | 无法用 RV 判断 | 需靠 etcd 侧事务记录或外部标记 |
| 全局最新状态 | 读时主 revision(不取单对象 RV) | 快照一致性判断 |
最后一行是常见的误用点:想判断「集群是否处于某个较新状态」时,不应该取某个对象最大的 RV,而应该看读响应头的主 revision——它是全库统一推进的序号,单对象 RV 只是它的投影。
从 12.1 到 12.3:一个完整读写流程
把三节串成一个完整的读写闭环,用一个 Deployment 的更新流程演示:
| 步骤 | 动作 | 底层 | 结果 |
|---|---|---|---|
| 1 | 控制器 Get Deployment | etcd 线性一致读,返回 mod_revision=41 | 对象 RV=41 |
| 2 | 修改 spec 后 Update(RV=41) | apiserver 比较 mod_revision=41 | 成功,对象 RV=42 |
| 3 | 另一个控制器也 Update(RV=41) | 比较发现当前已是 42 | 409,重读重试 |
| 4 | informer 用 RV=30 重建 watch | 该版本已被压缩 | 410,全量 relist |
| 5 | List 带 RV=45 续页 | mvcc 从 revision 45 读快照 | 不重不漏 |
第 1、2 步是 12.2 的乐观锁,第 4 步是本节与第 9.3 节的压缩联动,第 5 步是本节的快照读。贯穿始终的是 12.1 的版本树:每个键都保留历史、每次写都推进全局序号、压缩在时间轴前端回收。resourceVersion 不是 etcd 的附加功能,而是 mvcc 版本模型对 API 的暴露面。
这条流程也解释了为什么「resourceVersion 变了」不能简单等同于「对象内容变了」:任何写——即使 spec 与 status 的值最终没变——都会推进 mod_revision,从而改变 RV。反过来,RV 不变必然意味着自该版本之后没有写。所以 RV 是「写」的充分必要指示器,这正是乐观锁需要的性质:它检测的是写,不是内容差异。理解这一点,就能解释为什么一个看似「什么都没改」的 Update 也会让 RV 前进。
第 12 章到这里闭环:12.1 回答「版本从哪来」(revision 与版本树),12.2 回答「版本怎么用于并发控制」(乐观锁与 fencing),12.3 回答「版本怎么暴露给 K8s」(resourceVersion 与 409/410)。三者是同一个存储模型的三张面孔。往后看,第 13 章的 watch 建立在「从版本区间读事件」之上,第 15 章的运维建立「压缩与保留窗口」之上——它们都以本节与第 9.3 节的 revision 边界为前提。
一个值得一提的工程结论收尾:resourceVersion 的设计把「并发检测」与「存储实现」解耦——K8s 客户端只感知一个字符串,etcd 把它实现成 mod_revision。这个抽象让 K8s 有替换底层存储的可能性(例如某些发行版用其他后端),只要后端能提供「每次写递增、可比较、服务端颁发」的版本号。换句话说,乐观锁不绑定 etcd,绑定的是「单调递增的权威版本号」这一契约。
本节 lab
本节用 store 包三个用例验证「Get 返回最新值+mod_revision、旧版本被压缩拒绝、压缩回收版本链」三个方向。实现代码在 private/labs/k8s-etcd-lab/store/mvcc.go(Get、GetAtRev、Compact),测试在 store/mvcc_test.go,与 12.1 的用例同文件、按语义分区。运行前确认在仓库根目录执行 cd private/labs/k8s-etcd-lab,否则 ./store 的相对路径会找不到:
cd private/labs/k8s-etcd-lab
go test ./store -run 'TestMVCCGetReturnsLatestWithModRev|TestMVCCCompactedRevisionRejected|TestMVCCCompactRemovesOldVersions' -v
预期断言:
TestMVCCGetReturnsLatestWithModRev:Put("k","v1")、Put("k","v2")后Get("k")返回 v2 且 mod_revision=2——证明 Get 同时给出最新值与它对应的 mod_revision,即 resourceVersion 的底层数字;TestMVCCCompactedRevisionRejected:Compact(2)后GetAtRev("a", 1)返回ErrCompacted,未压缩的c@3正常读、被压 key a 不可见——证明旧 RV 读失败(对应 K8s 410 Gone),新版本不受影响;TestMVCCCompactRemovesOldVersions:Compact(2)移除 2 个版本、compactedTo前移到 2、a 消失而 b@3 保留——证明压缩回收旧版本链的具体数量与方向。
三个用例分别验证「RV 的投影」「压缩后 410」「压缩的回收量」,与本节开头、中段、结尾的三部分论述一一对应。
把 12.3 的 lab 与 12.1、12.2 的 lab 放在一起看,store 包的 8 个用例正好覆盖第 12 章的三层语义:前三个(TestMVCCPutAssignsMonotonicRevision 等)验证版本树与墓碑,中间两个(TestTxnAtomicIfThen、TestCASAndCASModRev)验证乐观锁,本节三个验证 resourceVersion 的投影、410 与压缩回收。整个 store 包就是第 12 章的可运行讲义,配合 lease 包的 TestRevokeImmediateAndFencingToken,乐观并发一条线就完整了。运行命令全部通过即满足 12.3 的语义要求。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。