《Kubernetes 分布式系统原理深入解析》3.1 list-watch 原语与增量同步

控制器订阅 apiserver 用的是一个原语:list-watch。先 List 拿全量快照与 resourceVersion,再 Watch 从该版本续增量事件;两者合起来保证『不漏、不重、不错』地维护本地缓存。本节拆解这个原语的协议、它为何用版本续接而非时间续接,以及它对缓存一致性的意义。lab 用 informer/source.go 与 reflector.go 验证 List 全量 + Watch 增量的同步。

3.1 list-watch 原语与增量同步

控制器怎么知道集群状态变了?答案不是轮询,而是一个叫 list-watch 的原语。它是卷二最重要的地基:几乎每个控制器、每个 informer、每次缓存同步,都在执行「先全量、再增量」的两段式订阅。

一个原语,两个动作

list-watch 分两步:

  1. List(全量):GET /apis/apps/v1/deployments?limit=500。拿到所有对象 + 响应头的 resourceVersion。这是「快照」。
  2. 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。它起到两个作用:

  1. 保活探测:确认长连接还通畅,防止「连接没断但已死」的静默黑洞。
  2. 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——「先全量、再增量」的最小验证。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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