Kubernetes v1.36: Declarative Validation Goes GA – Your Questions Answered

Kubernetes v1.36 marks a major milestone with the General Availability (GA) of Declarative Validation for native types. This shift replaces thousands of lines of handwritten validation code with a maintainable, tag-based framework. In this Q&A, we address the motivations, the inner workings of the new validation generator, and what this means for users and ecosystem developers.

1. What exactly has been graduated to GA in Kubernetes v1.36?

The Declarative Validation framework for Kubernetes native API types has reached General Availability. This means validation rules are now defined using +k8s: marker tags directly in Go type definitions, rather than handwritten Go functions. The framework includes a new code generator called validation-gen that automatically produces the corresponding validation logic. For users, this results in more consistent, predictable APIs with better documentation; for contributors, it eliminates roughly 18,000 lines of error-prone boilerplate code.

Kubernetes v1.36: Declarative Validation Goes GA – Your Questions Answered

2. Why was the shift from handwritten validation to a declarative model necessary?

Handwritten validation led to significant technical debt—about 18,000 lines of code that were hard to maintain and review. It also caused inconsistencies across different resources because there was no centralized framework. Moreover, the validation logic was opaque: clients and tools could not discover rules programmatically without reading source code or hitting runtime errors. Declarative validation solves these issues by centralizing rule definitions in a single, parseable format, making the API surface easier to understand and extend.

3. How does the new validation-gen generator work?

validation-gen is a code generator that parses +k8s: marker tags placed on Go struct fields in types.go files. It then automatically generates the corresponding Go validation functions and registers them with the API scheme. The generator is designed as an extensible framework—developers can add custom validators by describing the tags they parse and the Go logic they should emit. This approach mirrors how Kubernetes already uses generators for deep copies, conversions, and defaulting, ensuring a unified codebase.

4. What are some of the key +k8s marker tags introduced?

The framework provides a comprehensive suite of tags optimized for Go types. Common examples include:

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:union

For a full list, consult the official documentation.

5. How does Declarative Validation benefit everyday Kubernetes users?

Users gain more reliable and predictable APIs. Because validation rules are defined declaratively, the system can provide clearer error messages and ensure consistent enforcement across all resource types. Additionally, the framework unlocks future capabilities like publishing validation rules via OpenAPI, which will allow clients to understand constraints before making requests. This reduces trial-and-error and makes tooling (e.g., IDE plugins or CI checks) smarter.

6. What advantages does this bring to contributors and ecosystem tool developers?

Contributors no longer need to write and maintain thousands of lines of handwritten validation code—the generator produces them automatically. This reduces review burden and the potential for human error. Ecosystem tooling, such as Kubebuilder, can integrate directly with the declarative tags to generate CRD validation schemas. In the future, the same tags could be used to emit OpenAPI descriptions, making validation rules discoverable by a wide range of clients and automation.

Tags: