> 本文是写作规划，不是可发布正文。拆解对象：kube-apiserver 在 Kubernetes 控制面中的生产内核——以 Kubernetes v1.30.3（源码 tag v1.30.3）为主线，把一次 REST 请求从 HandlerChain → AuthN/AuthZ → Admission → stor…

本文介绍Kubernetes控制面内核系列文章，聚焦kube-apiserver与etcd间的存储层。文章指出当前知识缺口，定义五条排障坐标系：Storage/etcd耦合、Watch/cache、Admission、AuthN/AuthZ、流控。版本锚定v1.30.3，提供16篇阅读路线，强调通过分层定位504、410等故障，而非简单直连etcd排查。

本文拆解kube-apiserver请求路径，从TLS终止到etcd写入，需经过APF流控、认证、授权、Admission等拦截点。APF在认证前，Admission在REST handler内。请求失败时需区分是Webhook拒绝、APF排队还是etcd问题，不能简单归因于etcd慢。GVR路由将请求映射到对应storage实现。

kube-apiserver通过storage.Interface与etcd交互，存储protobuf序列化数据，key由前缀拼接，value经Transformer加密。GuaranteedUpdate用etcd Txn实现乐观并发写，Create/Delete/Watch各有路径。排障需关注etcd延迟、转换失败等指标，区分apiserver与etcd问题。

本文解析Kubernetes中resourceVersion字段的语义与常见误用。该字段源自etcd的mod_revision，仅对同一对象有单调性，跨对象比较无意义。文章详述了Watch起点、continue token分页机制及一致性保证，指出不同读路径的一致性差异，并解释了410 Gone错误的来源与处理方式。

本文介绍Kubernetes v1.30.3中kube-apiserver的watch cache机制，核心是Cacher组件：它通过watchCache环形缓冲存储事件，用Ready门控制启动同步，dispatch实现内存多路分发，bookmark维持资源版本推进。当缓存未命中或未就绪时回退到etcd，可能引发List风暴，需调整缓存容量和bookmark频率优化。

本文分析Kubernetes中`kubectl get pods -A`在大集群下变慢的原因，指出常见误判为etcd慢，实际可能是cacher或etcd3的List路径问题。文章详解了`resourceVersion`语义（`rv=""`走etcd强一致，`rv="0"`走缓存）、continue token的编码结构、分页成本模型，以及label selector在etcd侧无索引导致的全量扫描放大问题，并给出优化建议。

本文介绍Kubernetes v1.30.3中apiserver的Watch服务端路径，涵盖建立流程、resourceVersion语义（0与具体RV差异）、410 Gone的两大来源（cacher ring buffer滑出窗口或etcd ErrCompacted上浮）及分列方法、timeout与连接生命周期（含bookmark作用），并说明与client-go Informer的边界及WatchList功能现状。

本文介绍Kubernetes v1.30.3中Admission链的机制与排障。请求经AuthN、AuthZ后进入Admission，分Mutating和Validating两阶段，失败即返回错误，不写入etcd。内置插件如NamespaceLifecycle、LimitRanger、ResourceQuota在注册入口装配。Webhook集成有超时和failurePolicy，争议在于fail-open与fail-closed的可用性/安全性权衡。排障时需区分Admission轴与存储问题。

本文介绍Kubernetes v1.30.3中Admission Webhook的生产配置与故障排查。核心要点：Mutating Webhook串行执行可修改对象，Validating Webhook并行执行仅校验；timeoutSeconds默认10秒，failurePolicy决定超时后拒绝或放行；生产需配置副本、namespaceSelector避免自锁，并确保幂等性。CEL ValidatingAdmissionPolicy作为无外部依赖的替代方案，适合纯校验场景。排障时关注webhook延迟指标，而非etcd。

本文介绍Kubernetes v1.30.3中kube-apiserver的认证链结构，涵盖X509证书、SA token、静态Bearer、Bootstrap、OIDC及Webhook等认证器边界。文章区分401（认证失败）、403（授权失败）、503（存储或Webhook故障）等错误码，并讨论SA token过期、OIDC JWKS缓存等排障要点，强调认证与授权职责分离。

本文介绍Kubernetes v1.30.3的授权与审计机制。授权链依次为Node、RBAC、Webhook Authorizer，任一允许即放行，否则返回403。RBAC为纯Allow模型，无显式Deny规则。SAR/SSAR接口用于权限检查。Audit分四级记录请求，403仅来自K8s授权链，非etcd权限。排障需查Audit日志和status.reason。

本文介绍Kubernetes v1.30中kube-apiserver的过载保护机制，包括旧的max-in-flight全局并发限制和新的API Priority and Fairness（APF）公平排队系统。APF通过FlowSchema和PriorityLevel配置，使用SFVR算法实现流量分类和公平调度。文章详细区分429、504等超载症状的排查路径，强调先检查APF等待指标，再排查etcd或Webhook，并提供默认配置和调参建议。

本文介绍Kubernetes中两条API扩展路径：CRD v1和Aggregated API。CRD请求在apiserver内部处理，存储于etcd，可能涉及conversion webhook；Aggregated API则代理到外部Extension Server。文章详述各自失败模式、排障方法，并明确边界：CRD codegen、scheduler/controller、kubelet等不在讨论范围。

kube-apiserver无leader选举，多实例并发运行共享etcd，与controller-manager等不同。运维要点包括：滚动升级逐实例替换、处理409冲突、APF容量为各实例之和。核心flag有--etcd-servers、--etcd-servers-overrides（分集群events）、--request-timeout、--shutdown-delay-duration（需≥LB健康检查间隔×失败阈值）、--encryption-provider-config。升级顺序：etcd→apiserver→controller-manager→scheduler→kubelet，版本偏差不超过2个minor。健康检查中/readyz反映etcd连通性，/healthz不等价于etcd健康。

本文介绍kube-apiserver排障方法，提出五轴坐标系：Storage/etcd、Watch/cache、Admission、Auth、APF。通过症状映射表快速定位问题轴，如401/403查Auth，503查Admission，504查APF，410查Watch。强调先定轴再下钻，避免误操作，并列出关键metrics和命令，区分apiserver与etcd问题，指导高效排障。

本文总结kube-apiserver排障系列终章，提出机制排除树，按症状（401/403、webhook 503、APF 429、etcd延迟、Watch错误等）定位至Auth、Admission、APF、Storage或Watch轴。回收etcd系列停损线，明确Kine SQL后端Watch语义差异及events分集群边界。列出三个开放问题（watch cache SLO、线性读一致性、Lease fencing），强调以实测关闭，并给出ADR友好收束建议。

本文介绍kube-apiserver生产内核系列，聚焦控制面故障排障，以Storage/Watch/Admission/Auth/APF五轴为坐标系，规划16篇阅读路线。内容涵盖请求路径、watch cache、resourceVersion、Webhook、APF等机制，版本锚定Kubernetes v1.30.3，旨在帮助SRE归因504、410等错误，区分直连etcd与apiserver排障边界。

本文讨论Kubernetes控制面与etcd的耦合关系。kube-apiserver是唯一直接连接etcd的组件，通过watch cache合并客户端请求。resourceVersion对应etcd的mod revision，用于乐观并发控制。Node Lease通过etcd Lease机制实现心跳，减少写入放大。排障时需区分apiserver超时与etcd五轴问题，避免误判。