10 Key Updates in Kubernetes v1.36: Declarative Validation Goes GA
Kubernetes v1.36 marks a milestone for API reliability and developer experience. Declarative validation for native types has graduated to General Availability (GA), replacing thousands of lines of error-prone handwritten code with a unified, maintainable framework. This change brings more predictable APIs, better documentation, and opens the door to future integrations like OpenAPI-based rule publication and smoother tooling with Kubebuilder. In this article, we break down the ten most important aspects of this update—from the motivation behind the shift to the specific marker tags you'll now see in the Kubernetes codebase. Whether you're a cluster administrator, a contributor, or an ecosystem developer, these changes will impact how you interact with the API.
1. Why Declarative Validation Matters
The move to declarative validation is a fundamental shift in how Kubernetes enforces API rules. Instead of relying on opaque, handcrafted Go functions, the new framework uses +k8s: marker tags embedded directly in type definitions. This means validation logic is now explicit, discoverable, and consistent across all native resources. For users, the result is fewer runtime surprises and clearer API documentation. For contributors, it reduces code review burden and eliminates a major source of technical debt. The GA status signals that this approach is production-ready and will be the standard going forward.
2. The Hidden Cost of Handwritten Validation
Before v1.36, the Kubernetes project maintained approximately 18,000 lines of handwritten validation code. This approach had three critical drawbacks. First, it created immense technical debt: every new field or constraint required writing and reviewing a custom Go function. Second, inconsistency crept in—different resources sometimes enforced similar rules in slightly different ways. Third, the validation logic was opaque to external tools and APIs; clients had no way to discover rules without reading source code or failing at runtime. Declarative validation solves all three problems by codifying constraints at the type level.
3. Meet validation-gen: The New Code Generator
At the heart of this feature is a new generator called validation-gen. Much like the generators Kubernetes already uses for deep copies, conversions, and defaulting, validation-gen parses +k8s: marker tags from types.go files and automatically produces the corresponding Go validation functions. These generated functions are then seamlessly registered with the API scheme. The generator is designed as an extensible framework, allowing developers to create custom validators by defining new tags and the Go logic they should emit. This reduces boilerplate and ensures consistency across the entire codebase.
4. The Full Suite of +k8s: Marker Tags
Declarative validation introduces a comprehensive set of +k8s: marker tags that cover most common validation patterns. These tags are optimized for Go types and are now actively used throughout the Kubernetes codebase. For a complete list, refer to the official documentation. Below we highlight the most important categories, starting with presence rules. Each tag is placed directly on a field in the type definition, making validation logic transparent and self-documenting.
5. Presence Tags: optional and required
The +k8s:optional and +k8s:required tags are the simplest yet most impactful. They explicitly declare whether a field must be present in an API request. Previously, this logic was buried in handwritten validation functions; now it's a marker on the struct field itself. This change improves both developer experience and API documentation. When reading a type definition, you can immediately see which fields are mandatory versus optional, reducing ambiguity and the chance of misconfiguration.
6. Basic Constraints: min, max, length, and format
For numeric and string fields, the framework provides tags like +k8s:minimum=0, +k8s:maximum=100, +k8s:maxLength=16, and +k8s:format=k8s-short-name. These replace dozens of hand-coded bounds checks with a single declarative annotation. The format tag is particularly powerful, as it enforces well-known patterns (e.g., DNS subdomain, email) without writing regex functions. Together, these tags make validation rules more visible, easier to audit, and less prone to off-by-one errors.
7. Collection Constraints: listType and listMapKey
Kubernetes frequently uses lists and maps in its API. The tags +k8s:listType=map and +k8s:listMapKey=type allow developers to specify how collections should be validated and merged. For example, declaring a list as a map with a primary key ensures that entries are unique and can be updated individually. This replaces handwritten logic that often had subtle bugs. The declarative approach also enables better client-side caching and server-side apply, as merge semantics are now explicit in the type definition.
8. Union Validation with +k8s: Tags
Unions—fields where exactly one option must be set—are a common pattern in Kubernetes APIs. The new framework introduces tags (e.g., +k8s:union and related discriminators) to enforce mutual exclusivity declaratively. Previously, union validation required complex Go code with multiple checks. Now, a single marker tag on the struct, combined with field-level tags, ensures that only one field in a union group is populated at a time. This reduces bugs and makes the intent crystal clear.
9. Paving the Way for OpenAPI Integration
One of the most exciting long-term benefits of declarative validation is the ability to publish validation rules via OpenAPI. Since the rules are now expressed as structured annotations rather than Go code, they can be extracted and exposed in the API specification. This means client libraries, web UIs, and tools like kubectl could eventually validate requests client-side without contacting the API server. Future versions may include automatic generation of OpenAPI validation blocks from +k8s: tags, making the ecosystem more robust and responsive.
10. Ecosystem Impact: Kubebuilder and Beyond
The GA of declarative validation has immediate implications for the broader Kubernetes ecosystem. Tools like Kubebuilder, which help developers build custom controllers and CRDs, can now leverage the same +k8s: tags for validation. This means custom resources will benefit from the same consistency and discoverability as native types. Additionally, third-party API clients can introspect validation rules more easily, leading to better IDE support, automated linting, and more reliable automation. The shift to declarative validation is not just an internal improvement—it's a enabler for the entire ecosystem.
Kubernetes v1.36's graduation of declarative validation to GA represents a significant leap forward in API quality and maintainability. By replacing thousands of lines of error-prone Go code with a unified, annotation-driven framework, the project has made validation rules transparent, consistent, and extensible. Whether you're writing a CRD with Kubebuilder, managing a cluster, or building tooling, these changes will lead to fewer surprises and smoother operations. As the ecosystem adopts these markers, expect even tighter integration with OpenAPI, client-side validation, and a more predictable Kubernetes experience overall.