Kubernetes kyaml openapi 采样指南:从活体集群生成并内嵌 OpenAPI Schema
Kubernetes kyaml openapi 采样指南:从活体集群生成并内嵌 OpenAPI Schema
本文是 sigs.k8s.io/kustomize/kyaml/openapi 模块的实操指南,围绕其 README.md 中描述的 "Sampling New OpenAPI Data" 流程展开:如何从一台运行中的 Kubernetes API 服务器上采集 OpenAPI 数据,将其转换为内嵌的 Go 资源(swagger.go / swagger.pb),并替换 kustomize kyaml 内置的默认 schema 版本。读完本文,你将掌握 make nuke、make all 以及分步重建(swagger.pb → swagger.go → openapiinfo.go)的完整操作,理解版本选择与预计算(precomputed)同步机制,并能结合源码弄清这些内嵌 schema 在运行时如何被 openapi.go 解析、索引和使用。
背景:为什么 kyaml 要把 OpenAPI 数据"编译进"二进制
kyaml(Kustomize 的 Kubernetes YAML 处理库)在做字段校验、合并(merge)、补丁(patch)等操作时,需要知道每个资源类型的字段结构、patch 策略、merge key 以及资源是命名空间级还是集群级。这些信息全部来自 Kubernetes 的 OpenAPI v2 schema。
为避免每次运行都去请求一个在线 API 服务器,kyaml 采用"静态内嵌"策略:在构建期把一份 OpenAPI schema 以二进制资源的形式打包进程序,运行时直接解析。当前仓库中这套资源位于:
- kubernetesapi/v1_21_2/swagger.pb:从活体集群采样的 Kubernetes OpenAPI schema(protobuf 序列化格式);
- kubernetesapi/v1_21_2/swagger.go:由 go-bindata 生成的 Go 资源文件;
- kustomizationapi/swagger.json 与 kustomizationapi/swagger.go:Kustomization 自身类型(如
kustomization.yaml的字段定义)的 schema; - kubernetesapi/openapiinfo.go:登记"内置了哪些版本"的注册表文件。
在 openapi.go 中可以看到这些资源的消费端:包级全局变量 kubernetesOpenAPIVersion 记录当前选中的 Kubernetes schema 版本,globalSchema(类型为 openapiData)保存解析后的 spec.Schema、按 yaml.TypeMeta(GVK)索引的 schemaByResourceType、命名空间归属表 namespaceabilityByResourceType 等(见 openapi.go#L25-L81)。initSchema() 在首次使用时延迟解析内嵌 schema(见 openapi.go#L666-L699),其中对 Kubernetes schema 走 protobuf 分支(parse(..., Proto)),对 Kustomization schema 走 JSON/YAML 分支。也就是说:README 描述的"采样流程"产出的 swagger.pb,正是运行时 parseBuiltinSchema 通过 kubernetesapi.OpenAPIMustAssetversion 读取的数据源(见 openapi.go#L702-L717)。
整体流程概览
README 描述的采样与内嵌流程可以拆成五步,全部由本目录下的 Makefile 驱动:
- 启动干净的 kind 集群:Makefile 会确保存在
kind二进制(目标$(MYGOBIN)/kind,默认拉取KIND_VERSION := "v0.11.1"对应的发布版,见 Makefile#L8),并用它创建一次性集群; - 从集群采样 schema:执行
./scripts/fetchSchemaFromCluster.sh $(API_VERSION),把/openapi/v2的响应落盘为kubernetesapi/swagger.pb(Makefile 目标kubernetesapi/swagger.pb,见 Makefile#L53-L55)。注意:API_VERSION ?= "v1.21.2"是默认值,可用变量覆盖; - 生成 go-bindata 资源:
./scripts/generateSwaggerDotGo.sh把swagger.pb连同版本目录打包成kubernetesapi/<version>/swagger.go(Makefile 目标kubernetesapi/swagger.go,见 Makefile#L57-L59); - 生成 Kustomization schema 资源:用 go-bindata 把
kustomizationapi/swagger.json打进kustomizationapi/swagger.go(见 Makefile#L47-L51); - 更新版本注册表:
./scripts/makeOpenApiInfoDotGo.sh重新生成kubernetesapi/openapiinfo.go,写入默认版本号与OpenAPIMustAsset映射。
说明:
./scripts/下的三个脚本属于 kustomize 主仓库的开发工具,在本仓库的 vendored 副本中未包含(openapiinfo.go 头部注释也标注了它由makeOpenApiInfoDotGo.sh生成、勿手改)。因此在当前仓库内可直接执行的是 Makefile 层级的命令,脚本细节以 kustomize 上游为准。
替换默认 OpenAPI schema 版本
1. 删除所有当前内置 schema
首先清空两套内置 schema(Kustomization 与 Kubernetes 的都会被移除):
make nuke
从 Makefile#L22-L28 可以看到 nuke 会先执行 clean(删除 kustomizationapi/swagger.go 与 kubernetesapi/openapiinfo.go),再删除整个 kubernetesapi/* 目录。Makefile 注释明确警告:这是破坏性操作,被删除的内容通常需要重新连上活体 API 服务器才能重建。
2. 选择要内置的新版本
编译进二进制的 schema 版本,应当在所有仍在积极支持的 Kubernetes 版本中最大化 API 可用性。README 给出示例:当 1.20、1.21、1.22 都是活跃支持版本时,1.21 是最佳选择——因为 1.21 至少引入了一个新 API 且没有移除任何 API,而 1.22 移除了一大批在 1.20/1.21 中仍受支持的长期废弃 API。
当前仓库中内嵌的版本即为这一策略的实例:openapiinfo.go 声明 DefaultOpenAPI = "v1.21.2",OpenAPIMustAsset 只注册了 "v1.21.2" 一个版本,对应的数据目录为 kubernetesapi/v1_21_2/。
3. 修改 Makefile 中的版本变量
要改变默认 schema 版本,编辑本目录下的 Makefile:
# 目标 Kubernetes API 版本
API_VERSION ?= "v1.21.2"
# kind 发布版本,采样脚本依赖它启动集群
KIND_VERSION := "v0.11.1"
API_VERSION使用?=赋值(Makefile#L9),因此也可在命令行直接覆盖:make API_VERSION="v1.22.0" all;KIND_VERSION可能需要同步更新:采样脚本靠 kind 启动与目标版本匹配的集群,kind 与 Kubernetes 的兼容关系见其官方 release notes。Makefile 中的 kind 安装目标(Makefile#L33-L41)会根据$(uname)下载对应平台二进制到$(MYGOBIN)。
生成新的 schema:一键与分步
在 openapi 目录下执行以下命令,即可完成"采样 → 生成 swagger.go → 更新 openapiinfo.go"全流程:
make all
all 目标(Makefile#L11-L15)等价于三个子目标:
make kustomizationapi/swagger.go
make kubernetesapi/swagger.go
make kubernetesapi/openapiinfo.go
三个目标各自独立:
| 目标 | 输入 | 产出 | 作用 |
|---|---|---|---|
kustomizationapi/swagger.go |
kustomizationapi/swagger.json + go-bindata |
kustomizationapi/swagger.go |
打包 Kustomization 类型 schema |
kubernetesapi/swagger.go |
kubernetesapi/swagger.pb + go-bindata |
kubernetesapi/<version>/swagger.go |
打包 Kubernetes OpenAPI schema |
kubernetesapi/openapiinfo.go |
版本目录 | kubernetesapi/openapiinfo.go |
更新内置版本注册表与默认版本 |
如果你不再需要支持旧版本的 Kubernetes OpenAPI 数据,可以手动删除对应的旧 swagger.pb 与 swagger.go 文件。删除任何旧 schema 后必须重新运行 make kubernetesapi/openapiinfo.go,否则 openapiinfo.go 会继续登记已被删除的版本,运行时 SetSchema 校验 OpenAPIMustAsset 时可能失败。
Precomputations(预计算)
为了避免昂贵的 schema 查找,一些函数基于 schema 做了预计算结果缓存。最典型的例子是 openapi.go#L94-L177 中的 precomputedIsNamespaceScoped 表:它把常见 GVK 直接映射为"是否命名空间级"(例如 apps/v1 Deployment → true、v1 Namespace → false、rbac.authorization.k8s.io/v1 ClusterRole → false),让 IsNamespaceScoped()(openapi.go#L403-L412)在命中预计算表时完全跳过 schema 解析——源码注释明确指出"Schema 创建开销很大"。
关键同步机制:单元测试会校验这些预计算结果与当前 schema 保持一致;一旦你更换了内置 schema 版本,这些测试可能失败,此时需要按照测试输出的 diff 提示更新预计算结果(例如向 precomputedIsNamespaceScoped 增删条目)。这就是 README 所说"测试保证其与 schema 同步"的落地方式。
部分重建(Partial Regeneration)
不想全量重建时,可以只重建 Kubernetes API schema:
rm kubernetesapi/swagger.go
make kubernetesapi/swagger.go
注意 Makefile 中 kubernetesapi/swagger.go 依赖 kubernetesapi/swagger.pb(Makefile#L57-L59),因此这条命令会重新采样集群并重新生成 swagger.go。
如果只想抓取 schema、不生成 Go 资源,可以:
rm kubernetesapi/swagger.pb
make kubernetesapi/swagger.pb
该目标只执行 ./scripts/fetchSchemaFromCluster.sh $(API_VERSION),产出原始的 swagger.pb,便于你检查或离线处理采样结果。README 特别提醒:生成 swagger.go 时会重新抓取 schema(依赖链决定了无法跳过采样)。
运行全部测试
schema 变更属于影响面较大的改动,完成生成后应在仓库顶层运行完整测试套件:
make prow-presubmit-check >& /tmp/k.txt; echo $?
- 退出码应为
0; - 若非零,打开
/tmp/k.txt查看具体失败项。
这条命令同时覆盖"预计算与 schema 同步"相关测试——若新版本 schema 导致 precomputedIsNamespaceScoped 或其它预计算数据过期,测试会给出建议的 diff。
运行时如何消费这些内嵌 schema
理解采样流程后,再看 openapi.go 中与之配套的运行时 API,可以形成闭环:
- 默认版本:
kubernetesOpenAPIDefaultVersion = kubernetesapi.DefaultOpenAPI(即"v1.21.2"),见 openapi.go#L577-L580; - 选择内置版本:
SetSchema(openAPIField, schema, reset)解析openAPIField["version"],并校验该版本确实存在于kubernetesapi.OpenAPIMustAsset,否则报错the specified OpenAPI version is not built in(见 openapi.go#L611-L648);若同时提供自定义 schema 与内置版本,会返回cannot use both错误; - 查询当前版本:
GetSchemaVersion()(openapi.go#L651-L663)在未设置时返回默认内置版本,设置自定义 schema 时返回"using custom schema from file provided"; - 延迟解析:
initSchema()(openapi.go#L666-L699)带锁且只解析一次,按需把kubernetesapi/…/swagger.pb(Proto格式,经 gnostic 反序列化为 OpenAPI v2 Document 后再转spec.Swagger)与kustomizationapi/swagger.json解析进globalSchema; - 按 GVK 查 schema:
SchemaForResourceType(t yaml.TypeMeta)从schemaByResourceType索引返回资源 schema(openapi.go#L193-L204);该索引在AddDefinitions中依据每个定义上的x-kubernetes-group-version-kind扩展建立(openapi.go#L318-L353); - 命名空间归属推导:除预计算表外,
findNamespaceability会扫描 API paths 中是否含namespaces/{namespace}参数来动态推导资源作用域(openapi.go#L758-L790)。
使用前提与注意事项
- 需要网络与 kind:采样流程必须能访问 Docker 环境并拉取 kind 二进制;离线或受限环境无法完成
swagger.pb的重新采样; - 仓库是只读的:本文描述的全部命令应在 kustomize 上游工作副本中执行。在本仓库(vendored 副本)中,
kubernetesapi/v1_21_2/与kustomizationapi/下的产物是静态快照,仅用于阅读与学习运行机制; - 版本选择有取舍:内置版本越高,越贴近新集群,但可能丢掉旧 API(如 README 中 1.22 移除长期废弃 API 的例子);选择时应以"被支持版本的最大交集"为原则;
- 删除旧 schema 要彻底:删掉
swagger.pb/swagger.go后务必重跑make kubernetesapi/openapiinfo.go,否则注册表与磁盘文件不一致,运行时查OpenAPIMustAsset会得到错误版本; - 预计算表是硬依赖:换版本后务必运行完整测试,用测试输出的 diff 同步
precomputedIsNamespaceScoped等预计算结果,否则会出现运行时行为与 schema 不一致的隐患。
小结
kyaml openapi 的 "Sampling New OpenAPI Data" 流程本质是一条"活体集群 → protobuf 快照 → go-bindata 资源 → 版本注册表"的构建链:make nuke 清场、修改 API_VERSION/KIND_VERSION 选版本、make all 一键产出三件套,make prow-presubmit-check 兜底验证预计算一致性。运行时侧则由 openapi.go 的 SetSchema / GetSchemaVersion / initSchema 与 openapiinfo.go 的 OpenAPIMustAsset 共同协作,把编译期的 schema 快照转化为字段校验、补丁合并与作用域判断的可靠依据。