Kubernetes v1.36：声明式验证正式达到 GA

在 Kubernetes v1.36 中，Kubernetes 原生类型的声明式验证已达到通用可用（GA）。

对用户而言，这意味着 API 更可靠、更可预测，并且文档更完善。通过转向声明式模型，该项目还解锁了未来通过 OpenAPI 发布验证规则、并与 Kubebuilder 等生态系统工具集成的能力。对贡献者和生态系统开发者而言，这用一个统一、可维护的框架取代了数千行手写验证代码。

本文介绍为什么这次迁移是必要的、声明式验证框架如何工作，以及此次 GA 版本带来了哪些新能力。

动机：摆脱“手写”技术债

多年来，Kubernetes 原生 API 的验证几乎完全依赖手写 Go 代码。如果某个字段需要受最小值约束，或者两个字段需要互斥，开发者就必须编写显式的 Go 函数来强制执行这些约束。

随着 Kubernetes API 覆盖面扩大，这种方法导致了若干系统性问题：

1. 技术债：项目积累了约 18,000 行样板验证代码。这些代码难以维护、容易出错，并且在代码审查中需要高度细致的检查。
2. 不一致性：由于缺少集中式框架，验证规则有时会在不同资源之间被不一致地应用。
3. 不透明的 API：手写验证逻辑难以通过程序发现或分析。这意味着客户端和工具如果不查阅源代码或在运行时遇到错误，就无法可预测地了解验证规则。

SIG API Machinery 提出的解决方案是声明式验证：直接在 types.go 文件中使用接口定义语言（IDL）标签（具体为 +k8s: 标记标签）来定义验证规则。

引入 validation-gen

声明式验证功能的核心是一个名为 validation-gen 的新代码生成器。正如 Kubernetes 使用生成器来处理深拷贝、转换和默认值设定一样，validation-gen 会解析 +k8s: 标签，并自动生成对应的 Go 验证函数。

这些生成的函数随后会与 API scheme 无缝注册。该生成器被设计为可扩展框架，允许开发者通过描述要解析的标签以及应生成的 Go 逻辑，接入新的“Validators”。

一整套全面的 +k8s: 标签

声明式验证框架引入了一整套全面的标记标签，提供了针对 Go 类型高度优化的丰富验证能力。支持标签的完整列表请查看官方文档。以下是在 Kubernetes 代码库中现在会看到的一些最常见标签目录：

• 存在性：+k8s:optional、+k8s:required
• 基本约束：+k8s:minimum=0、+k8s:maximum=100、+k8s:maxLength=16、+k8s:format=k8s-short-name
• 集合：+k8s:listType=map、+k8s:listMapKey=type
• 联合：+k8s:unionMember、+k8s:unionDiscriminator
• 不可变性：+k8s:immutable、+k8s:update=[NoSet, NoModify, NoClear]

用法示例：

type ReplicationControllerSpec struct {
    // +k8s:optional
    // +k8s:minimum=0
    Replicas *int32 `json:"replicas,omitempty"`
}

通过将这些标签直接放在字段定义上方，约束会形成自说明文档，并且任何阅读类型定义的人都能立即看到。

高级能力：“环境式递进验证”

这项工作最重要的成果之一是，验证递进现在已成为 API 的标准、环境式组成部分。过去，如果需要收紧验证，我们必须先添加手写的递进验证代码，等待一个发布周期，然后再收紧验证，以避免破坏现有对象。

借助声明式验证，这种安全机制已内置其中。如果用户更新现有对象，验证框架会将传入对象与 oldObject 进行比较。如果某个特定字段的值在语义上等同于先前状态（即用户没有更改它），新的验证规则就会被绕过。这种“环境式递进验证”意味着我们可以立即放宽或收紧验证，并尽可能减少干扰。

通过 kube-api-linter 扩展 API 审查规模

达到 GA 需要对生成代码具备绝对信心，但我们的愿景并不止于验证。声明式验证是一个综合方法的关键组成部分，旨在让 API 审查更容易、更一致，并且具有高度可扩展性。

通过将验证规则从不透明的 Go 函数迁移到结构化标记中，我们正在赋能 kube-api-linter 等工具。该 linter 现在可以静态分析 API 类型，并自动执行 API 约定，显著减少 SIG API Machinery 审查人员的手动负担，同时向贡献者提供即时反馈。

下一步是什么？

随着 Kubernetes v1.36 发布，声明式验证正式达到通用可用（GA）。作为稳定功能，相关的 DeclarativeValidation feature gate 现在默认启用。它已经成为向 Kubernetes 原生类型添加新验证规则的主要机制。

展望未来，项目承诺更广泛地采用声明式验证。这包括迁移既有 API 中剩余的传统手写验证代码，并要求所有新 API 和新字段使用该机制。这一持续转型将继续降低代码库的复杂性，同时提升整个 Kubernetes API 覆盖面的稳定性和可靠性。

除核心迁移之外，声明式验证还为更广泛的生态系统开启了令人期待的未来。由于验证规则现在以结构化标记而非不透明 Go 代码的形式定义，它们可以被 Kubernetes API 服务器发布的 OpenAPI schema 解析并反映出来。这为 kubectl、客户端库和 IDE 等工具在请求发送到集群之前执行丰富的客户端验证铺平了道路。同一声明式框架也可被 Kubebuilder 等生态系统工具使用，从而为 Custom Resource Definitions（CRDs）的作者提供更一致的开发者体验。

参与其中

向声明式验证的迁移是一项持续进行的工作。虽然框架本身已经 GA，但仍有工作需要完成，即将较旧的 API 迁移到新的声明式格式。

如果你有兴趣为 Kubernetes API Machinery 核心贡献力量，这是一个绝佳的起点。请查看 validation-gen 文档，寻找带有 sig/api-machinery 标签的问题，并加入 Kubernetes Slack 上 #sig-api-machinery 和 #sig-api-machinery-dev-tools 频道中的讨论（如需邀请，请访问 https://slack.k8s.io/）。你也可以参加 SIG API Machinery 会议，直接参与其中。

致谢

衷心感谢所有帮助推动该功能达到 GA 的人：

• 正文：Tim Hockin
• 正文：Joe Betz
• 正文：Aaron Prindle
• 正文：Lalit Chauhan
• 正文：David Eads
• 正文：Darshan Murthy
• 正文：Jordan Liggitt
• 正文：Patrick Ohly
• 正文：Maciej Szulik
• 正文：Wojciech Tyczynski
• 正文：Joel Speed
• 正文：Bryce Palmer

以及 Kubernetes 社区中一路贡献的许多其他人。

欢迎来到 Kubernetes 验证的声明式未来！

• ← 上一篇
• 下一篇 →