10 Things You Need to Know About Kubernetes v1.36's Declarative Validation (Now GA)

Kubernetes v1.36 has arrived, and with it comes a significant upgrade for API reliability: Declarative Validation for native types has officially graduated to General Availability (GA). This shift from handwritten validation code to a declarative, tag-based framework promises more predictable APIs, easier maintenance, and a brighter future for ecosystem integration. Whether you're a cluster operator, application developer, or contributor, these ten points will help you understand what this change means and how it improves the Kubernetes experience.

1. What Is Declarative Validation?

Declarative Validation replaces the old approach of writing explicit Go functions to enforce rules on API fields. Instead, developers annotate type definitions with +k8s: marker tags that describe constraints—like +k8s:minimum=0 or +k8s:maxLength=64. A code generator then automatically produces the corresponding validation logic. This makes the validation rules visible directly in the type definitions, improving clarity and reducing human error. For end users, it means APIs behave more consistently, and error messages become more informative because the rules are no longer buried in custom code.

2. Why Handwritten Validation Was a Problem

Before v1.36, Kubernetes validation relied on roughly 18,000 lines of handwritten Go code. This approach created three major issues. First, technical debt made maintenance a nightmare—every new field required a new function, and reviewing those changes was time-consuming. Second, inconsistency crept in because different developers wrote validation with varying styles and levels of rigor. Third, opaque APIs meant that external tools and clients couldn't discover validation rules without digging into source code or waiting for runtime errors. Declarative Validation solves all three by centralizing rule definitions in the type files.

3. The Role of validation-gen

At the heart of this feature is a new code generator called validation-gen. Much like deepcopy-gen or defaulter-gen, validation-gen reads the +k8s: tags in Go type definitions and automatically generates the required validation functions. These functions are then registered with the API scheme seamlessly. The generator is designed as an extensible framework: developers can add custom validators by defining new tags and the Go logic they trigger. This modularity ensures that as Kubernetes grows, validation remains maintainable and consistent across all resource types.

4. The +k8s: Tag System

The declarative validation framework introduces a rich set of +k8s: marker tags that cover common validation patterns. These tags are placed directly in the types.go files alongside the field definitions. The full list is documented in the Kubernetes source, but they fall into categories like presence, basic constraints, collections, and unions. By using tags, developers can express validation intent without writing any procedural code, making the rules self-documenting and easier to audit.

5. Basic Constraint Tags

Among the most frequently used tags are basic constraints. Examples include +k8s:minimum and +k8s:maximum for numeric ranges, +k8s:maxLength for string lengths, and +k8s:format for expected formats (like k8s-short-name). These tags replace what used to be explicit bounds-checking functions. They also ensure that validation rules are applied uniformly across all resources, reducing the risk of edge cases where one resource enforces a limit but another doesn't. For API consumers, this means that constraint violations return clear, consistent error messages.

6. Collection and Union Tags

More complex validation scenarios are handled by tags for collections and unions. For example, +k8s:listType=map specifies that a list should behave as a map, with +k8s:listMapKey defining the key field. Union fields—those that are mutually exclusive—are tagged with +k8s:union and related +k8s:unionDiscriminator. These tags replace intricate handwritten logic that checked field exclusivity or enforced list uniqueness. The gain in readability is substantial: what once required pages of code now fits on a single line.

7. GA Status: Stability and Backward Compatibility

With graduation to GA, Declarative Validation is now stable and enabled by default for all native types. The feature has been thoroughly vetted through alpha and beta stages, ensuring that generated validation functions behave identically to the handwritten ones they replace. Backward compatibility is a top priority—existing workloads and custom resources are unaffected. For API version upgrades, the consistency of validation rules across releases becomes more predictable, a major win for operators managing multi-version clusters.

8. Benefits for API Consumers

Developers who call Kubernetes APIs directly or through libraries will notice more accurate error messages when they submit invalid objects. Because validation rules are now centralized and generated, the API server can produce feedback that directly references the tag constraints. Moreover, the framework unlocks the ability to publish validation rules via OpenAPI in future releases, making it possible for client tools to validate configurations before sending them to the cluster. This reduces the iteration cycle and catches mistakes earlier in the deployment pipeline.

9. Impact on Ecosystem Tools

Ecosystem projects like Kubebuilder and custom controller frameworks are poised to benefit significantly. With validation rules declared in types via tags, these tools can integrate the generated functions directly, eliminating the need for manual validation wiring. Validation-gen is designed to be reusable, so third-party projects can adopt the same generator pattern. This creates a more unified ecosystem where validation behavior is consistent, whether you're using native Kubernetes resources or custom resources built with operator-sdk.

10. Future Possibilities

The GA release is only the beginning. The declarative model lays the groundwork for publishing validation rules as OpenAPI extensions, enabling richer client-side validation. It also opens the door for tooling that can automatically generate documentation and validation checks from the tags. The extensible validation-gen framework encourages community contributions to add new tag types. As Kubernetes continues to evolve, this unified validation approach will reduce friction for contributors and improve the overall reliability of the API.

In summary, the graduation of Declarative Validation in Kubernetes v1.36 marks a turning point for API reliability and developer experience. By moving from thousands of lines of handwritten code to a tag-based, generated system, the project reduces technical debt, improves consistency, and opens up new integration possibilities. Whether you're a veteran contributor or a newcomer, this feature makes Kubernetes validation smarter, more accessible, and future-ready.