Kubernetes 1.36’s Declarative Validation Goes GA: A New Era for API Reliability

By • min read

Introduction

With the release of Kubernetes v1.36, the project reaches a significant milestone: Declarative Validation for native Kubernetes types is now generally available (GA). This shift from handwritten validation logic to a declarative, tag-based framework promises more predictable APIs, reduced maintenance burden, and enhanced integration possibilities—including the eventual publication of validation rules via OpenAPI and tighter coupling with tools like Kubebuilder.

For end users, this translates into APIs that are more reliable and better documented. For contributors, it means saying goodbye to thousands of lines of error-prone Go code. In this article, we’ll explore why this change was necessary, how the new declarative validation framework operates, and what capabilities this GA release unlocks.

The Motivation: Escaping Technical Debt

For years, Kubernetes relied on manual Go functions to validate API fields. Need a minimum value? Write a Go function. Need two fields to be mutually exclusive? Write another function. As the API surface grew, this approach accumulated roughly 18,000 lines of boilerplate validation code—a burden that became increasingly difficult to maintain and review.

This handwritten approach led to several pain points:

• Technical debt: Thousands of lines of repetitive code that required meticulous attention during code reviews and were prone to bugs.
• Inconsistency: Without a centralized framework, validation rules sometimes varied across similar resources, leading to confusion.
• Opaque APIs: Validation logic was hidden in source code, making it impossible for clients or tooling to discover rules programmatically. Users often only learned about constraints when encountering runtime errors.

The solution, championed by SIG API Machinery, was Declarative Validation—a system that uses Interface Definition Language (IDL) marker tags (like +k8s:) directly in types.go files to define validation rules. This declarative approach eliminates the need for hand-coded validation functions and brings consistency, discoverability, and maintainability to the forefront.

How Declarative Validation Works

The validation-gen Generator

At the heart of the feature is a new code generator called validation-gen. Similar to existing Kubernetes generators for deep copies, conversions, and defaulting, validation-gen parses +k8s: tags and automatically generates the corresponding Go validation functions.

These generated functions are seamlessly registered with the API scheme. Moreover, the generator is designed as an extensible framework: developers can plug in custom “Validators” by describing the tags they parse and the Go logic they should produce. This flexibility makes it easy to extend validation capabilities without touching the core generator.

A Comprehensive Suite of +k8s: Tags

The declarative validation framework introduces a rich set of marker tags that cover common validation needs. These tags are highly optimized for Go types and can be placed directly on struct fields. Here’s a catalog of some of the most frequently used tags:

• 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:union and related tags for one-of constructions
• Patterns and cross-field validation: Tags for regex patterns, minItems, maxItems, and more (see the official documentation for the full list).

With these tags, developers can express complex validation rules concisely and in a way that is self-documenting and machine-readable.

Implications for Users and Ecosystem

The GA of Declarative Validation is more than a technical improvement—it lays the groundwork for future enhancements. Because validation rules are now expressed declaratively, they can be published via OpenAPI, enabling clients and tools to discover constraints without reading source code. This paves the way for richer IDE support, automated API documentation, and better integration with Operator frameworks like Kubebuilder.

For the Kubernetes community, this means:

• Fewer bugs: Automated generation reduces human error in validation logic.
• Faster reviews: Code reviewers no longer need to scrutinize hundreds of hand-written validation functions.
• Better tooling: Declarative rules can be leveraged by linters, API version converters, and schema validators.

Conclusion

Kubernetes v1.36’s graduation of Declarative Validation to GA marks a pivotal step in making the platform more robust, maintainable, and developer-friendly. By replacing thousands of lines of handwritten Go code with a declarative tag system, the project reduces technical debt, improves consistency, and opens the door to deeper ecosystem integration. Whether you’re a casual user or a core contributor, this change promises a more reliable and transparent Kubernetes experience.

For more details, refer to the official Kubernetes documentation or the validation library code.