《Kubernetes 分布式系统原理深入解析》13.1 聚合层:apiserver 的扩展点

K8s 的核心 apiserver 不能什么都做,也不该什么都做。聚合层(kube-aggregator)把第三方 API 服务挂进统一的 API 入口:客户端从同一个 /apis 访问核心资源与扩展资源,聚合层做路由、鉴权委托与发现聚合。本节解剖聚合层的架构与『核心 + 扩展共享一条入口』的设计。lab 用 api 包的 store/crd 验证统一存储的版本语义。

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 服务校验
发现聚合把各 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——「扩展资源与核心资源用同一套乐观锁」。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图