Kubernetes v1.36 Declares Declarative Validation Generally Available—Ending Years of Handwritten API Rules

Breaking: Kubernetes v1.36 Ships Declarative Validation to GA

Kubernetes v1.36 has officially graduated Declarative Validation for native types to General Availability (GA), the project’s SIG API Machinery announced today. The move replaces over 18,000 lines of handwritten validation code with a maintainable, tag-based framework.

“This is a foundational change that makes Kubernetes APIs more reliable, predictable, and documentable,” said a lead contributor from SIG API Machinery. “Users will immediately benefit from clearer error messages and fewer inconsistencies.”

Key Highlights

• Validation-gen code generator automatically produces Go validation functions from +k8s: marker tags.
• Declarative rules can be published via OpenAPI, opening the door for ecosystem tools like Kubebuilder.
• GA status means the feature is production-ready and stable under the Kubernetes deprecation policy.

The release addresses long-standing technical debt accumulated since Kubernetes’ early days, when validation logic was written manually for each field and resource.

Background

For years, validating Kubernetes native APIs relied exclusively on handwritten Go code. Every constraint—minimum values, mutually exclusive fields, list uniqueness—required explicit Go functions.

Over time, the codebase swelled with roughly 18,000 lines of boilerplate validation, making maintenance error-prone and code reviews intense. Inconsistencies across resources became common, and validation rules were opaque to clients and tooling.

“Developers often discovered missing validation only at runtime, after submitting a malformed request,” explained a SIG API Machinery engineer. “That was a poor developer experience, especially for newcomers.”

The solution emerged from SIG API Machinery: use Interface Definition Language (IDL) tags—specifically +k8s: marker tags—embedded directly in types.go files to define validation rules declaratively.

The New Validation Framework: validation-gen and +k8s: Tags

At the heart of the feature is validation-gen, a new code generator that parses +k8s: tags and automatically generates the corresponding Go validation functions. These functions are then registered seamlessly with the API scheme.

The generator is extensible—developers can plug in new validators by describing the tags they parse and the Go logic they should produce. A comprehensive suite of +k8s: tags covers:

• 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:unionDiscriminator, +k8s:unionField

“Instead of reading thousands of lines of code, you now look at a few tags to understand a field’s validation,” the SIG APIMachinery lead noted. “That’s a huge win for both contributors and security auditors.”

What This Means

For Kubernetes users and operators: APIs become more reliable and consistent. Error messages will be clearer because validation is now generated from a single source of truth. Upgrading to v1.36 means fewer unexpected rejections and faster debugging.

For contributors and ecosystem developers: Handwritten validation code is being replaced with a unified, maintainable framework. This reduces the risk of bugs during code reviews and lowers the barrier for adding new validation rules.

For tooling and automation: Declarative rules can be published via OpenAPI, enabling tools like Kubebuilder to consume validation logic programmatically. This opens the door for richer client-side validation and better integration with CI/CD pipelines.

“This GA marks a shift from a manually curated validation system to a machine-readable, declarative one,” said the SIG APIMachinery engineer. “It’s a critical step toward making Kubernetes APIs self-documenting and easier to extend.”

For a full list of supported +k8s: tags, refer to the official documentation.