《Kubernetes 分布式系统原理深入解析》13.1 watch 协议:版本区间、事件、backlog 与 compact

watch 是 List 之后持续获得增量的通道:客户端以起始 revision 与 key 范围订阅,服务端回放该点之后的事件并转入实时,事件各带全局 revision 且永不重复;起始 revision 早于压缩点时 watch 失败需重建。lab 验证历史回放、PUT/DELETE 事件序列与 compact 断流。

13.1 watch 协议:版本区间、事件、backlog 与 compact

第 12.3 节讲过 resourceVersion 背后的 mvcc:每个键的每次变更都产生一个全局单调递增的 revision,K8s 对象的 resourceVersion 就是它最后一次变更的 revision。但 List 只给你一个时刻的快照——对象随后又变了,你怎么持续知道?答案是 watch:在快照之上开一条增量流,把「之后发生了什么」源源不断推给客户端。本节把 watch 协议的最小语义拆开:客户端怎么指定起点与范围、事件怎么携带版本号流动、追不上存量时怎么 backlog 追平、历史被压缩时又怎么断流。

三节的分工是:13.1 讲一条 watch 的完整协议语义(怎么建、怎么收、怎么断);13.2 把放大倍数讲清楚(一条事件如何扇出给上万个 watcher、服务端怎么限流);13.3 回到客户端视角,讲断连后如何用 revision 书签无缝恢复。本节的两个概念——backlog 追平与 compact 断流——是后面两节的共同基础:13.2 的慢消费者被取消之后怎么恢复,正是 13.3 的重连协议。

从快照到增量:List 之后为什么要 watch

一个典型请求序列是这样的:先 List 拿全量快照,再 Watch 订阅增量。两者共享同一套 revision 坐标,才能无缝衔接。

步骤手段拿到什么版本坐标
1List(带 resourceVersion)某一 revision 的全量快照rv0
2Watch(start_revision = rv0 + 1)rv0 之后的所有变更事件rv0+1 起
3持续消费实时事件流当前 revision 起一直往后

如果只 List 不 Watch,快照会以不可控的速度过时,你看到的是「一个过去时刻的镜像」;如果只 Watch 不 List,你缺失起点之前的全部历史,增量无从谈起。两者组合,K8s 的 informer 才得到「先全量、后增量」的完整视图。第 12.3 节说 resourceVersion 是「读历史」的钥匙,watch 就是「读未来」的通道——二者坐标是同一个 revision,起点接终点,正好把完整历史切分成互补的两段。

这里有个容易混淆的点:List 返回的是快照,Watch 返回的是事件流,但两者都挂在同一个全局 revision 坐标系上。快照回答「到 rv0 为止长什么样」,事件流回答「rv0 之后发生了什么」。把两个答案合起来,客户端在任何时刻都能重建出该 key 区间的完整状态机演化过程——这正是控制器调谐循环的基础:先看现状,再追增量,落到每个对象的最新版本上执行期望状态。

为什么不直接用轮询代替 watch?对比就清楚了:

方案获取增量延迟服务端开销
轮询 List每次拉全量再本地 diff受轮询间隔限制每次全量扫描一遍前缀
watch 增量事件即推即达一个事件的传输延迟只推变更,负载与变更数成正比

轮询要么延迟高(间隔长),要么服务端负载高(间隔短、全量扫描);watch 把「变更」本身变成推送单元,延迟低且负载与变更率成正比。K8s 的 informer 走的是「低频全量 + 高频增量」组合,轮询只保留在极少数不支持 watch 的互操作场景里。

watch 请求:起始 revision 与 key 范围

watch 请求的核心字段只有三个:key、range_end 和 start_revision。key 与 range_end 定义了一个半开区间 [key, range_end),表示「我要订阅哪些键」;start_revision 定义订阅的版本起点。

写法keyrange_end订阅范围
单键/registry/pods/default/foo空恰好这一个键
前缀/registry/pods//registry/pods0该前缀下的所有键
全范围/registry/pods/\0key 之后的所有键

前缀写法是 K8s 用得最多的:/registry/pods/ 前缀覆盖一个命名空间、一种资源甚至全集群的对象。etcd 客户端提供 WithPrefix() 帮我们生成 range_end(把前缀最后一个字节加一),所以代码里写 clientv3.WithPrefix() 即可,不必手算范围边界。命令行对应 etcdctl watch /registry/pods/ --prefix。

除了 key、range_end、start_revision,WatchCreateRequest 还有几个常用的辅助字段:

字段作用
progress_notify周期性返回一致性书签(13.3 节展开)
prev_kvPUT/DELETE 事件附带变更前的值
watch_id客户端为复用指定的 watch 标识
fragment大事件响应是否允许分片

命令行用法与之对应:etcdctl watch /registry/pods/ --prefix --rev=100 --prev-kv 表示从 rev 100 起订阅前缀,并且每个事件都带上变更前的值。

start_revision 的语义是「从这个 revision 之后的事件开始给」:start_revision = rv0 + 1,那么 rv0 及更早的事件都不必给,因为 List 快照已经把它们包含在内了。这个字段把快照与增量切成互补的两段,是 watch 协议版本区间的核心。默认不传时从当前最新 revision 开始,客户端随后只收「创建 watch 之后」的新事件——这在不需要存量追平的场景(比如纯通知)里够用,但 K8s 的 informer 几乎总是显式带上起点,因为要跟 List 快照对齐。

一个常见的工程问题:如果两个资源的 key 前缀有包含关系,watch 前缀较短的那一个会收到更多事件。K8s 里 apiserver 对每种资源用独立的 /registry/<resource>/ 前缀,prefix watch 精确落到该资源、互不串扰;只有少数需要联动变化的资源(如 service 与 endpoints)会在 watch 范围上做额外设计。选对范围既决定客户端处理量,也决定 etcd 扇出规模(13.2 节的主题)。

事件类型与全局 revision:PUT、DELETE 与事件序列

服务端推送的每个事件都有一个类型和一个 revision:

事件类型含义事件内容
PUT键写入或值更新key、新 value、mod_revision
DELETE键删除key、空 value、mod_revision(删除时刻)

每个事件都挂着一个全局单调的 revision——它不是某个键自己的序号,而是整个 etcd 的主 revision。第 12.1 节说过,每次写操作都推进主 revision,所以事件序列天然全局有序:revision 小的先发生、revision 大的后发生,顺序由 revision 唯一确定。两个客户端即使在不同时间启动 watch,只要订阅同一区间,拿到的都是同一份按 revision 排序的事件序列——顺序是协议保证的,不依赖网络到达次序。

一次 Put("k","v1")、Delete("k")、Put("k","v2") 会产生三个事件:

操作事件类型事件 revision
Put k=v1PUT1
Delete kDELETE2
Put k=v2PUT3

这段事件序列本身就是键 k 的完整变更历史:先写、再删、又写。任意从 rev 1 开始 watch 的客户端,都会按 1、2、3 的顺序收到这三个事件,不多不少。这就是「事件序列即该 key 的变更历史」的含义——watch 把 mvcc 里那条版本链(第 12.1 节的版本树)以事件的形式线性地推给客户端。DELETE 事件在 mvcc 层面对应的是墓碑版本:第 12.1 节里删除不立即清数据、而是追加一个 Deleted 版本,这个版本在 watch 上就表现为一条 DELETE 事件;历史读 GetAtRev 还能读到删除前的值,而 watch 客户端只会收到删除本身,两者分工不同但共享同一 revision。

prev_kv 是可选项:请求时打开,PUT 事件会带上变更前的值,DELETE 事件会带上被删掉的值。对需要「变化前后对比」的消费端(审计、控制器做 diff)很有用;默认关闭以省流量。

事件排序是全局的,不限于单个键:k1@1、k2@2 里 k2 的写入发生在 k1 之后,watch 客户端看到的顺序就是 k1 先、k2 后。跨键排序的意义在于——控制器常同时 watch 多个前缀,它们共享同一条全局 revision 序列,因此「先看到哪个事件」是确定性的,不会因为并发网络到达而错乱。这和第 12.1 节「revision 全局单调」的模型严格对应:事件流只是把版本树的增长顺序线性化而已。

backlog 追平:回放历史、衔接实时

如果创建 watch 时 start_revision 落后于当前 revision,服务端要先做一件事:把该 revision 之后已经发生的历史事件回放给客户端。这段回放就叫 backlog 追平。

回放的规则很简单:凡是 revision ≥ start_revision 的事件,都按 revision 升序推给客户端。例如写入 a@1、b@2、c@3 之后,从 rev 2 创建 watch,服务端立刻回放 b@2、c@3 两个事件;客户端追平到当前 revision 3 之后,订阅转入实时阶段——此后新写入 d@4,客户端收到 d@4,并持续如此。

关键性质是事件永不重复:每个事件只出现在它自己的 revision 上,回放与实时两条路径用 revision 边界切开,互不重叠。追平阶段收 [fromRev, now],实时阶段收 (now, ∞),两段的并集恰好是 [fromRev, ∞),一个不漏、一个不重。etcd 服务端用「unsynced / synced」两集合实现这个语义:落后 watcher 先在 unsynced 集合里批量补历史,补到与当前对齐后进入 synced 集合,之后靠事件广播直接推送。落点一个客户端视角的反省:既然事件流能追平历史,List 其实可以做得更轻——informer 首次同步时 List 快照,之后全靠 watch 增量维护本地缓存,正是吃满这个语义。

用一条时间线看「追平 → 实时」的切换:

rev:    1      2      3      4      5
操作:  写a    写b    写c   创建watch   写d
事件: [a@1] [b@2] [c@3] 回放b@2,c@3  [d@4]
                       (backlog追平)  (实时)

注意回放与实时在客户端看来是同一段连续的事件流——客户端并不需要区分哪些来自回放、哪些来自实时,只要按 revision 顺序消费即可。回放与实时的区分只是服务端内部实现细节(unsynced 集合处理回放、synced 集合处理实时广播),对协议语义没有影响。

实现追平还有一个细节:回放与实时共用同一条事件通道,客户端没消费完回放事件时,新到的实时事件会在通道里排队、不会插队。这保证客户端看到的顺序严格等于 revision 顺序——回放没读完,实时事件不会越过回放边界。这也解释了 13.2 节为什么慢消费者会积压:客户端不消费,回放与实时都在通道里堆着,直到越过服务端的容忍上限。

追平还有一个实现层面的注意点:回放是批量读事件,不是逐条实时。etcd 从 mvcc 后端按 revision 区间一次捞一批事件再分发给 unsynced 的 watcher,避免每个 watcher 都去后端逐条翻日志。批量粒度由服务端控制,客户端不需要感知——它看到的仍是一条按 revision 有序的连续流。

compact 断流:410 Gone 与重建协议

追平有一个前提:历史事件还在。第 9.3 节讲过 mvcc 压缩——auto-compaction 或手动 etcdctl compact 会把压缩点之前的 revision 全部丢弃。如果客户端请求的 start_revision 已经落在压缩点及之前,服务端无法回放,watch 直接失败,错误是 ErrCompacted(错误信息为 etcdserver: mvcc: required revision has been compacted,在 K8s 语义里对应 410 Gone)。

对客户端来说,这个错误不是「重试一下就好」,而是「起点已经不存在了」。正确的恢复协议是三步:

  1. 重新 List:拿一份最新全量快照,记录新的 revision rv1;
  2. 重建 watch:从 rv1 + 1 重新创建 watch;
  3. 继续增量:追平后恢复正常订阅。

etcd 在压缩时还会在响应里带上 compact_revision 字段,告诉客户端「现在压缩到哪个点了」,客户端可以据此判断自己的落后程度。K8s 的 informer 收到 410 后也是强制 relist 全量再重建 watch——功能上能自愈,但一次全量 relist 在大型集群里是数千个对象的下载成本,所以运维上把 auto-compaction retention 调到覆盖 watch 最长重连窗口(第 9.3 节的 8h 经验值),就是为了尽量不触发这条路径。

一个值得注意的边界:压缩断流不只是「老旧 watch」的问题。新建 watch 时如果客户端错误地用了已被压缩的 revision 做起点,同样会失败——比如 etcdctl compact 100 之后又把 --rev=50 传给 watch。判断起点是否有效只看一条不等式:起点 ≤ compact_revision 必败,起点 = compact_revision + 1 起才有保障。这也是 13.3 节重连协议里「总是先 relist 再重建」的动机:不依赖「历史还在」,就永远不会踩这条不等式。

watch 与 mvcc 版本树:事件日志就是变更日志

把 12.1 的版本树和本节的事件流放在一起看,会发现它们是同一个存储的两个投影。

  • 静态视角(12.1 mvcc):每个键拥有一条按 revision 升序的版本链,删除追加墓碑,GetAtRev 沿链回溯到任意历史点;
  • 动态视角(本节 watch):版本链上每一次「链的增长」(写)或「墓碑的追加」(删)被抽成一个事件,按 revision 顺序推给订阅者。

也就是说,watch 消费的就是 mvcc 的事件日志——它不是另一份数据,而是 mvcc 变更日志的流式出口。第 12.1 节里 Put 返回的 mod_revision、第 12.3 节里 K8s 对象身上的 resourceVersion,与这里事件的 revision 是同一个数字:写一个键产生一次 mvcc 变更,同时产生一个 watch 事件,revision 一致,三处对得上。

放到 K8s 数据模型(第 11.3 节)里看更具体:apiserver 对 /registry/pods/ 前缀做的每次写(创建、更新、删除 Pod)都在 mvcc 里产生一个事件;informer 的 watch 订阅的就是这条前缀上的事件流。所以 watch 协议本质上是在问:「在这个 key 区间里,从某个 revision 之后,mvcc 的版本树上发生了什么?」——服务端把答案按版本顺序说清楚,客户端就得到一份不丢不重的增量视图。而压缩断流(上一节)正是这个回答被历史回收打断时的边界情况,二者是同一枚硬币的两面。

把三处数字的对应关系列出来,方便对照:

位置数字含义
12.1 版本树mod_revision某键某版本挂的主 revision
12.3 resourceVersionrv对象最后一次变更的 mod_revision
13.1 watch 事件Event.Rev事件发生时的主 revision

三者是同一个值:写一个键,mvcc 在版本链上追加一个带 mod_revision 的版本,apiserver 把 mod_revision 写进对象的 resourceVersion 字段,watch 服务端把这次变更包装成带同号 revision 的事件。客户端无论走历史读、读对象还是收增量,坐标始终一致——这是整个 list-watch 机制能对齐的前提,也是 13.3 节断连续读能够「按 revision 续上」的根因。

本节 lab

本节三个用例在 private/labs/k8s-etcd-lab/watcher/:

  • TestWatchFromRevisionReplaysHistory:验证 backlog 追平——写入 a@1、b@2、c@3 后从 rev 2 创建 watch,回放得到 b@2 与 c@3 两个事件;
  • TestWatchPutDeleteEventSequence:验证事件序列——Put、Delete、Put 三个操作产生 PUT/DELETE/PUT 事件,revision 分别为 1/2/3;
  • TestWatchCompactionRejectsLaggard:验证压缩断流——Compact(2) 后从 rev 1 创建 watch 返回 ErrCompacted,从 rev 3 创建则正常。

运行命令:

cd private/labs/k8s-etcd-lab
go test ./watcher -run 'TestWatchFromRevisionReplaysHistory|TestWatchPutDeleteEventSequence|TestWatchCompactionRejectsLaggard' -v

预期断言:

  • 回放用例:从 rev 2 回放必须得到恰好 2 个事件,第一个 rev=2(键 b)、第二个 rev=3(键 c);
  • 事件序列用例:三个事件类型必须依次是 PUT、DELETE、PUT,revision 必须依次是 1、2、3;
  • 压缩用例:Watch(1) 必须返回 ErrCompacted(起点 1 落在压缩点 2 及之前),Watch(3) 必须成功且不报错。

三条全过即表示 watch 的版本区间、事件序列、backlog 追平与 compact 断流语义均符合本节描述。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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