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 坐标,才能无缝衔接。
| 步骤 | 手段 | 拿到什么 | 版本坐标 |
|---|---|---|---|
| 1 | List(带 resourceVersion) | 某一 revision 的全量快照 | rv0 |
| 2 | Watch(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 定义订阅的版本起点。
| 写法 | key | range_end | 订阅范围 |
|---|---|---|---|
| 单键 | /registry/pods/default/foo | 空 | 恰好这一个键 |
| 前缀 | /registry/pods/ | /registry/pods0 | 该前缀下的所有键 |
| 全范围 | /registry/pods/ | \0 | key 之后的所有键 |
前缀写法是 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_kv | PUT/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=v1 | PUT | 1 |
| Delete k | DELETE | 2 |
| Put k=v2 | PUT | 3 |
这段事件序列本身就是键 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)。
对客户端来说,这个错误不是「重试一下就好」,而是「起点已经不存在了」。正确的恢复协议是三步:
- 重新 List:拿一份最新全量快照,记录新的 revision
rv1; - 重建 watch:从
rv1 + 1重新创建 watch; - 继续增量:追平后恢复正常订阅。
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 resourceVersion | rv | 对象最后一次变更的 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 断流语义均符合本节描述。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。