《Kubernetes 分布式系统原理深入解析》11.3 etcd 与 K8s 数据模型映射
K8s 把全部资源对象以序列化 JSON 单 key 单对象存进 etcd,key 布局为 /registry/组/资源/命名空间/名称,对象每次写推进全局 revision,mod_revision 即 resourceVersion。lab 用 store 包的两个 mvcc 用例验证 Get 返回最新值与全局单调 revision。
category
K8s 把全部资源对象以序列化 JSON 单 key 单对象存进 etcd,key 布局为 /registry/组/资源/命名空间/名称,对象每次写推进全局 revision,mod_revision 即 resourceVersion。lab 用 store 包的两个 mvcc 用例验证 Get 返回最新值与全局单调 revision。
一次 etcdctl put 经 gRPC 到提案、WAL fsync、raft 多数派确认、commitIndex 推进、apply 落 backend 七步完成,WAL 的 fsync 是写路径核心延迟,批量提交摊薄其成本。lab 用 TestAppendEntriesReplicatesLog 验证日志复制到全部节点,用 TestLeaseGrantAndRemainingDecay 验证挂租约 key 的 TTL 递减。
etcd 单进程由 gRPC 服务层、raft 共识层(raft 库 + rafthttp)、storage 层(WAL + snapshot)与 backend 层(btree + bolt 的 mvcc)四层构成,写请求经提案、WAL、复制、apply 一路落到 backend。lab 用 raft/sim.go 事件驱动 Step 模拟共识层与传输,store、lease、watcher 包对应 backend 之上的 mvcc、租约与事件流,全量 46 用例通过。
etcd v3 提供串行化读与线性一致读两种模式,差别只在读前是否走一次 ReadIndex 确认。本节给出客户端指定方式、延迟/吞吐对比与适用场景,分析 apiserver 直连 etcd 读为线性一致、watch cache 快照为弱一致,并给出 K8s 各读点的一致性选择框架。lab 用 TestLinearizableReadIndex 与第 2 章 TestEventualStaleReadWindow 对照两种读模式的行为。
ReadIndex 用四步把线性一致读变成「commitIndex 边界 + 一次多数派确认」,不写日志;Lease Read 再用时钟租约省掉那次确认,但引入时钟漂移风险。本节对比二者与完整共识读的代价,说明 etcd 默认 Range 走线性一致读、串行化读是显式选项。lab 用 TestLinearizableReadIndex 验证 sim.go 以 commitIndex 作为读边界返回。
只写走共识、读直接本机读在 Raft 集群里不可行:复制异步使 follower 滞后,分区旧 Leader 会继续用过期状态响应读。本节分析 stale read 在 K8s 的实际危害,对比完整共识读、ReadIndex、Lease Read 三档方案,说明完整共识读的写放大与日志爆炸代价,并衔接第 2 章线性一致定义。lab 用 TestLinearizableReadIndex 验证 Leader 以 commitIndex 返回线性一致读边界、未提交日志不参与读。
etcd 的压缩是三层递进的:Raft 日志压缩(snapshot)只管协议层的日志,mvcc 历史版本压缩(auto-compaction,按 period 或 revision)管键值的历史版本,而存储碎片整理(defrag)才是真正把磁盘空间还给文件系统的一步。本节先讲清楚这三层的边界与默认值(--snapshot-count=100000、--auto-compaction-mode 与 --auto-compaction-retention、--quota-backend-bytes 默认 2GB),再解释为什么 mvcc 压缩后空间未必立即释放——bolt 数据库的碎片;然后给出 etcdctl defrag 与在线 defrag 的用法与代价。K8s 运维实践部分覆盖常见的 8h 保留配置、磁盘告警与逐台 defrag。最后梳理两类压缩故障:mvcc 压缩过快丢 watch 历史(ErrCompacted),以及 defrag 期间的性能下降,并预告 12 章 mvcc 的深入衔接。lab 用 snapshot.go 的 Compact 与 Install、以及 TestSnapshotCompaction 与 TestInstallSnapshot 联合验证「日志压缩→快照」与「落后节点从快照恢复」两个方向。
日志压缩之后留下一个缺口:Leader 的日志起点往前移了,落后的 follower 再按日志逐条追就追不上了——于是 Raft 引入 InstallSnapshot RPC,直接把快照发给落后节点。本节先讲清楚快照的生成时机(日志超过 snapshot-count 阈值、或 follower 的 nextIndex 落在 Leader 已丢弃的日志段),再逐个解释 InstallSnapshot 的字段(term、leaderId、LastIncludedIndex、LastIncludedTerm、Data),然后走一遍接收方的本地处理:丢弃旧日志、安装状态机、把 commit/apply 推进到快照位置。接着说明快照与日志匹配性质的衔接——LastIncludedTerm 让选举判断依然正确。最后落到 etcd 的 snapshotter 包、--snapshot-count 与备份/恢复的关系。lab 用 snapshot.go 的 Install 与 TestInstallSnapshot 验证落后节点安装快照后状态机直接对齐、不需要重放日志。
Raft 的日志是只追加的,只要集群在运行,日志条数就只增不减:磁盘、重启重放时间、慢 follower 追赶、内存缓存四处同时埋单。本节先拆解这四类代价,再给出 etcd 的真实数字(--snapshot-count 默认 100000 条触发快照、WAL 文件与 snapshot 文件的位置、--max-wal-files 默认 5),并说明日志重放从 WAL 到 apply 的完整路径。K8s 视角下,etcd 数据量随对象数与 revision 数增长,压缩不及时会让磁盘与内存同时暴涨。最后澄清压缩与一致性的关系:压缩掉的只是已提交且已应用的日志,状态机语义不受影响。lab 用 snapshot.go 的 Compact 与 TestSnapshotCompaction 验证日志超过阈值后可压成快照、日志条数下降、状态机保留已应用命令。
etcd 没走联合共识的完整实现,而是用更简单的单步变更:每次只加/删一个节点,新旧配置交集天然非空。V3.4 引入 learner 解决新成员慢的问题——先以不投票、不参与选举的身份同步日志,追平后 member promote 转正。本节给出单步变更的数学保证、learner 的完整生命周期、etcdctl 命令与 3→5 生产扩容演练。lab 用 AddLearner/Promote 验证 learner 不改变 quorum、不会被选为 Leader、晋升后 quorum 增大。
8.1 证明错峰切换配置会制造不相交的多数派,Joint Consensus 用两阶段把这个窗口封死:先进入旧配置与联合配置双多数,再切到纯新配置,保证任意时刻新旧配置的多数派必然相交。本节给出两阶段的状态机、双多数的提交条件、新成员先同步再变配置的时机,并对照 etcd 的 confchange 库与 confstate 处理。lab 继续用 AddNode 验证 quorum 始终是多数派这一数学基础。
增删节点看起来只是改一行集群配置,实则同时改写了 quorum 数学:若各节点在不同时刻切换配置,就会同时存在两个不相交的多数派,各自提交不同命令,把系统撕成两半。本节用 3→5 的反例说明脑裂条件、变更中的选举竞态,并落到 etcd 缩容、扩容、替换故障节点的真实场景。lab 用 membership.go 的 AddNode/RemoveNode 验证成员数变化时 quorum 从 2 移到 3。
状态机安全(State Machine Safety)是 Raft 安全证明链的最后一环:所有节点以相同顺序应用相同日志。本节论证它与日志匹配性质的关系,解释「只能提交当前任期日志」如何防止旧任期条目被覆盖,讲清新 Leader 任期开始用空日志条目(no-op)建立提交点、再以自身日志强制覆盖冲突的含义,概述 Log Matching → Leader Completeness → State Machine Safety 的归纳证明,并对照 etcd 应用层 backend 的 batch apply 与 consistent_index 幂等应用。lab 用 TestStateMachineSafety 验证移除旧 Leader 后新 Leader 仍保留已提交命令。
Leader 完整性(Leader Completeness)把 7.1 的当选结论推广到任意后续任期:被提交的日志条目在新任期 Leader 当选时一定存在。它的根基不是某一条具体规则,而是「Leader 日志只追加」这一不对称设计——选举限制挡住旧日志候选、日志只追加让 Leader 永不删除已提交条目、Leader 只能推进不能覆盖让复制永远单向。本节推演被分区替换的旧 Leader 恢复后重新当选的全过程,并对照 etcd 的 WAL 重放与 MemoryStorage.Append 如何维持只追加语义。lab 用 TestLeaderAppendOnly 断言 Leader 追加日志后已提交条目不被改写。
Raft 安全性的第一环是 Election Safety:每个任期至多选出一个 Leader,而让当选 Leader 必然包含全部已提交日志的钥匙正是日志新旧比较。本节站在 5.2 协议层之上做定理层证明:多数派交集 + logUpToDate 的 term 优先、index 次之语义推出当选 Leader 的日志完整性,推演旧日志 Leader 覆盖已提交数据的危险场景,并对照 etcd raft/raft.go 的 MsgVote 投票决策与 raft/storage.go 的日志来源。lab 用 TestElectionRestriction 复现旧日志候选拿不到多数、新日志候选当选。
提交是复制状态机从「日志一致」到「生效」的分界线:commitIndex 只在多数派 matchIndex 确认且条目属于当前任期时才推进;leader 通过每条 AppendEntries 携带 LeaderCommit 把提交传播给 follower;apply 阶段把 (ApplyIndex, CommitIndex] 区间应用到状态机并保持幂等。「只提交当前任期日志」规则防止旧任期日志被未来 leader 覆盖而丢失已提交数据;etcd 把 commit 与 apply 分离,apply 在独立的 backend 循环批量执行。lab 用 TestLogMatchAndCommit 与 TestCommitRequiresQuorum 分别验证提交传播与多数派约束。
Raft 的安全根在日志匹配性质:两个日志在相同 index 有相同 term,则之前所有条目一致。follower 日志可能缺条目、多条目、有冲突条目或 term 交错;leader 靠 nextIndex 逐条回退(etcd 用 RejectHint 每轮回退多条)配合 PrevLogIndex/PrevLogTerm 一致性检查修复对齐。lab 用 TestNextIndexBacktrack 注入冲突日志后断言 leader 逐条回退、follower 截断冲突段恢复一致。
Raft 的日志复制全部收敛到一条 AppendEntries RPC:请求携带 Term、PrevLogIndex、PrevLogTerm、Entries 与 LeaderCommit 五个字段,响应携带 Term、Granted 与 MatchIndex;空 Entries 的 AppendEntries 就是心跳,负责维持领导权、重置 follower 选举超时并顺带携带 LeaderCommit 推进提交。leader 必须周期性心跳,否则 follower 超时发起新选举;etcd 默认心跳间隔 100ms、选举超时 1000ms。lab 用 TestAppendEntriesReplicatesLog 验证心跳维持 leader 活性且 3 条日志复制到全部 3 节点。
正常选举靠随机超时错开,异常场景才暴露边界:同步超时引发分裂投票,分区节点借 pre-vote 被隔离出竞选,孤立 leader 靠 CheckQuorum 自检下台。本节逐一拆解 split vote、pre-vote、CheckQuorum 的机制与取舍,说明任期对齐降级规则,并落到 etcd 网络分区下控制面的实际表现:少数派无法提交、leader 迁移、恢复后日志追赶。lab 用 TestSplitVoteRecovers 验证分裂投票随机超时后收敛,用 TestPreVoteQuarantine 验证被分区节点无法借 pre-vote 扰乱主集群、不递增任期。
选举协议只解决「谁能竞选」,选举限制解决「谁配当选」:投票者只投给日志不落后于自己的候选,用 term 优先、index 次之的日志新旧比较,保证当选 leader 必然包含全部已提交条目。本节先推演无限制时旧日志节点覆盖已提交数据的事故链,再给出比较规则、投票决策、多数派交集与领导者完整性的安全证明,最后落到 etcd 节点重启、磁盘落后时如何避免选主后丢数据。lab 用 TestElectionRestriction 复现旧日志候选拿不到多数、新日志候选当选。