《Kubernetes 分布式系统原理深入解析》1.2 REST 语义:verbs、子资源、集合与分页

apiserver 把 etcd 的键值世界翻译成 REST 世界:GET/POST/PUT/PATCH/DELETE 对应读、创建、全量更新、部分更新与删除,Watch 是第 5 个动词;子资源(status、scale、proxy)把「对象」拆成「可独立访问的视图」;集合分页用 continue 令牌而非 offset,因为底层是 mvcc revision 而非关系表。本节拆解这套语义并说明它们如何映射到 etcd 操作。lab 用 api/store.go 验证集合分页的 list-watch 起点语义。

1.2 REST 语义:verbs、子资源、集合与分页

apiserver 对外暴露的是一个完整的 REST API。但它的 REST 不是「把数据库表暴露成 CRUD」那么简单——它把 etcd 的键值语义翻译成了资源语义。本节拆解这套翻译规则:五个动词、子资源、集合分页,以及它们各自背后的分布式系统含义。

五个动词:读、建、改、删、观

K8s 的 REST 动词比经典 CRUD 多一个「观」:

HTTP 动词语义对应 etcd 操作幂等?
GET读单个对象线性一致读或缓存读是
POST创建(Create)分配 RV 的写入否(重复会 409)
PUT全量更新(Update)携带 RV 的乐观锁写入是
PATCH部分更新合并/应用式写入是
DELETE删除删除 + 墓碑否
WATCH增量订阅watch 事件流—

重点看两个容易被忽略的设计:

  1. PUT 不是无条件的覆盖,而是「带版本的覆盖」。K8s 的 Update 必须携带客户端读取到的 resourceVersion;如果服务器上的版本已变,返回 409 Conflict。这迫使写入变成「比较-交换」(CAS),是卷二第 2.2 节乐观锁的 HTTP 形态。经典 REST 没有这个要求,K8s 加它是因为 etcd 本身支持 CAS,apiserver 把它原样暴露给客户端。

  2. WATCH 是第五个一等公民动词。它不是轮询的别名,而是长连接 + 增量推送。控制器不「定时拉」,而是「订阅变化」。这直接决定了卷二第 3 章 informer 的架构:缓存由事件流维护,而不是由周期查询维护。

子资源:把对象拆成视图

除了对象本体,apiserver 还暴露一组子资源,每个都是对象的某个方面:

  • /status:对象的状态视图。控制器写 status,用户读 status,双方对 spec 不冲突。设计上刻意让 status 与 spec 分离——正是卷二第 2.1 节「Generation 只随 spec 变化」的原因。
  • /scale:对象的副本数视图。HPA 只写 scale,不碰 spec,避免与其他控制器竞争。
  • /proxy、/log:Pod 的转发视图,apiserver 充当代理。

子资源的关键作用:并发隔离。多个写者(用户改 spec、控制器改 status、HPA 改 scale)通过子资源拆分,减少乐观锁冲突。若所有写都打同一个对象,则 spec 与 status 的并发更新必然频繁 409。

集合与分页:continue 令牌

GET /apis/apps/v1/deployments 返回集合。当对象多时(生产集群数万到数十万),必须分页。K8s 的分页很特别:

  • 请求带 limit=500,响应返回 metadata.continue 令牌。
  • 下一页请求把 continue 原样传回,apiserver 从上一页断点继续。

为什么不用 offset? 因为底层不是关系表,而是 mvcc 版本库。对象的顺序由 etcd 的 key 排序决定,分页游标是「我上次读到哪了」的索引位置,而不是「跳过 N 行」。用 offset 会在并发写入时重复或遗漏对象;用 continue 令牌则天然抵御对象在分页期间被增删。

这背后是卷二第 3.1 节 list-watch 的同一个模型:List 返回快照 + 游标,Watch 从游标续增量。continue 令牌本质上就是 list-watch 中「resourceVersion 起点」的 REST 形态。

命名空间与集合的层次

资源集合按命名空间组织:

/apis/apps/v1/namespaces/<ns>/deployments
  • 命名空间内的集合:GET .../namespaces/default/deployments
  • 集群级集合(无命名空间):GET /apis/apps/v1/deployments(跨全部命名空间)

命名空间是逻辑分区而非物理分区——底层仍是同一个 etcd。它在一致性层面没有特殊含义,只影响 RBAC 授权范围与 API 路径。集群级 List 会扫全部命名空间,代价更大,这也是 apiserver 缓存命中率(卷二第 3 章)比命名空间级 List 更依赖缓存的原因。

从 REST 到 etcd:键的设计

每个对象在 etcd 里的 key 是确定的,例如 Deployment 对象存于:

/registry/deployments/default/nginx

映射规则:/registry/<resource>/<namespace>/<name>(集群级资源无 namespace 段)。这套 key 设计决定了:

  • 前缀 List:/registry/deployments/ 前缀能列出某资源全部对象,etcd 支持前缀 watch。
  • 命名空间 List:/registry/deployments/default/ 前缀列出单命名空间对象。
  • Watch:watch 某个前缀,等于订阅该资源集合的全部变化。

所以 apiserver 的「集合」概念,底层就是 etcd 的 key 前缀。REST 的分层(集群/命名空间/对象)是前缀的层层下钻。这也解释了为什么 watch 天然支持「集合」——它本来就是前缀 watch 的 REST 化。

读路径的两档:直读与缓存读

REST 的 GET 在 apiserver 里有两套实现,对应两种一致性档位:

GET 形态数据来源一致性
直读(GET 不带 resourceVersion)走 apiserver 对 etcd 的读(可能经本地缓存)接近线性一致
List + Watch(informer)apiserver 维护的 watch 缓存有界滞后

注意:apiserver 自己也有一个对 etcd 的 list-watch 缓存(用于 serving GET 与实现一致性读)。也就是说,apiserver 是第一个 informer——它用与控制器完全相同的「list 全量 + watch 增量」机制维护自己的视图,只不过它还有一条直连 etcd 的写路径。这一层缓存正是卷二第 14 章「apiserver 与 etcd 最终一致窗口」的来源。

REST 与 gRPC:对外的两副面孔

apiserver 对外有两个协议面:

面谁用语义
REST/HTTPkubectl、curl、控制器人类可读、JSON/YAML、watch 长连接
gRPC与 kubelet 的通信、部分内部调用结构化、流式

两者的底层对象模型一致:都描述同一个资源、同一套版本语义。REST 的 PATCH /apis/.../deployments 与内部存储层的 Update 最终都映射到同一个 etcd 写入路径。理解这一点,就不必为「apiserver 到底对外是 REST 还是 gRPC」纠结——对外 REST,对内数据面统一。

DELETE 的两段式:软删除与 Finalizer

DELETE 在 K8s 里不是「立即抹掉」,而是两段式:

  1. 软删除:apiserver 给对象打上 metadata.deletionTimestamp,对象进入「终止中」状态。此时对象仍可通过 GET 读到,但不再是「活跃」的。
  2. Finalizer 清理:对象上若注册了 finalizer(metadata.finalizers),DELETE 不会真正删掉对象,而是等所有 finalizer 执行完毕、把自己从列表中移除后,才真正从 etcd 删除。

用伪代码看 apiserver 的删除判定:

func Delete(obj *Object) {
    if len(obj.Finalizers) > 0 && obj.DeletionTimestamp == nil {
        // 进入终止:打时间戳,等待 finalizer 执行
        obj.DeletionTimestamp = now
        return // 对象仍在,且不可更新 spec
    }
    if len(obj.Finalizers) > 0 {
        return // 还有 finalizer 未清:对象保留
    }
    etcd.Delete(obj) // 全部清完:真正删除
}

这个两段式设计服务两个目的:

  • 优雅清理:对象(如 PV、PVC)删除前需要释放底层资源,finalizer 给清理逻辑一个「在删除前执行」的钩子。
  • 可观察:deletionTimestamp 出现后,控制器知道「这个对象要没了」,可以停止对它做修复性动作(卷二第 5 章:调谐要跳过终止中的对象)。

与 REST 的关系:DELETE 返回的 200 只代表「删除被接受」,不代表「对象已消失」。查询时可能仍能看到带 deletionTimestamp 的对象。这与 kubectl apply 返回 200 不代表「已生效」是同一条主线:REST 动词的返回只承诺「操作已提交」,不承诺「副作用已完成」。

三个常见误解

  • 「PATCH 只是 PUT 的简化」——错误。PUT 是全量覆盖(必须带完整对象和 RV),PATCH 是差异更新(只带要改的字段),两者语义完全不同。PUT 覆盖未声明字段,PATCH 保留。卷二第 2.3 节对比三种 PATCH。
  • 「分页用 limit+offset 就好」——错误。etcd 不是关系库,offset 在并发写下会重复/遗漏对象。continue 令牌才安全。
  • 「子资源只是组织上的便利」——错误。子资源是并发隔离机制:spec/status/scale 分离让多个控制器各写各的,显著降低 409 冲突率。

动词背后的授权:GET、LIST 与 WATCH 的权限差异

REST 动词在 RBAC 里被映射成不同的权限操作,看似「都是读」,权限边界不同:

HTTP 动词RBAC 操作权限范围
GET 单个对象get单个对象
GET 集合list整个集合
WATCHwatch集合的增量事件

三个权限是互相独立的,角色可以只授予其中一个:

授权能做什么不能做什么
只给 get读单个 Deployment列全部、订阅变化
只给 list列全部 Deployment读单个(严格模式下)
只给 watch订阅增量事件流发起 List

WATCH 的授权范围比 list 更宽——能看到一切变化,包括删除,即使对象随后被清空。这层映射是排查「403 只发生在 list/watch」类问题的基础:RBAC 按动词分层,不是按「读写」二分。而 informer 的 list-watch 同时需要 list 与 watch 两个权限,缺一个都会在同步阶段报 403。

本节 lab

本节验证集合分页的「list-watch 起点」语义:ListSinceRV 返回该 revision 之后出现且仍存在的对象,并给出当前 RV 作为下一步起点:

cd private/labs/k8s-ctrl-lab
go test ./api -run 'TestListSinceRV' -v

用例创建两个对象后,从第一个对象的 RV 起 list,验证:只返回该 RV 之后的对象、当前 RV 正确返回。这正是 continue 令牌与 watch 起点在存储层的同一套语义。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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