kube-apiserver / Kubernetes 控制面内核：storage、cacher、Admission 与 APF

etcd / 生产内核 已把 单 Raft 组 → WAL/MVCC → Watch/Lease 钉到五轴排障；etcd/13 钉过 apiserver↔︎etcd 分层、resourceVersion 与 Node Lease，但写明 apiserver 实现全书不在此展开。分布式系统百科 · etcd 与 Kubernetes 网络 分别覆盖协调层百科与 Pod 数据面。中间仍缺一层：一次 Create/Update 卡在 Admission 还是 storage.Interface、504 是 APF 排队还是 etcd ReadIndex、410 Gone 是 cacher bookmark 还是 etcd ErrCompacted、Webhook 503 与 storage 超时如何分列，以及何时不该直连 etcd 排障 apiserver。

本系列回答：kube-apiserver 生产路径里 REST 请求失败落在哪一层，watch cache 相对 etcd 直读换来了什么排障坐标，以及控制面 504 如何与 etcd 五轴分列。

写：

• generic apiserver 与 HandlerChain；storage.Interface + etcd3。
• resourceVersion / bookmark；watch cache / cacher。
• List/Pagination、Watch 服务端路径、Admission/Webhook、AuthN/AuthZ/Audit、APF。
• CRD/aggregation 边界、运维升级、排障五轴、相对直连 etcd/Kine 的选型。

不写：Helm 安装全书、scheduler/controller/kubelet 内核重讲、CRD codegen 全书、CNI/mesh 数据面、未实测 P99 排行。不把 apiserver 写成透明 etcd 代理。 持久化层见 etcd/；Pod 网络见 k8s-network/、cilium/。

系列状态：01–16 已发布（2026-08-28）。 规划见 PLAN.md。机制结论钉源码 tag v1.30.3（Kubernetes v1.30.3），不以 kubernetes.io/docs/ 最新版冒充该版本。etcd 后端对照钉 etcd v3.5.33。无真实 K8s 集群则不粘贴伪造 kubectl 输出 / apiserver metrics。实验台账未跑。

版本锚定：Kubernetes v1.30.3（源码 tag v1.30.3；与 istio-xds 对照锚一致）。etcd 后端常见为 3.5.x——存储耦合机制以 v1.30.3 apiserver 源码为准，etcd 侧五轴见 etcd 系列。

适合谁看

• 平台 / SRE，要把「apiserver 504 / controller 不同步」推进到「能归因 Storage/Watch/Admission/Auth/APF 五轴」。
• 读过 etcd/ 或 etcd/13，需要 apiserver 侧机制全书的读者。
• 在原生 etcd 栈、Kine、events 分集群之间做控制面架构选型的架构师。

与已有系列的分工

读法：只要「只有 apiserver 连 etcd」→ etcd/13 足够；要「storage vs cacher vs admission vs APF 分列、504 归因」→ 本系列 01 → 03 → 05 → 12 → 15。

一、这个领域最值得关注的 5 个问题

1. 一次 Create/Update/Patch 从 REST 到 etcd，失败落在哪一层？ → 第 2–4、8–9、15 篇。
2. resourceVersion、bookmark、410 与 etcd ErrCompacted 如何分列？ → 第 4–7、15 篇。
3. watch cache 如何改变 etcd 负载？List 风暴从哪触发？ → 第 5–7、15 篇。
4. Webhook 慢、APF 排队、504 与 etcd 指标如何分列？ → 第 9、12、15 篇。
5. 何时查 etcd 系列、何时查 apiserver？Kine/events 分集群边界？ → 第 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

三、目录与每篇价值点

第一部分：模型与存储（01–05）

1. 控制面全景
   • 相对 etcd/13、distributed/50 的缺口；五轴与 16 篇路线。
2. apiserver 进程与请求路径
   • generic apiserver、HandlerChain、REST 路由。
3. storage.Interface 与 etcd3
   • codec、prefix、CRUD/Watch 到 etcd。
4. resourceVersion 与 Revision 映射
   • mod revision、continue、一致性读期望。
5. Watch cache / cacher 架构
   • dispatch、bookmark、cache miss 穿透。

第二部分：读写、准入与身份（06–11）

6. List / Pagination / 一致性 List
   • continue token、etcd Range 成本。
7. Watch 路径（服务端视角）
   • 长连接、410/timeout。
8. Admission 链概览
   • 准入顺序、插件与 webhook 边界。
9. Mutating / Validating Webhook
   • timeout、failurePolicy。
10. Authentication
    • SA、Bearer、OIDC 边界。
11. Authorization 与 Audit
    • RBAC、SAR、audit 分列。

第三部分：流控、运维与收束（12–16）

12. APF 与 max-in-flight
    • 公平排队、504 与 etcd lag 分列。
13. CRD / aggregation / 扩展边界
    • API 扩展停损线。
14. 运维与升级
    • HA、flags、与 etcd 联检。
15. 排障五轴
    • Storage/Watch/Admission/Auth/APF 口令表。
16. 选型收束与开放问题
    • 排除树；回收 etcd/13 apiserver 停损线。

参考

• PLAN.md — 逐章大纲、来源/实验/研究台账
• etcd / 生产内核
• etcd/13 · K8s 控制面耦合
• Kubernetes 官方文档

返回 全部系列索引