【kube-apiserver】控制面全景：缺口、五轴坐标系与 16 篇路线
内容提要
本文介绍Kubernetes控制面内核系列文章，聚焦kube-apiserver与etcd间的存储层。文章指出当前知识缺口，定义五条排障坐标系：Storage/etcd耦合、Watch/cache、Admission、AuthN/AuthZ、流控。版本锚定v1.30.3，提供16篇阅读路线，强调通过分层定位504、410等故障，而非简单直连etcd排查。
延伸解读
排障先定轴，再下钻组件
文章提出五条坐标系（Storage/etcd、Watch/cache、Admission、AuthN/AuthZ、流控），强调排障时应先判断问题属于哪条轴，再深入具体组件，而非直接怀疑etcd或盲目扩副本。例如504可能源于APF排队或etcd ReadIndex，410 Gone可能来自etcd compaction或cacher bookmark过期，不同轴对应不同证据包和排查路径。
etcd健康不等于apiserver正常
由于watch cache的存在，apiserver与etcd的负载形态解耦：多个client的Watch被合并为一条etcd Watch，满足条件的List走缓存不穿透etcd。因此etcd指标健康不代表apiserver侧Watch正常，反之亦然。排障时需分别查看两侧指标，避免因etcd健康而忽略apiserver内部问题。
端到端原则下的唯一写入方
文章引用Saltzer的端到端论证，说明Kubernetes控制面将RBAC、Admission、字段验证等可靠性保证集中在apiserver层，etcd只接收已授权的protobuf字节。因此只有apiserver持有etcd证书，任何绕开apiserver直写etcd的操作都会跳过这些关键检查，破坏端到端保证。
Q&A
kube-apiserver 与 etcd 之间的知识缺口是什么？
知识缺口在于：一次 Create/Update 从 REST 到 etcd 的失败落在 HandlerChain 的哪个插槽；504 是 APF 排队还是 etcd ReadIndex；410 Gone 是 cacher bookmark 过期还是 etcd ErrCompacted；Webhook 503 与 storage 超时如何分列，以及何时不该直连 etcd 排障 apiserver。
kube-apiserver 排障的五条坐标系是什么？
五条坐标系是：Storage/etcd 耦合、Watch/cache、Admission、AuthN/AuthZ、流控。每条轴对应不同的失败表象和排障路径。
如何区分 504 错误是 APF 排队还是 etcd ReadIndex 问题？
504 错误可能来自 APF 排队或 etcd ReadIndex。若 apiserver CPU 正常但请求排队，或 etcd 指标健康但 apiserver 返回 504，优先考虑流控轴（APF）；若 etcd 有 lag 或 ReadIndex 问题，则属于 Storage/etcd 耦合轴。需要分别检查 APF 队列深度和 etcd 的 ReadIndex 延迟。
410 Gone 错误可能由哪些原因引起？
410 Gone 可能来自两处：etcd 侧的 ErrCompacted（etcd compaction 窗口）与 cacher 侧的 watch channel overflow 或 bookmark 过期。前者查 etcd MVCC 轴，后者查 apiserver watch_cache_capacity。
为什么只有 kube-apiserver 持有 etcd 证书？
因为 Kubernetes 控制面遵循 Saltzer 端到端论证，可靠性保证应在通信端点实现。RBAC 决策、Admission mutation、字段验证都在 apiserver 层完成，etcd 只见已授权的 protobuf bytes。只有 apiserver 直连 etcd，才能保证端到端的安全和一致性。
watch cache 如何影响 etcd 的负载？
watch cache 将多个 client Watch 合并为一条 etcd Watch，满足条件的 List 走缓存不穿透 etcd，从而降低 etcd 的 QPS，使 etcd 指标与 apiserver 请求数解耦。
文章推荐的 16 篇阅读路线中，针对 'etcd 健康但 apiserver 504' 的路径是什么？
针对 'etcd 健康但 apiserver 504'，优先阅读 02（进程与请求路径）→ 12（APF）→ 15（排障五轴）。
文章提到的开放问题是什么？
开放问题是：apiserver watch cache 目前没有一个可以独立监控的 SLO，其 '足够新' 取决于 cacher 内部 startRevision、etcd compaction 保留窗口和 controller 重连时间窗口，三者联合调参没有统一公式，staleness bound 仍是工程估算。
