Skip to content

Kubernetes v1.36: Declarative Validation Graduates to GA

Kubernetes v1.36 promotes Declarative Validation to General Availability for all native Kubernetes types.

Release Summary

This foundational shift replaces thousands of lines of handwritten Go validation code with a standardized, machine-readable framework. The change makes API validation behavior more predictable and consistent across the platform while enabling future capabilities like publishing validation rules directly in OpenAPI specifications. For cluster operators, this release delivers more reliable API behavior and clearer error messages when resources fail validation. The framework also creates a path for better integration with ecosystem tooling, particularly for custom resource definitions and operator development workflows.

Key Changes

The GA release of Declarative Validation fundamentally restructures how Kubernetes validates API requests. Previously, each field constraint required explicit Go code scattered across the codebase. Now, validation rules are expressed declaratively using Common Expression Language (CEL) embedded directly in API definitions. This migration affects every core Kubernetes resource type, from Pods and Services to StatefulSets and ConfigMaps.

The declarative approach means validation logic lives alongside the field definitions it protects, rather than buried in separate validation functions. When you submit a manifest that violates a rule, the API server now returns errors that directly reference the declarative constraint rather than generic validation failures. This makes troubleshooting misconfigurations significantly faster because error messages map directly to documented field requirements.

The framework also standardizes how cross-field validation works. Rules that check relationships between multiple fields, such as mutually exclusive options or conditional requirements, now follow consistent patterns. This consistency reduces edge cases where validation behavior might have varied subtly between similar resource types.

With GA status, the validation rules are stable and fully supported. The Kubernetes project has completed migrating all native types to this model, eliminating the technical debt of maintaining parallel validation systems. Future API changes will use declarative validation exclusively, preventing the accumulation of new handwritten validation code.

Breaking Changes and Deprecations

The move to declarative validation tightens some previously loose API constraints. Validation that was implicit or inconsistently enforced in handwritten code now applies uniformly. While Kubernetes maintains strict backward compatibility guarantees, the stricter enforcement may surface configuration issues that silently passed validation in earlier versions.

Operators should audit their resource manifests against the following specific risks:

  • Cross-field constraints that were partially enforced may now reject previously accepted combinations. Review any resources using conditional fields or mutually exclusive options, particularly in Pod security contexts, volume configurations, and network policies.

  • Numeric bounds and string patterns are now consistently validated across all resource types. Check for edge cases where fields were set to boundary values or unusual formats that may have bypassed incomplete validation.

  • Transitional fields that maintained deprecated behavior alongside newer alternatives may now strictly enforce the intended migration path. Examine resources using fields marked deprecated in v1.34 or earlier.

  • Custom admission webhooks that duplicated validation logic may now conflict with stricter API-level checks. Test webhook interactions in non-production environments before upgrading production clusters.

The declarative framework itself does not deprecate any APIs or features, but it may expose latent configuration issues that went undetected under less rigorous validation.

Why It Matters for Operators

This change directly impacts how you diagnose and fix resource validation failures. When a kubectl apply fails due to validation errors, the improved error messages now pinpoint exactly which declarative rule was violated and why. This eliminates the debugging cycles spent interpreting vague "invalid value" messages or tracing through source code to understand constraints.

For teams building custom resources and operators, the declarative validation framework provides a clear model to follow. The CEL-based approach used in native types is the same framework available for CRD validation, creating consistency between core Kubernetes resources and custom extensions. This alignment simplifies operator development and makes validation behavior more predictable across your entire API surface.

The GA milestone also signals readiness for ecosystem integration. Tools like Kubebuilder and controller-gen can eventually consume declarative validation rules directly from OpenAPI schemas, automatically generating validated client code and accurate documentation. This reduces the manual work required to keep operator codebases synchronized with API constraints.

From a reliability perspective, the unified validation framework reduces the risk of inconsistent behavior across resource types. When validation rules are declared explicitly rather than implemented piecemeal in scattered Go functions, the entire platform becomes more maintainable and less prone to subtle bugs in constraint enforcement.

Upgrade Actions

Before upgrading production clusters to v1.36, validate your existing resource definitions in a test environment. Apply all manifests and monitor for validation errors that did not appear in previous versions. Pay particular attention to resources modified by automation or generated by CI/CD pipelines, as these are most likely to contain edge cases.

Review admission controller and webhook logs for validation failures that may have been silently ignored or handled inconsistently. The stricter declarative validation may surface issues that webhooks previously caught downstream, allowing you to move validation logic upstream into resource definitions where appropriate.

Update internal documentation and runbooks to reflect the improved error message format. Train platform teams to interpret CEL-based validation errors, as these will replace the older Go function error messages. The more explicit error format should reduce mean time to resolution for configuration issues.

For teams maintaining custom operators or controllers, audit your CRD validation rules to align with the declarative patterns now standard in native types. Consider migrating complex validation logic from webhook code to CEL expressions in CRD schemas where possible, taking advantage of the same framework Kubernetes core resources now use.

Test the upgrade path in staging with full workload coverage before scheduling production upgrades. While breaking changes are minimal, the tightened validation enforcement warrants thorough pre-upgrade verification of all active resource configurations.