Kubernetes v1.36 Celebrates General Availability of Declarative Validation
Kubernetes has taken a significant step forward with the release of v1.36, marking the General Availability (GA) of its Declarative Validation framework. This transition brings enhanced reliability, predictability, and more well-documented APIs to users. By adopting a declarative approach, Kubernetes paves the way for validation rules to be published via OpenAPI, while also facilitating better integration with tools like Kubebuilder. For developers involved in the Kubernetes ecosystem, this move consolidates thousands of lines of handwritten validation code into a unified, maintainable framework.
Why This Change was Necessary
Kubernetes has long relied on handwritten Go code for the validation of its native APIs. With the growth of the API surface, maintaining this custom codebase became increasingly problematic. Some major issues surfaced:
- Technical Debt: The reliance on 18,000 lines of boilerplate validation led to a codebase that was cumbersome to manage and rife with potential errors, especially during code reviews.
- Inconsistency: Validation rules lacked coherence, often varying across different resources due to the absence of a centralized framework.
- Opaque APIs: Without visibility into the validation logic, developers and toolkits faced unpredictable validation rules, often requiring consultation of source code or facing run-time errors.
To address these challenges, the Kubernetes community proposed the Declarative Validation framework. By utilizing Interface Definition Language (IDL) tags, specifically +k8s: marker tags, developers can embed validation rules directly within types.go files, resolving these pain points.
Introducing validation-gen
The core of the declarative validation framework is the new code generator known as validation-gen. Similar to other code generators within Kubernetes, this tool analyzes +k8s: tags and automatically produces corresponding Go validation functions. These generated functions are seamlessly registered with the API scheme. The extensibility of validation-gen allows developers to add new validators as needed, enhancing the framework's versatility.
A New Suite of +k8s: Tags
The introduction of this framework comes with a comprehensive suite of marker tags that enhance validation for Go types. For details, a full reference can be found in the official documentation. Some notable tags include:
- Presence:
+k8s:optional,+k8s:required - Basic Constraints:
+k8s:minimum=0,+k8s:maximum=100,+k8s:maxLength=16 - Collections:
+k8s:listType=map,+k8s:listMapKey=type - Unions:
+k8s:unionMember,+k8s:unionDiscriminator - Immutability:
+k8s:immutable,+k8s:update=[NoSet, NoModify, NoClear]
For instance, using tags directly above field definitions signifies constraints clearly, making them visible and self-documenting to developers.
Advanced Features: Ambient Ratcheting
Another noteworthy advancement is the adoption of validation ratcheting, which is now a built-in feature. Historically, tightening validation rules required complex, manual ratcheting code. This process involved waiting for a release cycle, creating a risk of breaking existing objects.
Declarative validation simplifies this with a built-in mechanism: when a user updates an object, the framework compares the incoming object with its previous state. If a field’s value remains unchanged, the new validation can be bypassed. This "ambient ratcheting" feature allows developers to modify validation rules with minimal disruption, enhancing the user experience.
Scaling API Reviews with kube-api-linter
The journey to GA for Declarative Validation involved rigorous confidence in the generated code. Beyond validation, the framework aims to streamline API reviews. By organizing validation rules into structured markers rather than obscure functions, tools like kube-api-linter can now analyze API types statically and enforce conventions automatically. This enhancement reduces the manual review workload for SIG API Machinery reviewers while providing immediate feedback to contributors.
What Lies Ahead?
As Kubernetes v1.36 confirms the GA status of Declarative Validation, this feature is now routinely enabled by default. Moving forward, the Kubernetes team is committed to further integration of this framework. The goal includes migrating remaining legacy validation code and ensuring its use in all new APIs.
This effort will minimize the complexity of the codebase while improving the consistency and reliability of the overall Kubernetes API. Moreover, the declarative nature of this validation allows for future enhancements in the broader ecosystem. Validation rules defined as structured markers can now be parsed and represented in OpenAPI schemas, promoting advanced client-side validation methods before any API requests are sent to the cluster.
Community Engagement
The transition to Declarative Validation remains a work in progress. While the framework has reached GA, remaining legacy APIs still require migration to this new format.
Those interested in contributing to the Kubernetes API Machinery are encouraged to explore opportunities. They can consult the validation-gen documentation or review issues marked with sig/api-machinery. Additionally, community discussions are active on the Slack channels #sig-api-machinery and #sig-api-machinery-dev-tools. Joining SIG API Machinery meetings is another excellent way to engage with these developments.
Acknowledgments
Gratitude goes to all who contributed to bringing this feature to GA:
- Tim Hockin
- Joe Betz
- Aaron Prindle
- Lalit Chauhan
- David Eads
- Darshan Murthy
- Jordan Liggitt
- Patrick Ohly
- Maciej Szulik
- Wojciech Tyczynski
- Joel Speed
- Bryce Palmer
And to all in the Kubernetes community who contributed to this major enhancement.
Here's to an exciting future with a declarative approach to Kubernetes validation!
