《Kubernetes 分布式系统原理深入解析》11.3 etcd 与 K8s 数据模型映射

K8s 把全部资源对象以序列化 JSON 单 key 单对象存进 etcd,key 布局为 /registry/组/资源/命名空间/名称,对象每次写推进全局 revision,mod_revision 即 resourceVersion。lab 用 store 包的两个 mvcc 用例验证 Get 返回最新值与全局单调 revision。

11.3 etcd 与 K8s 数据模型映射

11.2 把一次写从 Put 走到 apply 落盘:提案经共识被接受,apply 把新值写进 mvcc backend,读路径复用同一份存储。
但 etcd 自己并不知道「Pod」或「Deployment」是什么——它只存「key → value(带 revision)」。
把 K8s 的全部资源对象映射到这棵 key-value 树上的,是 apiserver 的存储层。
本节回答一个问题:同一个通用存储,如何承载 K8s 全部资源?
答案落在三件事上:key 布局、序列化、resourceVersion 与 revision 的对应。
这也是 11.2 写路径的延伸:写入时 apiserver 只是构造了一个 key 与一段 JSON,真正让它成为「资源对象版本」的,是 revision 与 resourceVersion 的这套映射。

K8s 在 etcd 的 key 布局

apiserver 把所有对象放进一个统一前缀 /registry 下,路径按「组、资源、命名空间、名称」逐级拼接。
核心资源没有组,所以少一段:

资源类型例子etcd key
核心 namespacedPod/registry/pods/default/nginx
核心 cluster-scopedNode/registry/nodes/k8s-node-1
有组 namespacedDeployment/registry/apps/deployments/default/nginx
核心特殊对象Namespace/registry/namespaces/kube-system

规律很简单。
有组的资源是 /registry/<group>/<resource>/<namespace>/<name>,无组的核心资源是 /registry/<resource>/<namespace>/<name>,cluster-scoped 资源省掉命名空间段。
名字里嵌了命名空间后,同一个命名空间下同一类资源在 etcd 里天然聚成一串前缀,这为 List 的高效遍历打好了底。

在真实集群里用 etcdctl 扫一眼,能直接看到这个布局:

etcdctl get /registry --prefix --keys-only | head -30

输出会是一串形如 /registry/pods/default/nginx、/registry/apps/deployments/default/nginx、/registry/leases/kube-system/kube-controller-manager 的 key,全部按字典序排列。
apiserver 的所有 List 请求,最终都落到这类前缀上的 Range。
读者可以记住一个心智模型:K8s 的 namespace 不是 etcd 的概念,它只是 key 前缀里的一层目录——这正是后面 List 分页、watch 起点能共享同一套逻辑的原因。

单 key 单对象:序列化 JSON 与存储边界

K8s 在 etcd 的存储粒度是「一个对象一个 key」:key 是该对象的规范名称,value 是该对象的完整序列化 JSON。
一个 Pod 的 value 大致是:

{"apiVersion":"v1","kind":"Pod","metadata":{"name":"nginx","namespace":"default","uid":"...","resourceVersion":"1420",...},"spec":{...},"status":{...}}

value 里带有完整的对象元数据(包括 resourceVersion、uid),所以 etcd 不关心对象结构,apiserver 读出 JSON 后反序列化成 Go 对象即可。
存储边界因此非常干净:etcd 保证的是「这个 key 的这次写入是线性一致的、不可丢的」,对象内部的一致性由 apiserver 自己用 resourceVersion 与事务保证。

这个模型和 etcd v2 时代(K8s 1.6 之前)完全不同。
v2 用目录树存对象,一个 Pod 的字段被打散成多个 key,List 要递归遍历目录。
v3 模型下每个对象就是一个 key,读取、写入、List 都变成单值或区间操作。
K8s 从 v2 迁到 v3 的核心收益正是「对象 = 单值」:不再有半更新的中间状态,一个 key 的读写天然原子。

序列化的另一个含义是没有跨对象的引用完整性。
Deployment 与它创建的 ReplicaSet、Pod 是三个独立 key,etcd 不保证它们一起存在。
控制器通过 List/Watch 自行收敛,这是第 1 章「K8s 是控制循环而非数据库事务」的体现。
另外,单个对象的体积受 etcd 单值大小限制(默认约 1.5 MiB,apiserver 侧又限制对象约 1 MiB),超大对象会直接写失败——这也是 K8s 对象设计避免内嵌大数据的原因。

resourceVersion 与 etcd revision

这是本节最核心的映射。
etcd 里每个 key 都有 mod_revision——它最近一次被写的全局 revision;K8s 对象元数据里的 resourceVersion 存的就是这个数字的字符串形式。

写入对象 N(revision 推进到 r) → 对象 metadata.resourceVersion = strconv(r)

由此推出三个工程上非常重要的性质。

  1. resourceVersion 是全局单调的:所有对象共享同一把 revision 计数,两个对象即使跨命名空间、跨资源类型,也能用 resourceVersion 比大小(虽然跨类型比较没有语义意义,但在 List 续页、watch 起点选择上很有用)。
  2. resourceVersion 就是并发控制令牌:apiserver 写对象前,把对象的 resourceVersion 与 etcd 里当前的 mod_revision 做比较(一个 Txn 的 If 条件),不相等则整体失败、返回 409。
    这就是 K8s 乐观并发控制的底层——第 12 章的 CASModRev 对应这个语义。
  3. 读旧版本 = 从旧 revision 重建对象:watch 从 resourceVersion 开始追事件,List 带 resourceVersion 读历史快照,都建立在「每个对象版本都挂在 revision 上」这一模型上。

把写对象的流程具体化。

  1. 客户端提交对象(可能带 resourceVersion,也可能不带)。
  2. apiserver 的 storage 层把对象编码成 key + JSON。
  3. 若对象已有 resourceVersion,etcd Txn 的 If 条件比较该值与 key 当前 mod_revision;不一致 → 409 Conflict,客户端重新 Get 再重试。
  4. 一致(或创建新对象)→ 写入,返回新 revision。
  5. 新 revision 写回对象元数据,作为下一次更新的乐观锁起点。

举一个具体的 409 例子。
客户端 A、B 同时 Get 到某个 Deployment 的 resourceVersion=100;A 先提交,revision 推进到 101;B 随后仍用 100 提交——If 比较失败,B 收到 409,必须重新 Get 拿 101 再改。
这个流程就是 K8s 里最常见的「update conflict」报错来源,背后没有分布式锁,只有 etcd 的一次 Txn 比较。

这里要注意:resourceVersion 对客户端是不透明字符串,客户端只做「存原值、再提交」的回显,不应该解析或比较它。
语义上的比较只发生在 apiserver 与 etcd 之间,用的就是整数 revision。
kubectl、client-go 都不碰 resourceVersion 的值,就是因为它只是令牌,不是人类可读的版本号。

关键前缀:leases、events、secret 与 configmap

不是所有 key 都是「普通业务对象」,有几类特殊前缀值得单独说明。

  • /registry/leases/:Lease 资源(coordination.k8s.io 组)的存储前缀,格式为 /registry/leases/<namespace>/<name>。
    它是控制器、调度器做选主锁的载体,值里只有 holderIdentity、acquireTime、renewTime 等少量字段。
    K8s 选主依赖的是 Lease 对象的内容,而不是 etcd 键的 TTL。
  • /registry/events/:事件对象的前缀,按命名空间和事件名存储。
    事件数量大、生命周期短,靠 TTL 机制周期性清理,与普通对象共用同一条 revision 计数。
  • /registry/secrets/ 与 /registry/configmaps/:secret 与 configmap 也是普通对象,value 里的 data 字段是 base64 编码的键值对。
    它们的特殊之处在 apiserver 层:secret 默认会被 KMS 或加密 provider 在写入前加密(encryption at rest),所以 etcd 落盘的内容对不可信备份者是密文;configmap 则通常明文。
    两者都遵守「单 key 单对象」的同一存储模型,K8s 依赖 etcd 的 data-consistency(写即持久、读线性一致)来保证配置与密钥的一致性,而不是额外的副本机制。

Lease 对象是三类「轻量高频写」里最典型的。
kube-controller-manager、kube-scheduler 每隔几秒更新自己的 Lease,每次更新都是一次完整的 etcd Txn 写。
正是因为资源小、写频繁,Lease 的 key 前缀天然就与其他对象分开,方便监控和故障排查时一眼定位选主状态。

一个常见的误解是「K8s 用 etcd 键级租约给对象设 TTL」。
实际上普通 K8s 对象在 etcd 里没有 TTL,删除只发生在控制器或用户显式删除时。
etcd 键级租约只用于极少数场景(如节点的心跳数据),而绝大多数「定期清理」由 K8s 自己的控制器(例如事件 GC)完成——这是 K8s 把「数据生命周期」上收到应用层而不是依赖存储机制的体现。

List 与 Range:一个前缀的 btree 遍历

etcd 的 mvcc 在内存维护一棵有序 btree 索引,key 按字典序排列。
这给了 K8s 一个极其廉价的 List 原语:列出某个命名空间下某类资源,就是一次 Range,扫从前缀开始的一段连续 key 区间。

列表需求Range 前缀
全集群 Pod/registry/pods/
某命名空间 Pod/registry/pods/<namespace>/
某命名空间下所有资源多个前缀分别 Range 后合并

因为 key 布局把命名空间嵌在前缀里,命名空间级 List 恰好是「从一个前缀起、到该前缀的字典序终点止」的一段连续区间,btree 上做区间遍历非常高效。
这也是 11.1 里说的「backend 层 btree 索引 + bolt 的 mvcc」服务 K8s 的核心方式:apiserver 不需要任何二级索引,etcd 的前缀即索引。

etcd 的 Range 请求用两个字段表达区间:key(起点)与 range_end(终点)。
range_end 等于起点加一个字节的最小上界(如 /registry/pods/default/ 到 /registry/pods/default0)就能扫完整个前缀。
K8s 的 List 正是这么构造的:把请求前缀翻译成一个 [key, range_end) 区间交给 mvcc。

List 还有一个配套机制:分页。
apiserver 的 pagingList 对大批量 List 做分页,每次 Range 取一页,用「最后一页最后一个 key」作为 continue 令牌,下一次 Range 从这个 key 之后继续——续页天然复用 Range 的区间语义。
watch 与 List 共享同一套 key 前缀与 revision 语义:List 拿到的资源版本号可以直接作为 watch 的起点,这在第 13 章讲 watch 协议时会再遇到。

与 lab store 包的映射

lab 的 store 包就是这一节的最小可运行模型。
store/mvcc.go 里:

  • Put(key, value) int64:每次写把全局主 revision 加一,返回本次写产生的 mod_revision——这就是 K8s 对象 resourceVersion 的底层数字。
  • Get(key) (value, rev, ok):返回 key 当前最新值及其 mod_revision——等价于 apiserver 读对象时拿到的「最新值 + resourceVersion」。
  • Txn、CASModRev:用 mod_revision 做乐观锁的 If/Then 比较——对应 K8s 写对象前的 409 冲突检测。
  • Delete 追加墓碑:删除后 Get 不可见、历史读仍可见——对应 K8s 对象删除后 watch 收到的 DELETE 事件仍带旧 resourceVersion。

三个用例直接对应本节的三个断言:全局单调 revision、Get 返回最新、乐观锁冲突。
跑法见下面的 lab 小节。

本节 lab

跑 store 包的两个核心用例:

cd private/labs/k8s-etcd-lab
go test ./store -run 'TestMVCCGetReturnsLatestWithModRev|TestMVCCPutAssignsMonotonicRevision' -v

预期断言:

  • TestMVCCGetReturnsLatestWithModRev:对同一 key 连续 Put 两次(v1、v2),Get 返回最新值 v2 与 mod_revision=2——K8s 读对象时拿到的 resourceVersion 就是这个数字。
  • TestMVCCPutAssignsMonotonicRevision:不同 key 共享同一把全局 revision 计数——Put a=1 得 rev1,Put b=2 得 rev2,Put a=2 得 rev3——这是「每次写推进全局 revision」的底层模型。

两个用例合起来,正好覆盖「resourceVersion = mod_revision」与「全局单调 revision」这两条 K8s 与 etcd 数据模型映射的基石。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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