Kubernetes v1.36 GA: How Declarative Validation Transforms API Reliability

With the release of Kubernetes v1.36, Declarative Validation for native API types has graduated to General Availability (GA). This milestone replaces thousands of lines of error‑prone, handwritten Go validation code with a unified framework of +k8s: marker tags. The result is more consistent, discoverable, and maintainable APIs—benefiting both cluster operators and ecosystem tooling. Below, we answer the most common questions about this feature, including its motivation, how validation-gen works, and what GA means for you.

What is Declarative Validation and why did it reach GA in v1.36?

Declarative Validation is a new approach to defining how Kubernetes native resource fields are checked for correctness. Instead of writing custom Go functions to enforce constraints like minimum values, mutual exclusivity, or string formats, developers now add structured +k8s: tags directly in the Go type definitions. In v1.36, this framework graduated from beta to General Availability (GA), meaning it is now stable, fully supported, and enabled by default. The GA status signals that the feature has passed rigorous testing, has a well‑defined upgrade path, and is safe for production use. For the broader community, it also unlocks the ability to publish validation rules via OpenAPI and integrate with tools like Kubebuilder, making APIs more predictable and self‑documenting.

What problems with handwritten validation led to this change?

For years, Kubernetes resource validation relied on handwritten Go code. As the API surface grew, this approach created three major issues:

• Technical debt: Approximately 18,000 lines of boilerplate validation code accumulated across the codebase. This code was hard to maintain, prone to bugs, and required intense review effort.
• Inconsistency: Without a centralized framework, validation rules were applied differently across similar resources, leading to surprising behavior for users and developers.
• Opaque APIs: Handwritten logic was invisible to clients and tooling. Developers had to read source code or encounter runtime errors to understand constraints—no machine‑readable documentation existed.

The SIG API Machinery proposed Declarative Validation as a way to eliminate these pain points by moving rules into type definitions, where they can be parsed, generated, and shared consistently.

How does the validation-gen code generator work?

At the core of Declarative Validation is a new tool called validation-gen. Much like Kubernetes generators for deep‑copy, conversion, and defaulting, validation-gen parses +k8s: marker tags attached to struct fields in types.go files. It then automatically produces the corresponding Go validation functions, which are registered with the API scheme. The generator is designed as an extensible framework: developers can add new “Validators” by describing the tags they parse and the Go logic they generate. This means that custom resource types can also benefit from the same approach. For a complete list of supported tags, see the next question.

What are the most important +k8s: tags?

The framework introduces a comprehensive suite of marker tags optimized for Go types. Here are some of the most common categories:

• Presence: +k8s:optional, +k8s:required
• Basic constraints: +k8s:minimum=0, +k8s:maximum=100, +k8s:maxLength=16, +k8s:format=k8s-short-name
• Collections: +k8s:listType=map, +k8s:listMapKey=type
• Unions: +k8s:unionDiscriminator, +k8s:union

These tags replace hundreds of lines of handwritten logic. For the full catalog, refer to the official documentation.

What does GA mean for users and ecosystem developers?

For everyday Kubernetes users, GA means the APIs you interact with become more predictable and better documented. Validation errors will be more informative, and third‑party tools can reliably introspect rules. For contributors and ecosystem developers, the benefits are even greater:

• Reduced maintenance burden: The 18,000 lines of handwritten code are replaced by generated code, lowering the risk of bugs and review fatigue.
• Consistent enforcement: All native resources now share a single validation framework, reducing inconsistencies.
• Future‑proofing: With GA, the project can now explore publishing validation rules via OpenAPI, enabling dynamic client generation and better tooling integration (e.g., Kubebuilder custom resource validation).

In short, GA marks the end of an error‑prune era and the beginning of a more automated, reliable API ecosystem.

How does this relate to OpenAPI and tooling like Kubebuilder?

One of the key motivations for Declarative Validation is enabling machine‑readable validation rules. When rules are expressed as tags in Go types, they can be extracted and published alongside the API. The Kubernetes project plans to emit validation schemas in OpenAPI format, which will allow client libraries and CLIs to validate resources before submission, without hitting the API server. This is especially valuable for ecosystem tools like Kubebuilder, which helps developers build custom controllers. With GA, Kubebuilder can automatically generate validation code for Custom Resource Definitions (CRDs) based on similar tags, reducing manual wiring. The move to declarative rules thus not only improves core Kubernetes but also extends its benefits to the entire operator ecosystem.