【kube-apiserver】控制面全景：缺口、五轴坐标系与 16 篇路线

etcd/13 · Kubernetes 控制面耦合 钉过 apiserver↔︎etcd 的分层边界、resourceVersion 与 Revision 映射、Node Lease 心跳路径，最后写明「apiserver 存储接口实现不在此展开，见续作控制面内核」。distributed/50 · etcd 深度解剖 给出了 Watch/MVCC/Lease 协调层百科，但 apiserver 的缓存层和链路拦截点只做了索引。k8s-network/ 覆盖了 CNI/Service/Pod 数据面，控制面存储层则明确不写。真正缺的一层是：一次 Create/Update 从 REST 到 etcd，失败落在 HandlerChain 的哪个插槽；504 是 APF 排队还是 etcd ReadIndex；410 Gone 是 cacher bookmark 过期还是 etcd ErrCompacted；Webhook 503 与 storage 超时如何分列，以及何时不该直连 etcd 排障 apiserver。

本文只做三件事：钉缺口、定义五条坐标系、给出 16 篇阅读路线。版本锚定 Kubernetes v1.30.3（源码 tag v1.30.3），etcd 后端对照钉 etcd v3.5.33。

本篇在系列中的位置

篇目	核心内容
第 1 篇 · 控制面全景	缺口、五轴坐标系、16 篇路线
第 2 篇 · 进程与请求路径	generic apiserver、HandlerChain、REST 路由
第 3 篇 · storage.Interface 与 etcd3	codec、prefix、CRUD/Watch 到 etcd
系列目录	关键问题、阅读路径、全部价值点

版本锚定：Kubernetes v1.30.3（源码 tag v1.30.3，2024-08-14 补丁线）。机制叙述对齐该 tag 下 staging/src/k8s.io/apiserver/；kubernetes.io/docs/ 为辅助参考，不以 live 版本冒充 v1.30.3。etcd 后端对照钉 v3.5.33——apiserver 存储适配行为以 v1.30.3 源码为准，etcd 侧五轴见 etcd 系列。无真实 K8s 集群则不粘贴伪造 kubectl 输出或 metrics 截图。

一、相对站内已有内容，缺口在哪

下表列出各已有系列的视角与本系列填补的格子。规则是：不重写已有内容，只填真正空着的格子。

结论：读者知道「只有 apiserver 直连 etcd」，但不知道 写失败是 admission 还是 etcd3、504 是 APF 排队还是 etcd ReadIndex、410 Gone 是 cache bookmark 还是 etcd ErrCompacted、Webhook 503 与 storage 超时如何分列；把 apiserver 当成 etcd 的 curl 代理，会在准入与缓存层指错组件。

Saltzer 端到端论证的含义：Saltzer, Reed & Clark（ACM TOCS 1984）的 end-to-end argument 指出，可靠性保证应在通信端点而非中间层实现。Kubernetes 控制面的单持久化入口（apiserver → etcd）体现了这一原则：RBAC 决策、Admission mutation、字段验证都在 apiserver 层完成，etcd 只见已授权的 protobuf bytes。把 admission 逻辑下沉到 etcd 层或分散到多个写入方，都会破坏这条端到端保证——这也是为什么只有 apiserver 持有 etcd 证书。

本系列刻意不写：Helm/kubeadm 安装全书、scheduler/controller-manager/kubelet 内核重讲、CRD codegen 全书、etcd Raft/MVCC 全书（外链 etcd 系列）、Kine 兼容层全书、CNI/mesh 数据面全书、未实测 P99/QPS 排行。若目标是「etcd Raft lag 与 apply lag 如何分列」，etcd 系列第 15 篇已够；若目标是「504 是 APF 还是 etcd ReadIndex、Webhook 503 与 storage 超时如何分列」，则必须沿本系列五轴下钻。

版本门禁（后续章节共用）

二、五条坐标系（后续章节回指）

后面每一篇都落到下面某一条轴上。排障口诀：先点名轴，再下钻组件——不要一上来换 etcd 或扩 apiserver 副本。504 与 etcd lag 在轴 1 与轴 5 分列证据包。

flowchart LR
  client["kubectl / controllers"]
  apiserver["kube-apiserver"]
  auth["AuthN AuthZ Audit"]
  adm["Admission chain"]
  storage["storage.Interface"]
  cacher["watch cache"]
  etcd["etcd v3.5.x"]
  client --> apiserver
  apiserver --> auth
  auth --> adm
  adm --> storage
  storage <--> cacher
  storage --> etcd
  cacher -->|"ListAndWatch"| etcd

Storage / etcd 耦合轴

定义：storage.Interface（k8s.io/apiserver/pkg/storage）是 apiserver 与后端的唯一接触面；etcd3 store 是该接口在 v1.30.3 原生栈的唯一实现。codec 负责对象序列化，pathPrefix /registry/ 与 resourcePrefix 决定 key 命名，value.Transformer 处理加密与压缩。

etcd/13 已钉「只有 apiserver 直连 etcd」。本轴深化：写失败的 3 个落点——拒绝于 admission（不进 storage）、GuaranteedUpdate 冲突（rv 不匹配）、etcd3 本身（quota/Raft）——三者证据包完全不同。

「写成功但对象不符合预期」或「etcd 健康但 apiserver 写超时」优先落本轴。展开见 第 3 篇、第 4 篇。

Watch / cache 轴

定义：cacher（k8s.io/apiserver/pkg/storage/cacher）在 storage.Interface 之上维护一个按 GVR 分片的内存缓存，向多个 client Watch 扇出事件，同时对满足一致性条件的 List 走缓存路径。bookmark 事件推进 client 侧的 resourceVersion 锚点；cache miss 会打穿到 etcd。

410 Gone 可能来自两处：etcd 侧的 ErrCompacted（etcd compaction 窗口）与 cacher 侧的 watch channel overflow 或 bookmark 过期。两者排障路径不同——前者查 etcd MVCC 轴，后者查 apiserver watch_cache_capacity。

「Watch 断流但 PUT 仍成功」或「controller 大面积触发 resync」优先落本轴。展开见 第 5 篇–第 7 篇。

Admission 轴

定义：mutating admission 先运行（含 Mutating Webhook），再运行 validating admission（含 Validating Webhook）。内置插件在 k8s.io/apiserver/pkg/admission/ 中注册；Webhook 通过网络调用出站。每个 Webhook 有独立的 timeoutSeconds 与 failurePolicy（Fail/Ignore）。

「Create 失败但 etcd 无写入」或「Write 延迟高但 etcd 指标正常」优先落本轴。展开见 第 8 篇–第 9 篇。

AuthN / AuthZ / Audit 轴

定义：请求在 HandlerChain 早期即完成认证（Bearer/SA token/OIDC）和授权（RBAC/Node/Webhook）；audit 事件在该阶段产生，不经 storage。401/403 不会产生 etcd 写入。

「403 但 etcd 有 Pod 记录」或「audit log 有请求但 etcd 无变更」优先落本轴。展开见 第 10 篇–第 11 篇。

流控与可用性轴

定义：APF（API Priority and Fairness，k8s.io/apiserver/pkg/util/flowcontrol）在 HandlerChain 最外层对入站请求分组排队；max-in-flight 是 APF 之前的简单上限。两者都可以产生 429 或导致 client 侧感知 504，与 etcd lag 产生的 504 证据包完全不同。

「apiserver CPU 正常但请求排队」或「etcd 指标健康但 apiserver 返回 504」优先落本轴。展开见 第 12 篇。

三、坐标系背后的三个不变量

1. 唯一写入方：只有 kube-apiserver 写 etcd（原生栈）；scheduler/controller/kubelet 写 apiserver REST。Saltzer 端到端保证建立在这一前提上——任何绕开 apiserver 直写 etcd 的操作都会跳过 admission、RBAC 与字段验证。

2. 串行失败，分层落格：一次 Create 请求沿 HandlerChain 推进——APF/max-in-flight → authn → authz → audit → admission → storage。任何一层拒绝，请求不继续。因此「失败在哪层」有唯一答案，不能混成「apiserver 慢」。

3. watch cache 改变 etcd 负载形态：cacher 把多个 client Watch 合并为一条 etcd Watch；满足条件的 List 走缓存不穿透 etcd。这使 etcd 的 QPS 与 apiserver 侧的请求数解耦——etcd 指标健康不等于 apiserver 侧 Watch 正常，反之亦然。排障时要分别看两侧指标。

四、设计谱系：从 etcd 适配层到 generic apiserver

Saltzer et al. 端到端论证（TOCS 1984）
  → K8s 控制面设计（2014–）：唯一持久化入口 + 准入链
  → generic apiserver（k8s.io/apiserver）：可复用的 REST/watch/admission 框架
  → kube-apiserver v1.30.3：
      HandlerChain（APF → authn → authz → audit → admission）
      → storage.Interface（etcd3 实现）
      → watch cache / cacher（List/Watch 分层）
  → 仍争：watch cache SLO 与 etcd compaction 联合调参；Kine 兼容层语义差

五、16 篇路线与阅读建议

flowchart TD
  overview["01 Overview"] --> reqpath["02 Request Path"]
  reqpath --> storage["03 storage etcd3"]
  storage --> rv["04 resourceVersion"]
  rv --> cacher["05 Watch Cache"]
  cacher --> list["06 List Pagination"]
  list --> watch["07 Watch Server"]
  watch --> adm["08 Admission"]
  adm --> webhook["09 Webhooks"]
  webhook --> authn["10 Authentication"]
  authn --> authz["11 AuthZ Audit"]
  authz --> apf["12 APF"]
  apf --> ext["13 CRD Boundary"]
  ext --> ops["14 Ops Upgrade"]
  ops --> trouble["15 Troubleshoot"]
  trouble --> select["16 Selection"]
  overview --> select

读法：先读本篇；若症状是「etcd 健康但 apiserver 504」，优先 02→12→15；若是「Watch 断流或 410 Gone」，优先 04→05→07→15；若是「Create 失败但 etcd 无写入」，优先 02→08→09→15。etcd 侧五轴（no leader / quota / ErrCompacted / Lease TTL）见 etcd/15；本系列不重写 etcd 内核。

每篇一句话价值点

六、开放问题：watch cache SLO 与 etcd compaction

etcd/13 已指出：compaction 保留窗口与 controller 断连时长共同决定 catch-up 成本。watch cache 在 apiserver 层增加了一个缓冲，但并未消除根本矛盾：

开放问题：apiserver watch cache 目前没有一个可以独立监控的 SLO——是否「足够新」取决于多个运行时条件（cacher 内部 startRevision、etcd compaction --auto-compaction-retention、controller 的 Watch 重连时间窗口）。三者的联合调参没有统一的官方公式，也没有已 peer-reviewed 的模型。Kleppmann (2017, Designing Data-Intensive Applications) 的外部一致性模型可作为分析框架，但 apiserver 缓存的精确 staleness bound 仍是工程估算而非形式证明。排障时若 controller 反复 full-resync，应分别查三个变量而不是默认调大 compaction 窗口。

本系列 第 5 篇 与 第 16 篇 展开；etcd/12 给 compaction 侧参数。

七、本篇不写什么

• etcd Raft/WAL/MVCC 内核（外链 etcd 系列）。
• scheduler/controller-manager/kubelet 内核全书。
• CRD codegen / API 聚合实现全书（第 13 篇停损线）。
• CNI / Service / Ingress 数据面全书（外链 k8s-network）。
• 未实测 apiserver vs 直连 etcd P99/QPS 排行榜。
• 把 live docs 后版本能力写成 v1.30.3。
• 伪造 kubectl trace、etcd metrics 截图。

参考资料

规范 / 官方文档 / 源码（A）

• Kubernetes v1.30.3（源码 tag v1.30.3）
• kubernetes/kubernetes tag v1.30.3：staging/src/k8s.io/apiserver/
• Kubernetes · API Concepts（Watch/resourceVersion 语义）
• Kubernetes · Configure and upgrade etcd
• etcd v3.5.33（存储后端）

论文 / 书（A/B）

• Saltzer, J. H., Reed, D. P., & Clark, D. D. (1984). End-to-end arguments in system design. ACM Transactions on Computer Systems, 2(4).
• Li et al. (2017). etcd: A Distributed Key-Value Store… USENIX ;login:.
• Kleppmann, M. (2017). Designing Data-Intensive Applications. O’Reilly.（外部一致性模型参考框架）

站内对照（A/B）

• etcd/01 · 生产全景
• etcd/13 · K8s 控制面耦合
• distributed/50 · etcd 深度解剖
• k8s-network/

实验台账

• 本篇无集群实测；无伪造 kubectl / etcdctl 输出。

上一篇：系列目录

下一篇：apiserver 进程与请求路径