Kubernetes kyaml openapi 采样指南:从活体集群生成并内嵌 OpenAPI Schema

原创2026-09-08 21:15:431,709 阅读
文章标签:云原生容器编排集群管理运维微服务

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 以二进制资源的形式打包进程序,运行时直接解析。当前仓库中这套资源位于:

在 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 驱动:

  1. 启动干净的 kind 集群:Makefile 会确保存在 kind 二进制(目标 $(MYGOBIN)/kind,默认拉取 KIND_VERSION := "v0.11.1" 对应的发布版,见 Makefile#L8),并用它创建一次性集群;
  2. 从集群采样 schema:执行 ./scripts/fetchSchemaFromCluster.sh $(API_VERSION),把 /openapi/v2 的响应落盘为 kubernetesapi/swagger.pb(Makefile 目标 kubernetesapi/swagger.pb,见 Makefile#L53-L55)。注意:API_VERSION ?= "v1.21.2" 是默认值,可用变量覆盖;
  3. 生成 go-bindata 资源:./scripts/generateSwaggerDotGo.sh 把 swagger.pb 连同版本目录打包成 kubernetesapi/<version>/swagger.go(Makefile 目标 kubernetesapi/swagger.go,见 Makefile#L57-L59);
  4. 生成 Kustomization schema 资源:用 go-bindata 把 kustomizationapi/swagger.json 打进 kustomizationapi/swagger.go(见 Makefile#L47-L51);
  5. 更新版本注册表:./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)。

使用前提与注意事项

  1. 需要网络与 kind:采样流程必须能访问 Docker 环境并拉取 kind 二进制;离线或受限环境无法完成 swagger.pb 的重新采样;
  2. 仓库是只读的:本文描述的全部命令应在 kustomize 上游工作副本中执行。在本仓库(vendored 副本)中,kubernetesapi/v1_21_2/ 与 kustomizationapi/ 下的产物是静态快照,仅用于阅读与学习运行机制;
  3. 版本选择有取舍:内置版本越高,越贴近新集群,但可能丢掉旧 API(如 README 中 1.22 移除长期废弃 API 的例子);选择时应以"被支持版本的最大交集"为原则;
  4. 删除旧 schema 要彻底:删掉 swagger.pb / swagger.go 后务必重跑 make kubernetesapi/openapiinfo.go,否则注册表与磁盘文件不一致,运行时查 OpenAPIMustAsset 会得到错误版本;
  5. 预计算表是硬依赖:换版本后务必运行完整测试,用测试输出的 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 快照转化为字段校验、补丁合并与作用域判断的可靠依据。

登录后查看全文
kubernetes