《Kubernetes 分布式系统原理深入解析》12.1 读路径:客户端缓存/apiserver/etcd 三层

Kubernetes 的读请求可在三层命中:客户端 informer 缓存、apiserver 的 watch 缓存、etcd 的多数派读。层越深越新、越慢越贵;Fresh 判定用 seenRV ≥ writtenRV 判断读到的版本是否已包含某次写。本节剖析三层各自维护的 resourceVersion、watch 增量推进与 Fresh 判定,并用 readpath 包的 ReadPath 验证三层排序与写后新鲜度。

12.1 读路径:客户端缓存/apiserver/etcd 三层

前面各章讲了很多「写入」的路径:写进 etcd、调谐收敛、跨集群分发。但用户和控制器每天执行的大部分操作是读。一个 kubectl get 落到哪里、一个 informer 返回的数据多新,决定了「你看到的状态」离「真实状态」有多远。本节把读路径拆成三层:客户端 informer 缓存、apiserver 的 watch 缓存、etcd 的多数派读——层越深越新、越慢越贵,并用 Fresh 判定精确回答「读到的版本是否已包含某次写」。读完你应当能判断:一次读到底走了哪一层,它离真实状态有多远。

读请求能命中的三个层次

一个典型的读请求(控制器调 List、用户敲 kubectl get)在语义上可以落在三层:

层谁在维护读到多新成本
客户端缓存informer 本地 list-watch最后一次 watch 事件推进到的版本最快,内存读
apiserver 缓存apiserver 内的 watch 缓存(etcd v3 的 MVCC 读)请求时刻 apiserver 已同步到的版本中,一次 RPC
etcdetcd 多数派读当前最新提交版本最慢最贵,跨节点往返

lab 的 ReadPath 用三个 RV(revision)字段记录三层各自同步到的版本:ClientRV、ServerRV、EtcdRV。三者满足 ClientRV ≤ ServerRV ≤ EtcdRV 的单调关系——客户端缓存的版本不可能比 etcd 更新。Read(layer) 按策略返回对应层的 RV。

为什么会有三层

三层不是重复建设,而是各自解决一类问题:

  • 客户端缓存解决「高频读不压 apiserver」。控制器每调谐一轮要读几千个对象,若都打到 apiserver/etcd,控制面立刻成为瓶颈。informer 把对象缓存在本地,读是内存操作,代价趋近于零——代价是读到的版本滞后于 watch 流。
  • apiserver 缓存解决「各客户端共享一份最新视图」。apiserver 用 watch 缓存服务 List,多个客户端从同一份缓存读到一致的版本,不必各自打 etcd。它是三层里最常用的「真读」——kubectl get 默认走这里。
  • etcd 多数派读解决「必须读到最新提交」。依赖 watch 缓存的读可能读到旧版本,需要绝对新鲜的场景(如校验写前置条件、查证某对象确实存在)直接读 etcd。

三层的取舍本质是**「新鲜度 × 成本」的滑尺**:内存读几乎免费但可能旧,etcd 读最新但每次都要跨多数派往返。工程上默认用前两层,把 etcd 读留给「必须新」的少数场景。

层越深越新:revision 的单调性

为什么层越深越新?因为每一层都是「上层缓存 + 增量同步」的结构,增量同步永远滞后于写入源头:

写路径:客户端 → apiserver → etcd 提交(revision N)
读路径:etcd(N)  → apiserver 缓存(≤N) → informer 缓存(≤apiserver 缓存)

写入先到 etcd 拿到全局递增的 revision,apiserver 的 watch 缓存随后推进到 N,informer 又通过 watch 流推进到 N。推进是异步的,所以任何一层的 RV 都可能小于 N。lab 里 ReadPath{ClientRV:10, ServerRV:15, EtcdRV:17} 展示的就是这个结构:17 是最新提交,15 是 apiserver 已看到的,10 是客户端缓存已同步到的。

这个单调结构带来一个工程习惯:判断「哪个层更可信」看 RV 大小即可,不需要额外的元数据。RV 是 apiserver 全局单调递增的,大者必然更新(前提是同一 apiserver/同一 etcd 集群,跨集群的 RV 不可比——这正是第 10 章联邦要单独记账版本的原因)。

watch 增量推进:客户端缓存如何变新

客户端缓存不是凭空变新的,它靠 watch 流的增量事件推进。每次收到一个 watch 事件(对象被创建/更新/删除),informer 把事件里的 resourceVersion 应用进本地缓存:

func (p *ReadPath) ApplyWatch(rv int64) {
    if rv > p.ClientRV {
        p.ClientRV = rv
    }
}

这个函数的两个特性值得注意:

  • 只前进不后退:if rv > p.ClientRV 保证过期/乱序的 watch 事件不会把缓存拉回旧版本。watch 流重连时可能重发旧事件,若不加这个判断,缓存会「倒退」,读者会看到已经失效的状态。
  • 事件驱动:缓存的更新完全由事件流驱动,不需要客户端主动去 apiserver 查询。这就是 informer 的 list-watch 模型——初次 List 建立基线,此后全靠 Watch 增量。

lab 的 TestWatchIncrementalSync 演示了完整过程:缓存 RV=10,ApplyWatch(13) 推进到 13,ApplyWatch(16) 推进到 16,乱序的 ApplyWatch(5) 被拒绝。缓存的新鲜度上限由「最近一个已处理事件」决定——事件流断了,缓存就停在断点。

informer 的 resync:缓存不会自我修正

客户端缓存有一个被低估的特性:它不会自我修正。如果一个 watch 事件丢了,informer 缓存就永久停留在那个缺失事件之前的版本——没有「定期去 apiserver 对账」的机制,缓存里的对象会一直保持错误状态。这就是 informer 需要 ResyncPeriod 的原因:每过一段时间,informer 把本地缓存里的对象与 apiserver 的最新版本重新 List 一次并逐项比对,把缓存修正到与服务器一致。

resync 的正确性依赖于 list 的返回是「全量快照」:informer 用服务器返回的完整对象集合覆盖本地缓存,把漏掉的事件补齐。代价是重 List 的体积——几千个对象全量拉一次,落在 apiserver 上是一次不小的读放大。resync 周期是「缓存新鲜度」与「读放大」之间的权衡:周期短则缓存更可靠但 apiserver 压力大,周期长则省流量但漏事件后的自愈更慢。生产上常见的做法是给不同对象配置不同 resync 周期——变化频繁的(如 Pod)短一点,几乎不变的(如 ConfigMap)可以拉长甚至禁止 resync。

断流重连:watch 恢复的一致性

watch 流不是永久可靠的,网络断、apiserver 重启都会断流。informer 的恢复策略值得单独讲,因为它决定了「断流期间丢的事件怎么补」。标准做法是带版本重连:断流时记下最后收到的 resourceVersion,重连后用 List 从那个版本开始重新拉一遍——List 请求带上 resourceVersion 参数,apiserver 返回「该版本之后的所有变化」:

kubectl get pods --watch --resource-version=123456

恢复的一致性由两个机制保证:

  • etcd 的 MVCC 保留:etcd 保留历史 revision 一段时间(--max-request-bytes 与压缩窗口之内),断流期间的旧事件还能被读出。
  • 版本回退兜底:如果请求的 resourceVersion 已经因为压缩不可用(第 9.3 节讲过 etcd 压缩),服务器返回 410 Gone,客户端被迫全量重 List 建立新基线。

所以断流重连的正确性边界是「事件保留窗口」:断流时间短于保留窗口,带版本重连能补齐;长于保留窗口,只能全量重建。这与第 9.3 节 etcd 快照/恢复的窗口概念同源——任何「从某版本继续」的机制都依赖上游还留着那段历史。

Fresh 判定:读到的版本是否包含某次写

三层各有各的 RV,但业务真正关心的问题只有一个:我读到的这个对象,是不是已经包含了某次我关心的写。 Fresh(seenRV, writtenRV) 给出精确判据:

func Fresh(seenRV, writtenRV int64) bool { return seenRV >= writtenRV }

一次写成功后,写入方拿到该写落库的 revision(writtenRV)。之后任何读,只要它的 seenRV >= writtenRV,就保证「这次读看到了那次写」——不管读的是客户端缓存还是 apiserver 缓存。反之,seenRV < writtenRV 则这次读不包含该写,读到的是旧视图。

Fresh 的威力在于它把「新不新」从「感受」变成「可比较的版本号」:

读层seenRVwrittenRV=16 时
etcd16新鲜,包含写
apiserver 缓存16新鲜,包含写
客户端缓存12不新鲜,未包含写

注意 Fresh 判断的是「是否包含某次写」,而不是「是否是最新」——最新是一个持续漂移的目标,包含某次写是一个可验证的事实。判断新鲜度要用版本比较,不要用「过了多久」:时间不能告诉你缓存是否同步到了那个版本,revision 可以。

什么时候用哪一层

把三层读放进常见场景,选择就清晰了:

场景推荐读层理由
控制器调谐循环读对象客户端缓存高频、可容忍秒级滞后
kubectl get 查状态apiserver 缓存默认路径,足够新
写前置条件检查(乐观锁)etcd 读 + RV 校验必须读到最新提交
校验对象确实不存在etcd 读缓存可能漏掉删除事件
一次读到一致快照apiserver 缓存(单次 List)watch 缓存保证同一时刻视图
跨资源关联查询客户端缓存(多 informer)各 informer 并发维护,关联无需打服务器

「用 etcd 读」不是默认选择,而是有明确理由的选择。第 12.2 节会进一步说明:写确认返回的 RV 必须配合同一层级的读才能验证「写已生效」——如果写后立刻用滞后严重的客户端缓存去读,即使 Fresh 判定失败,也不代表写没发生,只是读层太旧。

读层的选择还有一个「一致性级别」的侧面:客户端缓存与 apiserver 缓存都是最终一致的视图,只有 etcd 多数派读提供线性一致的「已提交即读到」保证。需要线性一致的场景(选主校验、配额扣减前的读)绝不能走缓存层——这是把「新鲜度」换成「一致性」的另一种表述。

这里还藏着一个经典问题:「写后读」(read-your-writes)为什么需要走对层。写入方拿到写返回的 writtenRV 后,若想立刻验证写的结果,读层必须满足 seenRV >= writtenRV。读 apiserver 缓存通常满足(写与读经过同一 apiserver 的同一序列),读客户端缓存则未必——informer 的 watch 可能还没推进到那个版本。验证自己刚写的写,绕开客户端缓存,是控制器代码里最常见的正确性习惯之一。

读路径的延迟预算

把三层读放到一次控制器调谐里,延迟预算可以这样分配:

读操作层单次延迟量级调谐循环里的占比
列对象清单客户端缓存微秒~毫秒主力,占绝大多数读
查单个对象最新状态apiserver 缓存毫秒少数,用于决策
乐观锁前置读etcd数毫秒~数十毫秒极少,只有写前必读

这个预算的价值在于:绝大多数控制器读应该命中客户端缓存,否则调谐循环就会被读路径拖垮。如果发现一个控制器大量读打到 apiserver 甚至 etcd,先检查是不是 informer 缓存没被正确使用——最典型的反模式是「每次调谐都直接 Get 而非 Lister().Get」,把缓存白白晾在一边。

预算也指导「缓存不可用时怎么办」:控制器启动时 informer 先做一轮全量 List 才对外可用,这段时间读会退化成 apiserver 读;高可用设计通常让控制器等缓存就绪(sync 完成)再开始调谐,而不是依赖永远可用的 apiserver 直读。

三个常见误解

  • 「kubectl get 读到的就是 etcd 里的最新状态,肯定是最新的」——错误。kubectl get 默认走 apiserver 的 watch 缓存读,读到的是请求时刻 apiserver 已同步的版本,可能落后于 etcd 最新提交。
  • 「客户端缓存和 apiserver 缓存是同步更新的,要么都新要么都旧」——错误。informer 缓存由 watch 事件流独立推进,通常滞后于 apiserver 缓存;三层各维护自己的 revision,互不保证同时刻一致。
  • 「过了几秒再读就一定读到新值,时间能当新鲜度判据」——错误。新鲜度只能用版本号比较(seenRV >= writtenRV),时间流逝不代表缓存已经同步到了那个版本。

一句话总结本节

读路径按「客户端缓存 / apiserver 缓存 / etcd 多数派读」分层,层越深越新、越慢越贵;informer 用只进不退的 watch 增量推进本地缓存,Fresh(seenRV ≥ writtenRV) 用版本比较判定读到的状态是否包含某次写。判断新旧的正确工具是 resourceVersion,不是时间。

下一节回答「写」的另一半:apiserver 返回写确认,离真正生效还有多远。

本节 lab

本节的两个测试落在 readpath 包的 ReadPath 与 Fresh 上,验证「三层排序」与「写后新鲜度」两条语义:

cd private/labs/k8s-net-lab
go test ./readpath -run TestReadThreeLayersOrdering -v
go test ./readpath -run TestReadFreshAfterWrite -v

两个测试各自独立验证一面:TestReadThreeLayersOrdering 验证「三层的相对新旧」,TestReadFreshAfterWrite 验证「版本比较如何判定新鲜」。

  • TestReadThreeLayersOrdering:ReadPath{ClientRV:10, ServerRV:15, EtcdRV:17},分别 Read(LayerClientCache)、Read(LayerServerCache)、Read(LayerEtcd),断言依次返回 10、15、17——3 条断言,对应「客户端缓存最旧、apiserver 次之、etcd 最新」。
  • TestReadFreshAfterWrite:写返回 RV=16,ServerRV=16 的 apiserver 读断言 Fresh(…, 16) 为真(已包含写),ClientRV=12 的客户端缓存读断言 Fresh(…, 16) 为假(未包含写)——2 条断言,对应「层越深越新、Fresh 判定依赖 seenRV ≥ writtenRV」。

两个测试跑完见 ok k8s-net-lab/readpath。TestWatchIncrementalSync(第 12.3 节还会用它)补全了「缓存如何被推进」这一面,这里先留到 12.3 节细讲。这就是「三层读 + 版本比较」的读路径最小闭环。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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