13.3 API 发现与扩展路径选型
前两节讲了两个扩展点:聚合层(13.1)与 CRD(13.2)。客户端怎么知道集群里有这些 API?靠发现机制(discovery)。本节解剖发现机制,并给出扩展路径的选型判据。
发现机制:客户端如何知道有什么
客户端(kubectl、controller、SDK)连接集群后,第一步是「发现」:
GET /api → 核心 API 组与版本
GET /apis → 全部 API 组(内置 + 聚合 + CRD)与版本
GET /apis/<g>/<v> → 该组下的资源列表(kind、verbs、子资源)
发现结果的形态:
{
"apiVersion": "v1",
"resources": [
{"name": "pods", "kind": "Pod", "verbs": ["get", "list", "watch", ...]},
{"name": "deployments", "kind": "Deployment", "verbs": [...]},
{"name": "widgets", "kind": "Widget", "verbs": [...]}
]
}
发现是「API 的目录服务」:它回答「集群里有什么、每个资源支持哪些操作」。客户端先查目录,再据此构造请求——这正是 3.1 节「先 list 后 watch」的起点(list 用发现到的路径)。
三种资源的统一发现
发现机制把三类资源汇进同一目录:
| 来源 | 资源 | 进入 /apis |
|---|---|---|
| 核心 apiserver | Pod/Deployment/… | 是 |
| 聚合层服务(13.1 节) | metrics/自定义服务资源 | 是(经聚合层) |
| CRD(13.2 节) | Widget 等自定义资源 | 是(apiserver 自动注册) |
客户端只需要查一次 /apis,就能看到集群里「所有」可用 API——不管它们是核心的、挂载的还是声明的。发现机制让「集群的 API 面」对外是统一的、可枚举的。
发现与控制器:client-go 用它建客户端
控制器(第 7-10 章)用 client-go 访问 apiserver,client-go 的底层依赖发现:
| client-go 环节 | 依赖发现 |
|---|---|
| RESTClient 构造 | 用发现的 group/version 拼 URL |
| 资源映射 | 用发现的 kind→resource 对应 |
| 列表/监听 | 用发现的路径与 verbs |
发现让「控制器怎么写客户端」变简单:不用硬编码资源路径,查询发现目录即可。这也是 API 扩展能无缝工作的前提——新挂的 API 进发现目录,client-go 天然能访问(配合 RBAC)。
扩展路径选型:CRD 还是聚合层
两条扩展路径,各有适用:
| 判据 | CRD | 聚合层 |
|---|---|---|
| 后端代码 | 不需要 | 要自己写 API 服务 |
| 资源类型 | 有 schema、存 etcd | 任意(存哪都行) |
| 子资源/多版本 | 内置支持 | 自己实现 |
| 语义定制 | 受限(schema 约束) | 完全自由 |
| 典型场景 | 业务资源、配置 | 指标 API、网关、混合协议 |
选型判断:
- 要一个「像 Pod 一样」的资源(schema、乐观锁、watch、子资源)→ CRD。它是「声明式扩展」——省后端代码。
- 要任意语义的 API(聚合任意数据源、非 REST 协议、自己控制存储)→ 聚合层。它给你「自由后端」。
- 两者可组合:CRD 声明资源 + webhook 在准入链把关(11 章)——业务资源的完整三件套。
一句话:CRD 是「资源型扩展」,聚合层是「服务型扩展」。要资源用 CRD,要服务用聚合层。
扩展路径与控制器:operator 的底座
第 9 章讲过「operator 模式」。把第 11-13 章串起来看,一个 operator 的完整底座:
CRD:声明自定义资源(如 EtcdCluster)
准入:Webhook 校验/注入(13.2 节的配套)
控制器:watch CRD 资源,调谐(第 6-10 章的方法论)
聚合层:(可选)挂指标/额外 API
operator 是「CRD + 控制器 + 可选 webhook」的组合:CRD 提供「自定义资源类型」,控制器提供「调谐语义」,webhook 提供「写路径把关」——三章的内容在这里汇成一种产品形态。K8s 的扩展设计(13 章)是为 controller pattern(第 6-10 章)服务的:让任何业务都能「声明资源 + 写控制器」地自动化。
发现缓存的代价:发现是「相对频繁」的读
客户端不能每次请求都查发现目录(那会放大到 apiserver)。kubectl 与 client-go 会把发现结果缓存在本地:
| 客户端 | 缓存策略 |
|---|---|
| kubectl | 本地 discovery cache(带过期) |
| client-go | 内存缓存 + 失效重查 |
kubectl --cached | 强制用缓存、不刷新 |
缓存带来了滞后:集群里新挂一个 API(CRD/APIService),客户端可能「暂时看不到」——因为它的发现缓存还没过期。发现是「有界的最终一致」(呼应 15.2 节):新 API 要等缓存刷新才能被所有客户端看到。
这也解释了「新装 CRD 后 kubectl get 不到」的常见坑:不是资源没建好,而是 kubectl 的发现缓存没过期。kubectl api-resources(或 --cached 前清缓存)就能看到。发现缓存把「API 面」的可见性从「即时」变成「最终一致」——这与控制器看对象的滞后是同一类现象。
版本在发现目录里的样子:一个资源、多个版本
发现目录里,同一种资源的不同版本是分开列出的:
resources:
- name: widgets # 简写:默认版本
- name: widgets/v1alpha1 # 该版本
- name: widgets/v1 # 另一版本
发现用 name/version 的形式表达「一个资源多个版本」(13.2 节)。客户端按自己支持的版本查对应条目——支持 v1 的控制器查 widgets/v1,还停在 v1alpha1 的旧客户端查 widgets/v1alpha1。发现目录把「多版本共存」变成可枚举的:每个版本单独一条,新旧客户端各取所需。
这与 13.2 节「新旧客户端共存」是同一件事的两面:转换函数让数据共享(13.2),发现条目让入口分明(本节)。版本演进的完整体验 = 转换 + 发现双配合。
发现与 kubectl 的日常 UX
kubectl 是发现机制最大的使用者,它的几个命令直接读发现结果:
| 命令 | 读什么 |
|---|---|
kubectl api-resources | 发现目录的资源列表(name/kind/verbs) |
kubectl explain pod | 单个资源的结构说明(schema 的面向用户版) |
kubectl get <kind> | 用发现把 kind 映射成资源路径 |
explain 尤其值得注意:它把「发现目录 + schema」翻译成人话——kubectl explain pod.spec.containers 告诉你这个字段是什么、什么类型。它是「API 的自文档」:不是写在别处的文档,而是从发现与 schema 实时生成的。
对用户的意义:发现机制不只有「客户端能用」,它还支撑「人能看」——api-resources 浏览集群有什么、explain 查字段怎么用。发现是「API 面」对人与程序共同的入口:程序用它构造请求,人用它理解集群——同一份目录,两种消费方式。
发现也要授权:目录不是公开的
发现目录不是「人人可看全部」。RBAC 过滤发现结果:
| 用户 | 看到 |
|---|---|
| 普通用户 | 有权限访问的资源子集 |
| 管理员 | 全部资源 |
| 匿名 | 最少(甚至空) |
发现目录是「权限裁剪后的」:kubectl get pods 能看到 Pod 是因为你被授权了;kubectl get secrets 看不到,也是因为没授权(发现的资源列表里就不出现)。发现不是「API 全录」,是「我可见的 API 录」。
这对安全的意义:扩展 API 也会被 RBAC 裁剪(13.3 节「扩展 API 有 RBAC」)——即使集群挂了敏感 CRD,未授权用户连「它存在」都发现不了。发现 + RBAC 的组合,让「API 面」既统一又可裁剪——这是它成为安全边界一部分的原因。
三个常见误解
- 「客户端要分别连各个 API 服务」——错误。发现机制 + 聚合层让所有 API 汇入统一入口。
- 「CRD 比聚合层强」——不准确。各有适用:CRD 省后端代码但语义受限,聚合层自由但要多写服务。
- 「扩展 API 没有 RBAC」——错误。扩展资源同样受 RBAC 保护(聚合层委托鉴权、CRD 资源可绑定 role)。
本节 lab
本节验证统一 API 下的存储语义(扩展路径选型的基础——所有扩展共享同一套对象/版本模型):
cd private/labs/k8s-ctrl-lab
go test ./api -run 'TestCRDVersionConversion|TestRVMonotonic' -v
TestCRDVersionConversion:CRD 多版本转换——「资源型扩展」的核心语义。TestRVMonotonic:统一入口下 RV 单调递增——「服务型扩展」与「资源型扩展」共享的一致性基础。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。