13.1 聚合层:apiserver 的扩展点
K8s 的能力不只有内置资源(Pod、Deployment、Service)——它还能挂第三方 API(metrics、网关、自定义业务资源)。挂载的机制就是聚合层(kube-aggregator)。本节解剖这个「apiserver 的扩展点」:怎么让一个集群有一致入口、多个 API 服务。
一个集群一个 API 入口
聚合层解决的核心问题:客户端怎么在一个入口访问所有资源。
kubectl get pods → 核心 apiserver
kubectl get metrics → 聚合层的 metrics API 服务
kubectl get widgets → 聚合层的自定义 API 服务
三者共享同一个 API 入口(https://cluster:6443)、同一套鉴权、同一个发现机制。客户端不需要知道「哪个服务在处理我的请求」——API 的统一性是聚合层提供的。
聚合层的三个职责
kube-aggregator(聚合层)不是核心 apiserver,是一个「路由 + 委托」的代理层。三个职责:
| 职责 | 做法 |
|---|---|
| 路由 | 把 /apis/ |
| 鉴权委托 | 把客户端的身份/权限委托给后端 API 服务校验 |
| 发现聚合 | 把各 API 服务的发现信息合并进 /apis 目录 |
核心 apiserver 与聚合层的分工:核心管内置资源,聚合层管扩展资源。聚合层把多个 API 服务「聚」成一个统一入口——这正是它名字的含义。
APIService:注册一个扩展服务
把第三方 API 挂进聚合层,靠 APIService 对象注册:
apiVersion: apiregistration.k8s.io/v1
kind: APIService
metadata:
name: v1.metrics.k8s.io
spec:
group: metrics.k8s.io
version: v1
service: # 后端 API 服务
name: metrics-server
namespace: kube-system
注册后:/apis/metrics.k8s.io/v1 的请求被聚合层转发给 kube-system/metrics-server。APIService 是「把某个 API 服务挂到统一入口」的注册表。
转发与鉴权:一致的体验
聚合层转发请求时,保持「入口一致」的体验:
| 环节 | 聚合层行为 |
|---|---|
| 鉴权 | 客户端身份原样传给后端(delegated authz) |
| 准入 | 后端自行处理(聚合层不越俎代庖) |
| 发现 | 各服务的 API 信息汇入 /apis 目录 |
客户端的一次请求穿过聚合层到达后端,鉴权信息不丢失——后端能用同一套 RBAC 决定「这个用户能不能读这些数据」。对客户端而言,这就是「一个集群、一套 API」:路由、鉴权、发现都由聚合层统一处理。
为什么需要聚合层:核心不膨胀
聚合层的存在理由——核心 apiserver 不该无限膨胀:
| 方案 | 问题 |
|---|---|
| 所有资源都内置 | 核心无限膨胀、发版绑定 |
| 每个扩展一套独立入口 | 客户端要连多个服务、多套鉴权 |
| 聚合层 | 核心保持精简、扩展共享入口 |
聚合层把「扩展能力」与「核心演进」解耦:第三方 API 服务独立部署、独立演进,通过聚合层挂进集群,不用改核心。这和第 11 章 webhook 外置是同一哲学——能力外置、入口统一。
聚合层 vs 准入链:两个扩展点对比
K8s 有两个「扩展点」,常被混淆:
| 准入链(11 章) | 聚合层(本节) | |
|---|---|---|
| 位置 | 写路径内 | API 入口 |
| 管什么 | 请求内容的把关/加工 | 新资源/新 API 的挂载 |
| 后端 | webhook 服务 | API 服务 |
| 类比 | 写路径的策略层 | 入口的扩展点 |
准入链扩展「写请求怎么处理」,聚合层扩展「集群有哪些 API」。前者在已有的对象上把关,后者引入新的对象类型。一个项目往往两者都用:自定义资源(13.2 节)经聚合层暴露、业务 webhook 在准入链把关。
聚合层转发的数据面细节:身份怎么传
聚合层转发不只是「把 URL 换一下」——它要把客户端的身份原样带给后端:
| 传递内容 | 方式 |
|---|---|
| 用户/组 | 认证头、请求头原样透传 |
| TLS 客户端证书 | 可配置跳过校验(insecureSkipTLSVerify) |
| 授权决策 | 委托给后端(delegated authz) |
「身份透传」是聚合层的关键细节:后端 API 服务要能用客户端的身份做自己的 RBAC 决策(这个用户能不能读 metrics)。如果聚合层把身份丢了,后端只能匿名放行或匿名拒绝——鉴权的一致性被破坏。
聚合层 vs 网关的差异在这里:普通网关转发请求不问身份,聚合层必须保身份、还要在必要时代校验。聚合层不是「反代」,是「K8s 语义的延伸」——它转发的不只是请求,还有集群的鉴权/发现语义。
APIService 的健康:后端挂了会怎样
聚合层转发到后端,后端也会挂。APIService 的健康由 Available 条件表达:
kubectl get apiservice
v1.metrics.k8s.io Local True ... # Available=True 正常
v1.widgets.example Local False ... # Available=False 后端不可用
后端不可用的表现:/apis/<group>/<version> 的请求报错(连接失败、超时);但核心资源不受影响(聚合层只代理扩展路径)。聚合层的故障是「局部」的——扩展 API 挂了,内置 API 照常。
这给扩展服务的设计启示:聚合层后端要有自己的健康检查、要独立部署。扩展 API 的可用性 = 聚合层可用性 + 后端可用性——后端挂了,发现目录里还在但请求全失败。运维要在「发现」之外监控「可用性」,两者是两回事。
一次聚合层请求的完整旅程
跟着一个 kubectl get metrics 走完聚合层:
客户端 → LB → 核心 apiserver
→ 识别出 /apis/metrics.k8s.io/v1 是扩展路径
→ 交给聚合层处理
→ 聚合层查 APIService 注册(metrics-server)
→ 转发请求(保留客户端身份)
→ metrics-server 处理 → 返回响应
→ 聚合层把响应原样返回客户端
几个关键细节:
| 环节 | 细节 |
|---|---|
| 识别 | 核心 apiserver 先认出「这是扩展路径」,交给聚合层 |
| 注册查找 | 聚合层查 APIService 对象找后端 |
| 转发 | 请求头/身份透传,TLS 按配置 |
| 响应 | 原样回传,不二次加工 |
客户端完全无感:它看到的就是「一个 /apis/metrics.k8s.io/v1 的资源」,背后是转发到 metrics-server。聚合层的复杂度全在「客户端看不到」的那一侧——这正是扩展 API「入口统一」的意义。一次聚合层请求的旅程,本质是「入口统一、后端分散」的一次演示。
聚合层 vs 反向代理:差别在哪
有人把聚合层类比「反向代理」。差别是关键:
| 维度 | 反向代理 | 聚合层 |
|---|---|---|
| 路由依据 | URL/域名 | APIService 注册(group/version) |
| 鉴权 | 通常自己做 | 委托给后端(delegated authz) |
| 发现 | 无 | 汇入 /apis 目录 |
| 语义 | 纯转发 | K8s API 语义的延伸 |
聚合层是「带 K8s 语义的反向代理」:它不止转发流量,还参与发现(13.3 节)、保持鉴权一致、让扩展 API 像内置 API。用「反代」类比聚合层会漏掉最重要的部分——发现与鉴权委托,正是这两个「非转发」职责让它成为 K8s 的扩展点。
三个常见误解
- 「聚合层是核心 apiserver 的一部分」——准确说是「与核心一起运行、但职责独立的代理」——路由/委托由它做,内置资源仍由核心处理。
- 「扩展 API 服务要改核心」——错误。独立部署,通过 APIService 注册即可挂进统一入口。
- 「聚合层只服务 CRD」——错误。聚合层挂「任意 API 服务」(metrics-server、自定义服务);CRD 是另一条更简单的扩展路径(13.2 节)。
本节 lab
本节验证统一 API 入口下的存储语义(聚合层后端与核心共用同一套对象/版本模型):
cd private/labs/k8s-ctrl-lab
go test ./api -run 'TestRVMonotonic|TestOptimisticConflict' -v
TestRVMonotonic:统一入口下对象 RV 单调递增、UID 稳定——「一个集群一套 API」的一致性基础。TestOptimisticConflict:并发写冲突返回 409——「扩展资源与核心资源用同一套乐观锁」。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。