《Kubernetes 分布式系统原理深入解析》13.3 API 发现与扩展路径选型

客户端怎么知道集群有哪些 API?靠发现机制(discovery):/apis 目录列出版本与资源,kubectl 与客户端据此构建请求。发现机制把核心资源、聚合层服务、CRD 全部汇入同一目录。扩展 API 有两条路径——聚合层(挂服务)与 CRD(声明资源)——本节给选型判据与发现机制的原理。lab 用 api 包验证统一存储的版本语义作为选型基础。

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
核心 apiserverPod/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 单调递增——「服务型扩展」与「资源型扩展」共享的一致性基础。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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