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 事件流 | — |
重点看两个容易被忽略的设计:
PUT 不是无条件的覆盖,而是「带版本的覆盖」。K8s 的 Update 必须携带客户端读取到的
resourceVersion;如果服务器上的版本已变,返回409 Conflict。这迫使写入变成「比较-交换」(CAS),是卷二第 2.2 节乐观锁的 HTTP 形态。经典 REST 没有这个要求,K8s 加它是因为 etcd 本身支持 CAS,apiserver 把它原样暴露给客户端。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/HTTP | kubectl、curl、控制器 | 人类可读、JSON/YAML、watch 长连接 |
| gRPC | 与 kubelet 的通信、部分内部调用 | 结构化、流式 |
两者的底层对象模型一致:都描述同一个资源、同一套版本语义。REST 的 PATCH /apis/.../deployments 与内部存储层的 Update 最终都映射到同一个 etcd 写入路径。理解这一点,就不必为「apiserver 到底对外是 REST 还是 gRPC」纠结——对外 REST,对内数据面统一。
DELETE 的两段式:软删除与 Finalizer
DELETE 在 K8s 里不是「立即抹掉」,而是两段式:
- 软删除:apiserver 给对象打上
metadata.deletionTimestamp,对象进入「终止中」状态。此时对象仍可通过 GET 读到,但不再是「活跃」的。 - 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 | 整个集合 |
| WATCH | watch | 集合的增量事件 |
三个权限是互相独立的,角色可以只授予其中一个:
| 授权 | 能做什么 | 不能做什么 |
|---|---|---|
| 只给 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 起点在存储层的同一套语义。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。