Kubernetes v1.36 marks a significant milestone with the General Availability (GA) of Declarative Validation for native types. This feature replaces thousands of lines of handwritten validation code with a unified, maintainable framework. For users, it means more reliable, predictable, and better-documented APIs. For contributors, it opens the door to publishing validation rules via OpenAPI and integrating with tools like Kubebuilder. In this article, we break down the five most important things you need to know about this release.
1. Why Handwritten Validation Became a Burden
For years, validating Kubernetes native APIs relied on handwritten Go functions. If a field required a minimum value or two fields needed to be mutually exclusive, developers had to write explicit logic. As the API surface expanded, this approach created roughly 18,000 lines of boilerplate validation code—hard to maintain and error-prone. Code reviews became intense and inconsistencies cropped up across resources. Moreover, the validation logic was opaque: clients and tooling couldn’t discover rules without digging into source code or encountering runtime errors. This technical debt motivated SIG API Machinery to seek a more scalable solution.
2. How Declarative Validation Transforms API Reliability
Declarative Validation moves from imperative Go code to a declarative model using +k8s: marker tags within types.go files. This shift makes validation rules explicit, consistent, and discoverable. Now, instead of hunting through functions, contributors simply annotate fields with tags like +k8s:minimum=0. The resulting validation is automatically generated, reducing human error and ensuring uniform behavior across all native types. For end users, this means more reliable APIs: constraints are honored predictably, and the API schema becomes self-documenting.
3. Meet validation-gen: The New Code Generator
At the heart of this feature is validation-gen, a code generator that parses +k8s: tags and produces the corresponding Go validation functions. Just as Kubernetes already uses generators for deep copies and conversions, validation-gen automatically registers these functions with the API scheme. The generator is extensible: developers can plug in new Validators by describing the tags they parse and the Go logic they produce. This reduces maintenance overhead and allows the community to add custom validation rules without rewriting boilerplate.
4. A Deep Dive into the +k8s: Marker Tags
The declarative validation framework introduces a comprehensive set of marker tags. These include presence indicators like +k8s:optional and +k8s:required, basic constraints such as +k8s:minimum=0, +k8s:maximum=100, +k8s:maxLength=16, and +k8s:format=k8s-short-name. For collections, tags like +k8s:listType=map and +k8s:listMapKey=type define how lists behave. Union fields are also handled. These tags are optimized for Go types and replace hundreds of handwritten checks, making the codebase cleaner and more maintainable.
5. Benefits for Users and Ecosystem Developers
With this GA release, both end users and ecosystem developers gain tangible advantages. Users experience more reliable and predictable APIs—validation rules are enforced consistently, and the API documentation becomes richer because rules are declared inline. For ecosystem developers, especially those using tools like Kubebuilder or building custom controllers, the new framework unlocks the ability to publish validation rules via OpenAPI in the future. This means tooling can automatically discover and enforce constraints without guesswork. Ultimately, this reduces technical debt and aligns with Kubernetes’ goal of making APIs self-describing.
In summary, Kubernetes v1.36’s Declarative Validation GA is a game-changer for API reliability and developer productivity. By moving from handwritten code to a declarative, tag-based approach, the project eliminates thousands of lines of error-prone logic and paves the way for deeper ecosystem integration. Whether you’re a contributor writing new API types or a user consuming Kubernetes APIs, this release makes validation more transparent and trustworthy. To explore the full list of supported tags, check the official documentation and start annotating your types today.