Kubernetes v1.36：声明式验证晋升为GA

原文链接:https://kubernetes.io/blog/2026/05/05/kubernetes-v1-36-declarative-validation-ga/

---

在 Kubernetes v1.36 中，针对 Kubernetes 原生类型的声明式验证（Declarative Validation） 已达到正式发布（GA）阶段。

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

本文将介绍为何必须进行此次迁移、声明式验证框架的工作原理，以及本次 GA 版本带来的新功能。

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

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

随着 Kubernetes API 表面的扩展，这种方法导致了一些系统性问题：

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

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

引入 validation-gen

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

这些生成的函数随后会无缝注册到 API 方案中。该生成器被设计为一个可扩展的框架，允许开发者通过描述它们解析的标签以及应生成的 Go 逻辑来插入新的“验证器（Validator）”。

全面的 +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"`
}

将这些标签直接放置在字段定义的上方，约束条件便实现了自文档化，任何阅读类型定义的人都能一目了然。

高级功能：“环境式渐进增强”（Ambient Ratcheting）

这项工作的最大成果之一是，验证渐进增强（validation ratcheting）现在已成为 API 的一个标准、环境式组成部分。过去，如果需要收紧验证，我们必须先编写手动的渐进增强代码，等待一个 release，然后再收紧验证，以避免破坏现有对象。

借助声明式验证（Declarative Validation），这一安全机制已被内置。如果用户更新了一个现有对象，验证框架会将传入对象与 oldObject 进行比较。如果某个字段的值在语义上与先前状态等效（即用户未更改它），则绕过新验证规则。这种“环境式渐进增强”意味着我们可以立即且以最小干扰的方式放松或收紧验证。

使用 kube-api-linter 扩展 API 审查

要达成通用可用性（General Availability, GA），需要对生成的代码有绝对信心，但我们的愿景远不止于验证。声明式验证是综合方法的关键部分，旨在让 API 审查更简单、更一致且高度可扩展。

通过将验证规则从不透明的 Go 函数移至结构化的标记（markers）中，我们正在赋能诸如 kube-api-linter 之类的工具。此 linter 现在可以静态分析 API 类型，并自动强制执行 API 约定，显著减轻 SIG API Machinery 审阅者的手动负担，并为贡献者提供即时反馈。

下一步是什么？

随着 Kubernetes v1.36 的发布，声明式验证（Declarative Validation）正式晋升为通用可用性（General Availability, GA）。作为一项稳定特性，关联的 DeclarativeValidation 特性门控现在默认启用。它已成为向 Kubernetes 原生类型添加新验证规则的主要机制。

展望未来，该项目致力于更广泛地采用声明式验证。这包括迁移现有 API 中遗留的手动验证代码，并要求所有新 API 和新字段都使用声明式验证。这一持续过渡将继续缩减代码库的复杂性，同时增强整个 Kubernetes API 表面的一致性和可靠性。

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

参与其中

向声明式验证的迁移是一项持续的工作。虽然框架本身已达成 GA，但在将旧 API 迁移到新的声明式格式方面仍有工作要做。

如果你对参与 Kubernetes API Machinery 的核心开发感兴趣，这里是一个绝佳的起点。查看 validation-gen 文档，寻找标记有 sig/api-machinery 的 Issue，并在 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 验证的声明式未来！