Kubernetes 一致性测试清单守护机制：test/conformance 目录、golden 文件与更新工作流全解析

导读

本指南聚焦 Kubernetes 主仓库中的 test/conformance 目录，深入讲解"一致性（Conformance）测试清单"如何被当作一份受版本控制的 golden 文件来守护、审查与更新。你将掌握：该目录的回归测试角色、conformance.yaml 清单的生成与校验链路（gen-specsummaries.sh → walk.go → YAML）、测试用例如何通过注释与 [Conformance] 标记被收录，以及贡献者在增删一致性测试时必须遵循的完整提交流程。读完即可独立处理"改了测试却导致一致性清单回归失败"的典型问题。

目录定位：这是一道"守护清单"的回归测试

Kubernetes 主仓库的 test/conformance/README.md 开宗明义地说明：该目录包含一个用于控制全部一致性测试清单的回归测试（regression test）。

也就是说，test/conformance 目录本身并不是 e2e 一致性测试的执行入口，而是一道"元测试"——它守卫的是"哪些用例被官方认可为 Kubernetes Conformance 用例"这一清单。其核心约束可以概括为三条：

1. 清单有唯一事实来源：所有一致性测试的权威列表固化在一个 golden 文件 test/conformance/testdata/conformance.yaml 中（当前仓库状态下共收录约 462 条用例，横跨 sig-api-machinery、sig-apps、sig-network、sig-node、sig-storage 等多个 SIG 的测试）。
2. 改动即报警：任何对一致性测试集合的增删，都会使回归检查失败，从而强制开发者去更新 golden 清单。
3. 变更需架构委员会审查：golden 文件的所有改动必须交由 sig-architecture 评审后方可合入。

一致性测试的价值在于其是"发行版/云厂商平台是否符合 Kubernetes API 行为"的判定依据，因此其清单的增删必须谨慎且透明——这正是本目录存在的原因。

golden 清单的数据模型：每个条目记录了什么

守护的对象 test/conformance/testdata/conformance.yaml 是一份结构化的 YAML 列表，生成逻辑由 test/conformance/walk.go 中定义的 ConformanceData 结构体驱动。每个条目包含以下字段：

字段	YAML 键	含义	取值示例
TestName	testname	从测试前注释 Testname: 中提取的人类可读名称	Priority and Fairness FlowSchema API
CodeName	codename	Ginkgo 描述串拼接出的完整代码级名称，含 [Conformance] 标记	[sig-api-machinery] API priority and fairness should support FlowSchema API operations [Conformance]
Description	description	从注释 Description: 提取的行为契约描述，使用 RFC 2119 关键词	...The flowschema resource must support create, get, list, watch...
Release	release	该用例加入/修改一致性套件的版本	v1.16、v1.29
File	file	定义该测试的源码文件路径（故意不保存行号，避免无意义变更）	test/e2e/apimachinery/webhook.go
URL	（不输出）	代码所在源码行链接，YAML 序列化时通过 yaml:"-" 排除，避免暴露行号	—

从 walk.go 可见，设计者刻意把行号从 YAML 中剥离，其注释写明这是"为了避免无意义的变化"——清单只跟踪测试的"存在性"与"归属文件"，而非行级波动。

真实条目示例（摘自当前仓库的 golden 文件，对应 FlowSchema API 用例）：

- testname: Priority and Fairness FlowSchema API
  codename: '[sig-api-machinery] API priority and fairness should support FlowSchema
    API operations [Conformance]'
  description: ' The flowcontrol.apiserver.k8s.io API group MUST exist in the /apis
    discovery document. The flowcontrol.apiserver.k8s.io/v1 API group/version MUST
    exist in the /apis/flowcontrol.apiserver.k8s.io discovery document...'
  release: v1.29
  file: test/e2e/apimachinery/flowcontrol.go

注意 codename 携带 [Conformance] 标签、description 大量使用 MUST/SHOULD 等 RFC 2119 关键词——这两点构成了用例"够格进入清单"的语义基础。

用例如何获得一致性身份：[Conformance] 标记与规范注释

并非所有 e2e 测试都能进入清单。一个用例要成为 Conformance 用例，需要在代码与注释两个层面满足约定：

1. 使用专用包装函数注册

框架在 test/e2e/framework/ginkgowrapper.go 提供 ConformanceIt，它是 ginkgo.It 的包装，会自动追加 [Conformance] 标签并使静态分析更简单：

// ConformanceIt is wrapper function for ginkgo It.  Adds "[Conformance]" tag and makes static analysis easier.
func ConformanceIt(args ...interface{}) bool {
	args = append(args, ginkgo.Offset(1), WithConformance())
	return It(args...)
}

而 walk.go 判断用例是否属于一致性集合的逻辑同样简单直接：检查其完整名称是否包含子串 [Conformance]。

2. 在调用前编写结构化注释

在 test/conformance/cf_header.md 中给出了标准范例——注释必须包含 Release:、Testname:、Description: 三要素，且紧邻 ConformanceIt 调用：

/*
  Release: v1.13
  Testname: Kubelet, log output, default
  Description: By default the stdout and stderr from the process being executed in a pod MUST be sent to the pod's logs.
*/
framework.ConformanceIt("should print the output to logs [NodeConformance]", func(ctx context.Context) {

walk.go 的 commentToConformanceData 函数（walk.go）通过正则按 Testname: / Release: / Description: 行首前缀切分注释：前两者只取单行，Description 之后的所有普通行会被拼接为多行描述。若注释里找不到 Testname:，则整个解析结果返回 nil，该用例会被跳过并打印日志。

3. 注释与调用位置必须靠近

为保证注释确实属于该用例，解析器限定注释组结尾与函数位置的距离不得超过 5 行（conformanceCommentsLineWindow = 5，见 walk.go），超出即视为不相关注释。此外 validateTestName（walk.go）会拒绝名称中带 [Alpha]、[Feature:...]、[Flaky] 等"不够格"标签的用例进入清单。

4. 禁止供应商相关的跳过逻辑

一致性用例必须对所有平台生效。仓库配套工具 hack/conformance/check_conformance_test_requirements.go 通过正则扫描每个 ConformanceIt(...func() { 到 }) 之间的代码，若发现 e2eskipper.Skip*( 调用（如按 provider 跳过），即报错退出。其注释与代码明确写道：一致性测试不得调用任何 e2eskipper.Skip*()，否则意味着该行为并非所有平台都具备、不应进入一致性清单。

守护机制如何工作：两处"一旦不一致就失败"的检查

回归测试形态：conformance_test.sh

test/conformance/conformance_test.sh 是清单守护的直接执行者：

if diff -u test/conformance/testdata/conformance.yaml test/conformance/conformance.yaml; then
  echo PASS
  exit 0
fi
echo 'See instructions in test/conformance/README.md'
exit 1

它会将重新生成的清单与仓库中已检入的 golden 文件做逐字节 diff：一旦不一致（即有人增删了 [Conformance] 用例却未同步 golden），检查即失败，并提示"参见 test/conformance/README.md 中的说明"。这正对应 README 中那句"如果新增或移除一致性测试，本测试会失败"。

CI 校验形态：hack/verify-conformance-yaml.sh

在 CI 与 hack/verify-all.sh 体系内，由 hack/verify-conformance-yaml.sh 承担同样的职责：先调用 test/conformance/gen-conformance-yaml.sh 生成新清单，再与检入的 conformance.yaml 做 diff -u，不一致即失败并同样提示阅读本 README。因此，"更新清单"是改动一致性测试后无法绕过的环节。

从源码到 golden 文件的完整生成链路

理解整条流水线有助于判断何时该重跑、以及每步产物是什么：

1. gen-specsummaries.sh：编译 github.com/onsi/ginkgo/v2/ginkgo 与 test/e2e/e2e.test（设置 DBG=1 以便文件名为仓库相对路径），随后执行 dry-run 抽取：

   ./_output/bin/ginkgo --dry-run=true --focus='[Conformance]' ./_output/bin/e2e.test -- --spec-dump "${KUBE_ROOT}/_output/specsummaries.json" > /dev/null
   

   产物是 _output/specsummaries.json——所有名称含 [Conformance] 的用例的 Ginkgo SpecReport 序列化结果。
2. spec-to-yaml.sh：基于 Go 环境运行 walk.go：

   go run ./test/conformance/walk.go --source="${KUBE_ROOT}" ./_output/specsummaries.json > ./_output/conformance.yaml
   

   此时 walk.go 借助 LeafNodeLocation 定位每个 spec 对应的 file:line，打开源文件并用 go/parser + AST 注释映射解析其前置注释，抽取 Testname/Release/Description，最终按 CodeName 排序后整体 yaml.Marshal 输出。
3. gen-conformance-yaml.sh：将上面两步串联，产出 _output/conformance.yaml。
4. update-conformance-yaml.sh（README 指定的入口）：执行第 3 步后把产物复制回 golden 位置：

   test/conformance/gen-conformance-yaml.sh
   cp _output/conformance.yaml test/conformance/testdata/conformance.yaml
   

何时需要重跑：任何导致 [Conformance] 用例集合或其在 test/e2e 中定义文件变化的改动——新增 ConformanceIt、删除用例、改写注释中的 Testname/Release/Description、把用例跨文件移动等——都会让重新生成的 YAML 与 golden 文件产生差异。

按 README 操作：更新 golden 清单的正式流程

test/conformance/README.md 给出的维护动作非常明确，这里展开成完整步骤：

1. 本地重生成清单：在仓库根目录执行更新脚本：

   hack/update-conformance-yaml.sh
   

   该脚本会自动依次完成 spec 抽取与 YAML 生成，并将最新产物覆盖写回 test/conformance/testdata/conformance.yaml。

2. 确认改动范围合理：git diff 检查 golden 文件的变化是否恰好对应你新增/删除/修改注释的那些 [Conformance] 用例条目，避免夹带意外变更（例如无关的行级噪音——得益于 ConformanceData 不记录行号的设计，这类噪音通常不会出现）。

3. 将变更后的文件加入 PR：README 原话为"Add the changed file to your PR"，即把更新后的 test/conformance/testdata/conformance.yaml 连同测试源码改动一起提交。

4. 交由 sig-architecture 评审：README 明确要求"Changes to that file require review by sig-architecture"。由于一致性清单直接决定第三方发行版是否"合规"，golden 文件的任何变动都需要架构委员会把关后方可合入。

与清单伴生的边界数据：不可测端点与待晋升用例

除主清单外，testdata 目录还维护了两份配套边界清单，它们在一致性相关工具链中扮演辅助角色（注意 embed.go 通过 //go:embed 将 conformance.yaml 与 ineligible_endpoints.yaml 一并打入二进制）：

• ineligible_endpoints.yaml：列出"不可参与一致性测试"的 API 端点及原因。当前仓库中约 300 余条，典型如 connectCoreV1*NodeProxy* 系列——理由是"无法被测试，且可能很快被弃用"。这类端点即使存在 API 操作也无法进入一致性断言。
• pending_eligible_endpoints.yaml：记录"待评估/待晋升"的端点，当前仓库状态下列出 getLifecycleAPIGroup 等条目，代表尚在跟进中的候选。

一致性套件文档与执行的关系（延伸）

清单的用途不限于回归守护，它还支撑一致性套件文档的生成：gen-conformance-docs.sh 与 spec-to-docs.sh 会基于同样的 spec 摘要输出 Markdown 文档，模板头部即 cf_header.md（其中含版本占位符 {{.Version}}，由 walk.go 的 --docs 模式与 --version 标志填充）。

顺带澄清一个常见混淆：本目录守卫的是"清单"，真正在集群上执行这些一致性用例的是 test/conformance/image 下的 e2e 运行编排（如 conformance-e2e.sh），两者配合形成"清单定义 + 镜像执行"的完整一致性体系。而判断一个用例是否属于清单的 [Conformance] 标签语义，在 cf_header.md 中有权威解释：它是"e2e 测试的子集"，每个用例必须用 RFC 2119 关键词（MUST/MUST NOT/SHOULD/MAY 等）在注释里讲清平台需要遵守的行为契约，以区分"验证平台的代码"与"仅用于搭建/清理环境的基建代码"。

小结：日常维护速查

场景	正确动作
新增/删除一个 [Conformance] 用例，或修改其前导注释	重跑 hack/update-conformance-yaml.sh，把更新后的 conformance.yaml 加入 PR
conformance_test.sh 或 hack/verify-conformance-yaml.sh 报 diff 失败	说明 golden 与最新清单不一致，按上一步重新生成即可，错误信息会直接提示"See instructions in test/conformance/README.md"
为用例编写注释	必须提供 Release:、Testname:、Description: 三要素，Description 尽量使用 RFC 2119 关键词，注释结尾距 ConformanceIt 调用不超过 5 行
用例名/描述含 [Alpha]、[Feature:...]、[Flaky]	会被 walk.go 的校验拒绝，先移除这些标签再谈晋升
用例内有按平台跳过逻辑	先删除 e2eskipper.Skip* 调用，否则 check_conformance_test_requirements.go 检查不通过
修改了 conformance.yaml	提交时备注并提请 sig-architecture 评审

这套"golden 文件 + 自动重生成 + 强审查"的设计，保证了 Kubernetes 一致性测试清单的每一次变化都有迹可循、有据可查，也让发行版与云厂商能够依赖一份经过架构委员会把关的稳定契约。