【kube-apiserver】CRD / aggregation / 扩展边界：API 扩展停损线
内容提要
本文介绍Kubernetes中两条API扩展路径：CRD v1和Aggregated API。CRD请求在apiserver内部处理，存储于etcd，可能涉及conversion webhook；Aggregated API则代理到外部Extension Server。文章详述各自失败模式、排障方法，并明确边界：CRD codegen、scheduler/controller、kubelet等不在讨论范围。
延伸解读
两条扩展路径的排障差异
CRD 与 Aggregated API 的失败模式不同：CRD 请求在 apiserver 内部处理，错误通常来自 conversion webhook 或存储层；而 Aggregated API 请求被代理到外部 Extension Server，错误多源于下游服务。排障时需区分：CRD 问题查 apiserver 日志和 etcd 延迟，Aggregated API 问题则先检查 Extension Server 状态和证书。
conversion webhook 超时与 etcd 慢的区分
当 CRD 多版本转换依赖 webhook 时，超时可能被误判为 etcd 性能问题。文章明确指出：conversion webhook 超时不等于 etcd 慢，排障时应先测量 webhook 端到端延迟，再检查 etcd_request_duration_seconds。这有助于避免在错误的方向上浪费时间。
扩展 API 的边界：哪些不属于 apiserver 范畴
文章划定了停损线：CRD codegen、controller-runtime、scheduler/controller 内核以及 kubelet 数据面均不在讨论范围。这些组件要么是客户端库，要么是 apiserver 的客户端，不直接持有 etcd 连接。理解这一边界有助于聚焦问题域，避免将控制面逻辑层或数据面问题误归因于 apiserver。
Q&A
Kubernetes 中 CRD 和 Aggregated API 两条扩展路径有什么区别？
CRD 请求在 kube-apiserver 内部处理，存储于 etcd，可能涉及 conversion webhook；Aggregated API 则通过 APIService 将请求代理到外部 Extension Server，由 Extension Server 自行管理存储。
CRD 对象的 etcd 存储 key 是什么格式？
以 group=example.com、version=v1、plural=foos 为例，etcd key 形如 /registry/example.com/foos/<namespace>/<name>，存储格式默认为 protobuf 或 JSON，且 encryption provider 配置对此路径生效。
conversion webhook 不可达或超时会导致什么现象？
conversion webhook 不可达时，GET/Watch CR 可能返回 500 或 503；conversion webhook 慢（超过 timeoutSeconds）会导致请求超时，apiserver_request_duration_seconds 增大。排障时先查 webhook 端到端延迟，再查 etcd_request_duration_seconds。
Aggregated API 请求转发到 Extension Server 时，kube-apiserver 如何处理？
请求经 apiserver 认证/授权后，聚合层将原始请求（含 Authorization header 中的 impersonation 信息）代理到 Extension Server，使用 mTLS 连接。Extension Server 自己管理存储，可以是独立 etcd、内存或任意后端。
Extension Server 不可用或证书过期时，会出现什么故障？
Extension Server 未运行时，APIService 状态 Available=False，请求返回 503；证书过期会导致 mTLS 握手失败，同样表现为 503。排障起点是检查 APIService 状态和证书有效期。
CRD codegen、scheduler/controller、kubelet 是否属于本系列讨论范围？
不属于。CRD codegen 和 controller-runtime 属于开发工具；scheduler/controller-manager 是 apiserver 的客户端，不持有 etcd 连接；kubelet 数据面也不在范围内。本系列聚焦 kube-apiserver 的 Storage/Watch/Admission/APF 等轴。
CRD 和 Aggregated API 的失败模式有何不同？
CRD 失败时 kube-apiserver 进程内有确定的 Storage/Admission 报错；Aggregated API 失败时 kube-apiserver 只是代理，错误来自下游 Extension Server，不要把 Extension Server 不可用误判为 kube-apiserver etcd 连接问题。
