Kubernetes v1.36 marks a significant milestone for the project's API reliability and developer experience. The Declarative Validation feature for native Kubernetes types has officially graduated to General Availability (GA). This means cluster operators, application developers, and ecosystem tool builders can now rely on a more consistent, predictable, and well-documented API validation system. By shifting from handwritten Go code to a declarative model using marker tags and a code generator, Kubernetes eliminates thousands of lines of boilerplate maintenance, paving the way for future integrations like OpenAPI publishing and smoother integration with tools like Kubebuilder. In this article, we explore the motivation behind this shift, how the new framework works, and what capabilities the GA release unlocks.
Why Declarative Validation Mattered
For years, Kubernetes native API validation relied on manually written Go functions. Each field constraint—whether a minimum value, a required field, or a mutual exclusivity rule—required a dedicated piece of imperative code. As the API surface grew, this approach accumulated roughly 18,000 lines of validation logic, creating what the SIG API Machinery team called a technical debt bottleneck.
The Burden of Handwritten Code
Handwritten validation was not just voluminous; it was brittle. Every new API version or field change meant updating multiple functions, and code reviews became intense exercises in checking consistency. The risk of introducing subtle bugs—like missing a condition or applying a rule only to certain resources—increased over time. This maintenance overhead slowed down feature development and made the codebase harder to contribute to.
Inconsistencies and Opaque APIs
Without a centralized framework, validation rules were often applied inconsistently across similar resources. For example, a maxLength constraint on a string field might exist for one custom resource but not another, purely because the developer wrote different code each time. Worse, these rules were opaque to consumers: clients, command-line tools, and IDE plugins could not programmatically discover what constraints an API field had without reading the source code or encountering a runtime error. This lack of transparency hindered tooling and automation, especially in CI/CD pipelines and admission controllers.
How Declarative Validation Works
The solution proposed by SIG API Machinery was to define validation rules directly in the type definition files (types.go) using +k8s: marker tags. These tags are parsed by a new code generator called validation-gen, which automatically produces the corresponding Go validation functions and registers them with the API scheme. The result: a unified, maintainable validation framework that replaces thousands of lines of handwritten code.
Introducing validation-gen
validation-gen joins the family of Kubernetes code generators like deepcopy-gen and defaulter-gen. It reads the marker tags and outputs Go validation logic that is seamlessly integrated. The generator is designed as an extensible framework: developers can plug in new validators by describing the tags they parse and the Go logic they should produce. This makes it easy for anyone working on Kubernetes core or external projects to add custom validation rules without writing boilerplate.
Marker Tags: A Unified Validation Vocabulary
The declarative validation framework introduces a comprehensive set of marker tags optimized for Go types. These tags cover common validation patterns:
- 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:unionand related tags for mutually exclusive fields
For a full list, refer to the official Kubernetes documentation. These tags make validation rules both human-readable and machine-parsable, enabling tools to introspect API constraints.
What GA Means for Users and Developers
With the GA graduation in Kubernetes v1.36, Declarative Validation is now stable and enabled by default. This brings tangible benefits across the Kubernetes ecosystem.
More Reliable and Documented APIs
Because validation rules are now declared in a single place—the type definitions—they are less prone to drift or inconsistency. API consumers get more predictable error messages, and documentation can be auto-generated from the tags. For example, an OpenAPI specification can include validation constraints directly, allowing clients to validate inputs before sending requests. This reduces round trips and improves developer productivity.
Future Integration with OpenAPI and Tools
The GA release unlocks the ability to publish validation rules through the OpenAPI schema, making them accessible to a wide range of tools. Kubebuilder, for instance, will be able to generate controller code that respects the same validation tags. This means third-party operators and custom resources can benefit from the same declarative validation framework without extra effort. Additionally, admission webhooks and policy engines (like OPA/Gatekeeper) can consume these rules for richer governance.
For contributors and ecosystem developers, the migration to validation-gen eliminates the need to write and maintain thousands of lines of validation code. The unified framework reduces review burden, speeds up changes, and makes the codebase more approachable for new contributors.
Conclusion
Kubernetes v1.36's Declarative Validation GA is a quiet but powerful improvement. It addresses years of technical debt, brings consistency to API constraints, and opens the door to smarter tooling and automation. Whether you're a cluster administrator ensuring resource compliance, an application developer building on Kubernetes APIs, or a contributor extending the platform, this feature makes your life easier. The days of hunting through handwritten validation code are over—welcome to declarative validation in Kubernetes.