Kubernetes API 组与 YAML 校验

这次最值得我记住的，不是某个编辑器报错该怎么压下去，而是我又一次看见了一个很典型的工程误区：明明是工具链在误判，人却会本能地怀疑 manifest 里最基础的字段是不是写错了。

我这次碰到的问题很具体。一个 Kubernetes 多资源 YAML 文件里，Namespace、Secret、Pod、Service 这些标准资源的 apiVersion: v1 被编辑器标红，提示：

Matches multiple schemas when only one must validate

而同一个文件里，rbac.authorization.k8s.io/v1 这种带 group 的资源，或者 clickhouse.com/v1alpha1 这种 CRD 资源，却没有爆同样的错。表面上看，很容易让人产生一种错觉：是不是 apiVersion: v1 这种写法本身就有问题，或者至少“太模糊了”，应该找个更具体的值来规避掉这个告警。

但真正重要的地方恰恰在这里：apiVersion 不是给编辑器看的提示字符串，而是 Kubernetes API 自己的资源定位字段。

我会怎么理解 apiVersion

如果把 Kubernetes 当成一套“资源协议”，那一个对象到底是什么，最核心的定位信息其实是 GVK：

• Group
• Version
• Kind

而 YAML 里对应的就是：

• apiVersion
• kind

比如：

apiVersion: apps/v1
kind: Deployment

这句话真正表达的是：

• API group 是 apps
• version 是 v1
• kind 是 Deployment

所以 apiVersion 不是独立存在的版本号，它本质上是 group/version 的压缩表示。

什么是 core API

Kubernetes 里最容易让人误会的地方之一，就是所谓的 core API。这个词听上去像是某个叫 core 的 group，但实际上不是。

core API 更准确地说，是 Kubernetes 最基础、最早的一批资源所在的那组 API。它的特殊点是：

• group 不是 core
• 也不是 core.k8s.io
• 而是空字符串

这就导致它在 YAML 里的表现形式非常特殊。因为 group 是空的，所以 apiVersion 写出来就不是 something/v1，而是直接：

apiVersion: v1

这也是为什么下面这些资源必须写成这样：

apiVersion: v1
kind: Namespace

apiVersion: v1
kind: Service

apiVersion: v1
kind: Pod

它们不是“被我自定义成了 v1”，而是它们本来就属于 core group 的 v1 版本。

为什么 apiVersion: v1 不能改成别的

我觉得这里最容易出错的思维方式，是把 apiVersion 当成某种“可以为了工具兼容性调一调的配置项”。它不是。

以 Service 为例，如果它在当前 Kubernetes 里定义的就是：

• group = ""
• version = v1
• kind = Service

那 YAML 里就只能写：

apiVersion: v1
kind: Service

你不能因为编辑器报错，就把它改成：

apiVersion: core/v1

或者：

apiVersion: apps/v1

因为那已经不是“同一个资源的另一种写法”了，而是彻底换成了一个 Kubernetes 根本不认识的 GVK 组合。编辑器也许不报这个特定错误了，但 kubectl apply 反而会失败。

所以我会把这件事记成一句很实用的话：不要为了让 schema 安静下来，去篡改真正的 API 身份。

为什么只有 v1 更容易报这种 schema 错

这次现象最迷惑人的地方，是并不是所有 apiVersion 都会报错。rbac.authorization.k8s.io/v1、clickhouse.com/v1alpha1 往往都很安静，偏偏 v1 最容易被标红。

我对这个现象的理解是：v1 在 schema 匹配层面太“泛”了。

因为 apiVersion: v1 对应的是整个 core API，而 core API 下面挂着很多资源：

• Pod
• Service
• Secret
• ConfigMap
• Namespace
• ServiceAccount
• PersistentVolumeClaim
• 还有别的

也就是说，编辑器如果只先看到一行：

apiVersion: v1

它会天然面临很多候选 schema。相反，像：

apiVersion: rbac.authorization.k8s.io/v1

范围就已经收窄很多了；再加上 kind，通常很快就能收敛到那几个 RBAC 资源之一。

所以不是 v1 更“不合法”，而是 v1 的候选资源集合更大，更容易把聚合 schema 的 oneOf / anyOf 选择机制逼出歧义。

为什么 yaml-language-server 会在多资源文件里误报

这次实际触发误报的配置，是把 yaml-language-server 指向了一套 Kubernetes 通用 schema。问题不在 Kubernetes 本身，而在于这种工具链很容易把“一个文件里混着很多不同资源”的情况处理得不够稳定。

对我来说，最合理的解释是这样的：

• yaml-language-server 绑定了一套 Kubernetes 聚合 schema；
• 这套 schema 更擅长处理“一个文件只描述一种资源”；
• 当同一个 YAML 文件里连续放了 Namespace、Secret、Pod、Service 乃至 CRD 资源时，schema 选择器会反复在多个候选之间试探；
• 对 apiVersion: v1 这种本来就候选很多的字段，最容易提前落入“匹配了多个 schema”的假阳性。

换句话说，这不是 Kubernetes 在说你的 manifest 有问题，而是编辑器的 schema 推断在多文档混合文件里失去了足够强的上下文。

为什么把配置从 k8s/**/*.yaml 改成 *.yaml 后，错误反而消失了

这一步最反直觉，也最值得记一笔。

我不会轻易把这种现象解读成“*.yaml 比 k8s/**/*.yaml 更正确”。我更倾向的判断是：修改 glob 之后，当前文件匹配到了另一条 schema 关联路径。

更具体地说，最可能有两种情况：

• 原来的 k8s/**/*.yaml 根本没有命中当前文件，所以它实际上落回了默认的 Kubernetes 聚合 schema；
• 改成 *.yaml 后，当前文件终于被显式 schema 接管，自动推断路径不再参与，于是假阳性消失了。

这件事对我最大的提醒是：编辑器“报了”或者“没报”，并不一定说明 manifest 语义发生了变化，更常见的是 schema 绑定路径变了。

我会怎么处理这类问题

我现在会优先按下面这个顺序处理，而不是第一时间去改 manifest 字段：

1. 先确认 kubectl apply 和实际 CRD 版本是否正常；
2. 再确认当前文件到底匹配到了哪条 schema；
3. 如果是多资源混合文件，就优先怀疑 schema 工具链，而不是 apiVersion；
4. 能拆文件就拆文件；
5. 不能拆的时候，就避免把过于激进的聚合 schema 绑定到所有 YAML 文件上。

对我来说，这种判断方式比死记“某个编辑器怎么配”更重要。因为真正长期有用的知识，不是某条配置项，而是先区分协议层问题和工具层问题。

对我的提醒

这次小插曲让我更愿意把 Kubernetes manifest 看成“声明式 API 请求”，而不是“某种给编辑器看的配置文本”。只要把这个视角守住，很多判断就会简单很多：

• apiVersion 写什么，取决于 Kubernetes API；
• 编辑器报不报错，取决于 schema 工具链；
• 两者经常相关，但绝不能混为一谈。

也正因为如此，下一次如果我再看到 apiVersion: v1 被 schema 标红，我第一反应不会再是“是不是该换个版本号”，而会先问自己：我现在修的是集群协议，还是编辑器幻觉？

---

相关页面：kubernetes · kubernetes-autoscaling · clickhouse-production-migration · clickhouse-single-node-to-cluster-migration · clickhouse-deployment-topologies