《Kubernetes 分布式系统原理深入解析》10.3 etcd 各读模式对比与工程取舍

etcd v3 提供串行化读与线性一致读两种模式,差别只在读前是否走一次 ReadIndex 确认。本节给出客户端指定方式、延迟/吞吐对比与适用场景,分析 apiserver 直连 etcd 读为线性一致、watch cache 快照为弱一致,并给出 K8s 各读点的一致性选择框架。lab 用 TestLinearizableReadIndex 与第 2 章 TestEventualStaleReadWindow 对照两种读模式的行为。

10.3 etcd 各读模式对比与工程取舍

10.1 和 10.2 把线性一致读的原理讲清楚了:ReadIndex 用 commitIndex 边界 + 多数派确认实现,Lease Read 用时钟租约再省一次往返。本节回到 etcd 这个具体产品,把它的读模式全景、客户端如何指定、以及 K8s 里各层该怎么选读模式整理成工程决策框架。第 2 章已经用 consistency 包验证过线性一致与最终一致的行为差异,本节引用其结论,不再重复细节。

etcd v3 读模式全景

etcd v3 对外提供两种读模式,差异集中在「要不要等多数派确认」:

读模式英文路径是否可能 stale服务端动作
串行化读Serializable直接读本机 mvcc可能跳过确认
线性一致读LinearizableReadIndex 确认后读否先走读索引
  • 串行化读:请求不进共识路径,直接在收到请求的那个 etcd 成员上读本地 mvcc 存储。延迟最低、吞吐最高,但可能读到本机尚未同步到的最新提交。适用对「新」不敏感的场景。
  • 线性一致读:请求先走一轮 ReadIndex,等到多数派确认的已提交位置,再读本地 mvcc。读到的是「读发起前全部已提交写」的最新状态,代价是每读多一次多数派往返。

注意两者最终都在一个成员的本机读 mvcc——差别只在于读之前是否经过一次 ReadIndex 确认。这是理解 etcd 读延迟的关键:串行化读省掉的不是「读」,而是「确认」。

客户端如何指定读模式

三种常见入口,全部落在同一个 RangeRequest.serializable 字段上:

  1. Go 客户端 clientv3:默认线性一致;clientv3.WithSerializable() 开启串行化读。源码里注释写得很明确:“By default, it’s linearizable.”
  2. etcdctl 命令行:etcdctl get --consistency=s|l(简写 -n),默认 l(线性一致)。
  3. gRPC 直接调用:构造 RangeRequest 时显式设置 serializable 字段。

在 etcdserver/v3_server.go 的 Range 实现里,逻辑是一个 if:!r.Serializable 时先 linearizableReadNotify(ReadIndex 确认),否则直接读。整个分支就是两种模式的全部差别。

另外要注意:watch 是另一条路径,它消费事件流,不适用 Range 的两种读模式——watch 的新鲜度由事件序号保证,与读快照不是同一个维度。

Range 请求字段再确认

RangeRequest 是 etcd v3 所有键值读的载体,一致性相关的字段只有一个:serializable。proto 里的注释写得很直白:“Range requests are linearizable by default; linearizable requests have higher latency and lower throughput than serializable requests but reflect the current consensus of the cluster."——默认线性一致,串行化是「为了性能、换来可能读旧」的显式取舍。

这个字段在客户端有三种设置途径(前面列过),在服务端只有一个分支。理解这一点后,读模式的切换就完全透明了:不是两套读实现,而是同一条读路径在「要不要先确认」处的一个 if。

两种模式的延迟与吞吐

量化看差异:

  • 串行化读:一次成员内读,无额外往返。同可用区延迟通常亚毫秒到几毫秒,吞吐只受本地存储读限制。
  • 线性一致读:多一次 quorum 确认往返。多数派确认走心跳路径,跨机架/可用区时约一个网络 RTT(几毫秒)。在稳定的 3 节点集群里,线性一致读的延迟大约是串行化读 + 一个 RTT。

吞吐上,线性一致读的确认路径把每笔读挂到「一次心跳」粒度,批量读场景差距更明显。etcd 的实践数据是:串行化读能支撑高得多的读 QPS,线性一致读则与写路径共享多数派往返资源。所以 etcd 官方的建议里,监控、大盘、可容忍旧读的负载用串行化;一切「读到必须是最新」的负载用线性一致。

把差异浓缩成一张表:

场景串行化读线性一致读
成员内读0 额外往返0 + 一次确认往返
读 QPS 上限本地存储上限确认路径上限
跨可用区成员内延迟成员内 + 一个跨区 RTT
批量读每笔独立可共享一次确认
分区下的少数派成员仍响应(旧数据)确认失败(不可用)

最后一行把两种读模式放进故障场景,能看到它们对「可用性」的态度相反:串行化读宁可旧也要可用,线性一致读宁可失败也不返回旧值。

适用场景:什么时候用串行化读

串行化读的正确使用场景是「可以容忍几个毫秒到几个事件的旧」:

  • 监控指标、日志检索、容量大盘;
  • 客户端本地缓存的热身填充(先读旧值,再用 watch 追新);
  • 不需要做「写后读」校验的展示类查询。

而线性一致读用于「读到旧值会产生错误决策」的场景,例如:

  • 写后立刻读回(read-your-writes):写入成功返回后,同一客户端要立刻看到自己写的内容;
  • 唯一性 / 判等:判断某个键是否存在、某个名字是否被占用;
  • 带条件的决策:读取一个状态再基于它做下一步写。

从 Range 到 etcdserver 的完整路径

把一次 Range 读在 etcd 里的旅程走一遍(以 v3 实现为准):

  1. 客户端发起 Get,clientv3 构造 RangeRequest,serializable 取默认 false;
  2. gRPC 请求到达任意一个 etcd 成员,kvServer.Range 先做参数校验;
  3. 进入 EtcdServer.Range:!r.Serializable 时先 linearizableReadNotify(ReadIndex 确认),否则直接跳过;
  4. 确认完成后,调用 applyV3Base.Range 从 mvcc 存储读取;
  5. 带上响应头(含已确认的 revision)返回。

对比写路径(Leader 广播 → 多数派确认 → apply),读路径在第 3 步只做「确认边界」,不追加任何日志。整条路径里,serializable 只是把第 3 步跳过——两种模式共享 mvcc、共享 apply 后的状态机,差异被压缩到最小。

apiserver 的读取策略

Kubernetes apiserver 在 etcd 之上的读路径有两层,工程决策其实发生在「缓存 vs 直连」上,而不是在 etcd 的 serializable 选项上:

  1. 直连 etcd 的读是线性一致。apiserver 的 etcd3/store.go 里,Get 直接 KV.Get(ctx, key),List 在 pagingList 里 KV.Get(ctx, key, opts...)——两处都没有传 WithSerializable(),所以走 etcd 默认的线性一致读(以 k8s v1.23 源码为例)。单对象 Get(不带 resourceVersion)因此保证读到多数派已确认的最新状态。
  2. watch cache 快照是弱一致。apiserver 用 Cacher 包住 etcd 存储。不带 resourceVersion 的 List 默认由 watch cache 的快照服务——快照来自 watch 事件流,可能比 etcd 当前状态旧几个事件;带显式 resourceVersion、或需要续页回落存储时,才走 etcd 线性一致读。

所以「apiserver 读到旧值」的常见来源是 watch cache 和 informer 缓存,而不是 etcd 的串行化 Range。要区分这两个来源:直连读慢但准,缓存读快但旧。

apiserver 的 Cacher 对两种读的处理并不对称(以 k8s v1.23 源码为准):单对象 Get 在不带 resourceVersion 时直接回落底层存储,走 etcd 线性一致读;List 则默认由 watch cache 快照服务,只有带显式 resourceVersion、开启续页或 cache 尚未就绪时才回落 etcd。所以「单对象读线性一致、默认 List 弱一致」的差异真实存在,判断时要按资源类型和请求参数分别看,不能一概而论。

K8s 各场景该用哪种读

把 K8s 的读点过一遍,几乎每一种都能对应到上面的分类:

读点读路径一致性档位
kube-apiserver 单对象 Get直连 etcd线性一致
apiserver 带 RV 的 List回落 etcd线性一致
apiserver 默认 Listwatch cache 快照弱一致
informer / kubelet 缓存本地 store最终一致
etcdctl 手动查询默认 linearizable线性一致

控制器的大多数读走 informer 本地缓存,这是设计如此:调谐循环本来就是周期性的,容忍几秒滞后,靠 watch 事件 + 重试收敛。但一旦进入「决策点」(选主、判空、写后读),就必须回落线性一致读。

分区下的两种读

把两种读模式放到分区场景里看,能更清楚它们的差异:

  • 串行化读:请求在哪个成员就由哪个成员本机读。被分区到少数派的成员依然能响应读,返回的是过期数据——可用但旧。这正是 10.1 节旧 Leader 场景在「读模式」层面的表现:读的可用性不需要任何共识,代价就是一致性没有保证。
  • 线性一致读:确认需要多数派,被分区到少数派的成员无法完成 ReadIndex 确认,读会超时或失败——不可用但准。

这和第 2 章 CAP 的结论吻合:分区下「可用」与「线性一致」不可兼得。串行化读偏向可用(宁可旧),线性一致读偏向一致(宁可不可用)。工程上按读点对「旧」的容忍度选档位,就是这个取舍的日常形态。

一致性取舍的工程决策框架

把前面所有内容压缩成一个可复用的判断框架:

  1. 这个读会触发写吗? 会(先读后写、条件写)→ 线性一致;不会 → 看下一步。
  2. 读到旧值会伤害谁? 影响正确性(删了重建、调错节点)→ 线性一致;只影响展示(监控、列表)→ 串行化/缓存。
  3. 写后需要立刻可见吗? 需要(read-your-writes)→ 线性一致;允许异步传播 → 最终一致缓存。
  4. 延迟预算? 读 QPS 高且可容忍旧 → 串行化读或本地缓存;必须新 → 接受一次多数派往返。

这个框架呼应第 2 章的结论:一致性是有成本的,线性一致读比串行化读每笔多一次 quorum 往返;分布式系统的工程艺术在于把「必须新」的读和「可容忍旧」的读分开,而不是一刀切。etcd 用 ReadIndex 把「线性一致读」的成本压到一次心跳往返,已经是这个方向上的最优解之一。

决策框架实例演练

拿三个真实场景走一遍框架:

  1. Deployment 控制器读副本数:这个读不直接触发写,但读到旧副本数会导致错误扩缩容——影响正确性。所以控制器用 informer 缓存做周期调谐(容忍旧),但在执行一步具体的状态变更前,会基于相对新的版本计算差异,必要时回落 apiserver 的线性一致读。结论是「周期读用缓存、变更读用线性一致」。
  2. Namespace 终结器清空:控制器要确认 namespace 里的资源确实删空,才移除终结器、允许 namespace 消失。如果读到旧值、以为资源还残留,namespace 会永远卡在 Terminating——这是「读到旧值会伤害正确性」的典型,必须线性一致读。
  3. 监控大盘展示 Pod 数:只影响展示,容忍几秒旧 → 串行化读或 informer 缓存即可,不值得为它付出每笔一次多数派往返。

这三个例子覆盖了框架的四个问题:读会不会触发写、旧值伤不伤害正确性、要不要 read-your-writes、延迟预算够不够。

本节 lab

本节同时引用两个 lab 验证两种读模式的行为边界:

  • private/labs/k8s-etcd-lab/raft/ 的 TestLinearizableReadIndex:展示线性一致读返回 commitIndex 作为读边界,未提交日志不参与读。
  • private/labs/k8s-etcd-lab/consistency/models_test.go 的 TestEventualStaleReadWindow:展示最终一致(等价于本机读)存在旧读窗口,随后收敛。

运行命令:

cd private/labs/k8s-etcd-lab
go test ./raft -run TestLinearizableReadIndex -v
go test ./consistency -run TestEventualStaleReadWindow -v

预期断言:

  • TestLinearizableReadIndex:Leader 用 CommitIndex 回答 ReadIndex 请求,返回的读边界只包含已提交日志;
  • TestEventualStaleReadWindow:副本 0 的传播延迟为 5 tick,写入 v2 后仅过 1 tick,副本 0 必须能读到旧值(证明旧读窗口存在);传播完成后必须读到 v2(证明最终收敛)。

前者是线性一致读的边界语义,后者是串行化/本机读的旧窗口——两个测试合起来,正好覆盖本节「两种读模式 + 取舍」的全部行为。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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