Kubernetes v1.36 Milestone: Declarative Validation Becomes Fully Stable
Introduction
With the release of Kubernetes v1.36, the Declarative Validation framework for native Kubernetes types has graduated to General Availability (GA). This significant milestone brings enhanced reliability, predictability, and better-documented APIs to users. By shifting to a declarative model, the project lays the groundwork for publishing validation rules via OpenAPI and seamlessly integrating with ecosystem tools like Kubebuilder. For contributors and ecosystem developers, this change eliminates thousands of lines of error-prone handwritten validation code, replacing them with a unified, maintainable framework. In this article, we explore why this migration was necessary, how the declarative validation mechanism operates, and what new capabilities the GA release offers.
The Motivation: Moving Beyond Handwritten Validation
For many years, validating Kubernetes native APIs relied entirely on handwritten Go code. When a field needed a minimum value, or two fields required mutual exclusivity, developers had to craft explicit Go functions to enforce those constraints. As the Kubernetes API surface grew, this manual approach led to several systemic challenges.
Technical Debt Accumulation
The project accumulated roughly 18,000 lines of boilerplate validation code. This code was hard to maintain, prone to errors, and demanded rigorous attention during code reviews.
Inconsistency Across Resources
Without a centralized framework, validation rules were sometimes applied inconsistently across different resources, leading to unpredictable behavior.
Opaque APIs
Handwritten validation logic was difficult to discover or analyze programmatically. Clients and tooling could not predictably know validation rules without consulting source code or encountering runtime errors.
The solution proposed by SIG API Machinery was Declarative Validation: using Interface Definition Language (IDL) tags (specifically +k8s: marker tags) directly within types.go files to define validation rules.
How the Declarative Validation Framework Works
Enter validation-gen: The Core Generator
At the heart of the declarative validation feature is a new code generator called validation-gen. Just as Kubernetes uses generators for deep copies, conversions, and defaulting, validation-gen parses +k8s: tags and automatically generates the corresponding Go validation functions. These generated functions seamlessly register with the API scheme. The generator is designed as an extensible framework, allowing developers to plug in new Validators by describing the tags they parse and the Go logic they should produce.
A Comprehensive Suite of +k8s: Tags
The declarative validation framework introduces a rich set of marker tags providing advanced validation capabilities tailored for Go types. For a full list of supported tags, refer to the official documentation. Below is a categorized overview of common tags now found in the Kubernetes codebase:
- 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
These tags replace the need for manual Go validation, making the intent clearer and reducing boilerplate.
New Capabilities with GA
With the GA release, users can expect:
- More Reliable APIs: Declarative validation ensures rules are consistently applied across all resources, reducing edge cases.
- Ease of Integration: The framework enables future publication of validation rules via OpenAPI, allowing third-party tools to reason about constraints without access to source code.
- Ecosystem Friendly: Tools like Kubebuilder can leverage the same tags, simplifying custom resource validation.
- Reduced Maintenance: Contributors no longer need to write and review thousands of lines of ad-hoc validation code.
Impact on Contributors and Ecosystem Developers
For those extending Kubernetes, the shift to declarative validation streamlines the process of defining new API types. Instead of coding validation logic from scratch, developers add minimal marker tags to their Go struct fields, and validation-gen handles the rest. This not only reduces human error but also alignes with Kubernetes' principle of declarative management.
Looking Forward
The graduation of Declarative Validation to GA marks a key step toward a more transparent and maintainable Kubernetes API. As the project continues to evolve, expect further integrations, such as OpenAPI-based rule exposure and tighter coupling with admission controllers. For now, API consumers can enjoy greater consistency, while contributors benefit from a cleaner codebase.
Related Resources: