3.1 list-watch 原语与增量同步
控制器怎么知道集群状态变了?答案不是轮询,而是一个叫 list-watch 的原语。它是卷二最重要的地基:几乎每个控制器、每个 informer、每次缓存同步,都在执行「先全量、再增量」的两段式订阅。
一个原语,两个动作
list-watch 分两步:
- List(全量):
GET /apis/apps/v1/deployments?limit=500。拿到所有对象 + 响应头的resourceVersion。这是「快照」。 - Watch(增量):
GET /apis/apps/v1/watch/deployments?resourceVersion=<上一步的 RV>。之后 apiserver 持续推送「对象变了」的事件(Added/Modified/Deleted),每条都带新 RV。
两步合起来回答一个问题:从这一刻起,集群里发生了什么? List 建立起点,Watch 跟踪后续。
为什么用「版本」续接而不是「时间」
Watch 的起点是 resourceVersion,不是时间戳。这个选择很关键:
- 版本是单调的、可比较的:RV 序列是 etcd 的 mvcc revision,任何两次读都知道谁先谁后。
- 时间戳不可靠:不同机器时钟不同步(卷一第 3 章),事件与事件之间无法用墙钟排序。
- 版本可以「续」:我 List 到 RV=100,watch 从 100 开始,保证「100 之后的变化我全收到」——不重不漏。
List + Watch 的衔接保证:任何在 List 之后发生、且在 List 响应 RV 之后提交的写,都会以事件形式出现在 Watch 流里。因为事件按 RV 顺序推送,从 List 的 RV 起点看,之后的每个写都有事件。这就是「不漏」的证明。
增量同步的三种事件
Watch 流里的对象带三种事件类型:
| 类型 | 含义 | 控制器动作 |
|---|---|---|
| Added | 对象新创建 | 入队 reconcile |
| Modified | 对象被更新 | 入队 reconcile |
| Deleted | 对象被删除 | 清理、入队 reconcile |
控制器把每个事件对应的 key 塞进 workqueue(卷二第 6 章),worker 取出后读取最新状态并调谐。注意:控制器不直接处理事件内容,而是把事件当作「重试信号」。这是 informer 与命令式事件处理的最大区别——事件只是告诉你「有个 key 需要看」,具体看什么由 reconcile 决定。
缓存:从事件流重建本地视图
list-watch 的最终产物不是事件本身,而是本地缓存:
List 全量 → 构建初始缓存
Watch 增量 → 更新缓存(增/改/删)
控制器读 → 读缓存而非每次都打 apiserver
这套设计的好处:
- 读放大消失:控制器每个周期都读集群状态,如果每次读都打 apiserver,数千控制器 × 数千对象 = 打爆。读本地缓存近乎免费。
- 写放大被抑制:控制器只在自己需要时写 apiserver。
- 事件驱动:有变化才调谐,没有变化不空转。
代价是缓存滞后(卷二 3.3 节):控制器看到的状态可能比 etcd 晚几毫秒到几秒。
list-watch 与分页的关系
上一节(1.2)讲的分页 continue 令牌,与 list-watch 的 RV 是同一个模型的两种形态:
- 分页的 continue:List 内部的断点续传。
- list-watch 的 RV:List 到 Watch 之间的断点续传。
两者都源自 etcd 的 key 前缀 + mvcc revision。这印证了卷二的观察:apiserver 的一切「集合语义」都是 etcd 前缀 + revision 的翻译。
watch 的一致性保证:从哪个版本开始
list-watch 的「不漏」依赖一个关键协议细节:watch 从 List 响应的 RV 开始,事件严格按 RV 单调推进。
设 List 返回 RV=100。watch 从 100 开始后,发生的任何写(revision 101、102、…)都会以事件形式推送。这条保证来自 etcd:apiserver 的 watch 本身就是对 etcd 的前缀 watch,etcd 保证「从 revision 100 之后,每个提交至少出现一次」。
三种可能的起点:
| 起点 | 行为 | 风险 |
|---|---|---|
| 空(不指定 RV) | 从当前最新开始,之前的全量靠 List 补 | 无 |
| List 响应的 RV | 标准续接,不重不漏 | 无 |
| 过期的旧 RV | 事件已压缩(Compact)→ 410 Gone | 需 relist |
第三种情况值得展开:etcd 会定期压缩历史 revision(如保留最近 5 分钟)。如果客户端用一个很旧的 RV 去 watch,etcd 找不到起点,返回 410 Gone。informer 收到 410 的正确反应不是重试 watch,而是重新 List(3.3 节)。这就是「relist 退避」在协议层的触发条件之一。
list 的边界:快照与分页的关系
List 响应是一次「一致性快照」吗?严格说不是——一个大集合的 List 要跨多次分页请求(1.2 节 continue 令牌),每次分页之间对象可能变化。所以 List 的 RV 是「响应时刻」的版本,不是「List 开始时刻」的版本。
实际语义:List 返回的 RV 保证「返回那一刻」之后的变化都能被后续 watch 覆盖。客户端把它当 watch 起点即可,不必纠结「List 是否线性一致」。这正是声明式系统容忍滞后、依赖最终一致的又一次体现:起点不必是最新,只要后续能续上。
list-watch 与轮询的成本对比
「为什么不直接轮询?」是理解 list-watch 价值的最后一块拼图。轮询与事件推送的成本差距:
| 对比项 | 轮询 | list-watch |
|---|---|---|
| 请求频率 | 固定间隔(如 30s) | 只在变化时推送 |
| 数据量 | 每次都拉全量 | List 一次全量 + 之后增量 |
| 时效 | 平均半个周期(15s) | 毫秒~百毫秒 |
| 服务器压力 | 与对象数 × 轮询者成正比 | 与变化数成正比 |
放大到数千控制器:轮询模式下每个控制器每 30s 拉一次全量,apiserver 每秒要处理数千次大 List;list-watch 模式下每个资源只有一条 watch 连接,只在变化时产生流量。事件驱动不是「更优雅」,而是「数量级更省」——这正是 informer 成为标准的原因。
三个常见误解
- 「Watch 会丢事件,所以要定时轮询」——错误。list-watch 设计上不丢(从 List RV 续接),但连接可能断(网络/超时);断连时 informer 会重新 List(relist),卷二 3.3 节讲退避。
- 「控制器处理每个事件」——错误。控制器只把 key 入队,reconcile 时重新读;同一个 key 的多次事件在队列里去重(卷二 6.1 节)。
- 「缓存与 etcd 永远一致」——错误。缓存是异步的,有滞后;「多新」取决于 watch 传播延迟。这决定了控制器的「当前状态」永远是「某个时刻的快照」。
事件类型之外:watch 的簿记事件
watch 流里不只有 Added/Modified/Deleted,还有簿记事件。理解它们能解释 informer 的一些「看起来多余」的行为:
| 事件类型 | 含义 | 控制器是否入队 |
|---|---|---|
| Added / Modified / Deleted | 对象变化 | 是 |
| BOOKMARK | 周期性确认「watch 还活着」 | 否 |
| ERROR(如 410 Gone) | 起点失效 | 否(触发 relist) |
BOOKMARK 事件是 K8s 对「watch 静默断连」的回应:apiserver 会定期(默认 5 分钟)发送一条不带数据、只带当前 RV 的 BOOKMARK。它起到两个作用:
- 保活探测:确认长连接还通畅,防止「连接没断但已死」的静默黑洞。
- RV 锚点刷新:客户端知道「最新 RV 到哪了」,即使没有任何对象变化。
控制器收到 BOOKMARK 不做事(不入队),但它证明了 watch 链路的健康。没有 BOOKMARK,一个无声断开的 watch 会让 informer 误以为「集群很安静」——直到 relist 才发现丢了一大段。
watch 的三种断连与客户端的反应
| 断连方式 | 表现 | informer 反应 |
|---|---|---|
| 网络断开 | 读超时、连接关闭 | relist |
| 410 Gone | 起点已压缩 | relist |
| 服务端超时 | 连接被 apiserver 主动关 | relist |
三种断连的最终反应都是 relist——因为增量续接的起点不可信了。这也是 3.3 节「断连即全量重建」的协议级原因。可以这样记:增量是优化的路径,全量是兜底的正确路径;任何增量不可续,就回到全量。
RV 从哪来:List 响应头与 watch 事件头
RV 在协议里出现在两个位置,语义不同:
| 位置 | 形式 | 含义 |
|---|---|---|
| List 响应头 | metadata.resourceVersion | 本次快照的版本 |
| 对象体内 | 每个对象的 resourceVersion | 该对象的写入版本 |
| watch 事件头 | 事件的 RV | 事件顺序编号 |
控制器的续接用「List 响应头的 RV」作起点,不是用「某个对象的 RV」。区别在于:对象 RV 是「最后一次写它的版本」,可能比快照旧;快照 RV 是「整个集合读到的最新版本」。用错起点会漏事件——比如用了一个更旧的 RV 续接,watch 会重复推送,或(更糟)起点被压缩报 410。续接永远用响应级 RV,这是 informer 内部处理好的细节,但理解它有助于排查「watch 重复/丢失」类问题。
watch 事件的幂等性
控制器收到重复的 Modified 事件会怎样?答案是「无害」。因为控制器只把 key 入队,reconcile 时重新读取最新状态——重复事件最多导致一次多余入队(被 DeltaFIFO 去重),不会产生错误动作。这给了 watch 设计自由度:事件可以重复,但不能丢失。apiserver 在某些边界情况下(如内部缓存重建)可能重发事件,客户端必须容忍;而「不能丢失」由 relist 兜底。这是 3.1 节「不漏不重」的精确版本:不漏是硬保证,不重是软保证。
本节 lab
本节验证 list-watch 的两段式同步:List 全量进 FIFO、Watch 增量追加:
cd private/labs/k8s-ctrl-lab
go test ./informer -run 'TestListSync|TestWatchIncremental' -v
TestListSync:List 全量后 FIFO 中每个对象一条 Sync 增量,HasSynced=true。TestWatchIncremental:消费完 List 全量后,新创建的对象经 watch 进入 FIFO,类型为 Added——「先全量、再增量」的最小验证。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。