Kubernetes v1.36 Delivers Declarative Validation: What It Means and How It Works

In Kubernetes v1.36, the Declarative Validation feature for native API types has reached General Availability (GA). This milestone replaces decades of handwritten validation code with a unified, maintainable framework based on marker tags and a new code generator called validation-gen. For users, it means more reliable, predictable, and better-documented APIs. For contributors and ecosystem developers, it eliminates roughly 18,000 lines of boilerplate code, reduces inconsistencies, and paves the way for future tooling integration. Below, we answer key questions about this transformative change.

What is Declarative Validation and why did Kubernetes need it?

Declarative Validation is a framework that allows Kubernetes developers to define validation rules directly in type definitions using +k8s: marker tags. Previously, validation was done entirely in handwritten Go code—a practice that led to significant technical debt as the API surface grew. The project had accumulated about 18,000 lines of such code, which was error-prone, difficult to maintain, and often inconsistent across resources. Additionally, because the rules were buried in code, they weren't easily discoverable by clients or tooling. The move to a declarative model centralizes validation logic, makes it transparent, and sets the stage for future enhancements like automatic OpenAPI publication and ecosystem tool integration.

How does validation-gen simplify API validation?

At the core of this feature is a new code generator called validation-gen. Similar to how Kubernetes uses generators for deep copies, conversions, and defaulting, validation-gen parses +k8s: marker tags from the types.go files and automatically produces the corresponding Go validation functions. These generated functions are then registered with the API scheme seamlessly. The generator is built as an extensible framework—developers can plug in new “Validators” by describing the tags they parse and the Go logic they should generate. This not only eliminates thousands of lines of manual code but also ensures consistency and reduces the chance of human error during code reviews.

What are the main benefits for developers and cluster operators?

For developers working on Kubernetes itself, the most immediate gain is maintainability. They no longer need to write or review lengthy validation functions—instead, they add a few marker tags to struct fields. This also reduces the risk of inconsistencies: if a rule appears in one resource, it can be reused across others. For cluster operators and API consumers, the benefits are more reliable and predictable APIs. Validation rules are now explicitly documented via tags, making it easier to understand constraints without digging into source code. Additionally, the GA status guarantees stability: these tags and generated logic are now part of the official Kubernetes API machinery, reducing the chance of breaking changes in future releases.

Can you list some of the key +k8s marker tags and their uses?

The declarative validation framework introduces a comprehensive suite of +k8s: marker tags optimized for Go types. Here are some common examples:

• Presence: +k8s:optional and +k8s:required mark fields as optional or mandatory.
• Basic Constraints: +k8s:minimum=0, +k8s:maximum=100, +k8s:maxLength=16, and +k8s:format=k8s-short-name enforce numeric ranges, string lengths, and specific formats.
• Collections: +k8s:listType=map and +k8s:listMapKey=type define how lists are structured and keyed.
• Unions: +k8s:union and related tags manage mutually exclusive fields. For a full list, see the official documentation.

What future capabilities does this GA release unlock?

By moving to a declarative model, Kubernetes now possesses a standardized, machine-readable representation of validation rules. This unlocks several exciting possibilities. First, the project can automatically publish validation rules via OpenAPI, making them discoverable by any client that supports the OpenAPI spec. Second, ecosystem tools like Kubebuilder can consume these rules to provide richer code generation, scaffolding, and IDE support. Third, it simplifies the creation of custom validators and admission webhooks by providing a consistent tag-based language. Ultimately, this GA milestone is a foundational step toward a more automated and tool-friendly Kubernetes API ecosystem, reducing the gap between what developers write and what tools can understand.

How does this affect contributors and code maintainability?

For contributors and ecosystem developers, the biggest impact is the dramatic reduction in boilerplate code. Instead of writing and maintaining thousands of lines of Go validation functions, they can now express rules with a few declarative tags. The generated code is automatically registered and consistent across resources, eliminating many subtle bugs. Additionally, the unified framework simplifies code reviews—reviewers can focus on the tags and their correctness rather than parsing complex function logic. This also makes the codebase easier to onboard new contributors, as the validation intent is clearer. In summary, the GA release of Declarative Validation transforms a historically painful part of Kubernetes development into a clean, maintainable, and extensible system.