Declarative API Validation

Kubernetes 1.33 includes optional declarative validation for APIs. When enabled, the Kubernetes API server can use this mechanism rather than the legacy approach that relies on hand-written Go code (validation.go files) to ensure that requests against the API are valid. Kubernetes developers, and people extending the Kubernetes API, can define validation rules directly alongside the API type definitions (types.go files). Code authors define pecial comment tags (e.g., +k8s:minimum=0). A code generator (validation-gen) then uses these tags to produce optimized Go code for API validation.

While primarily a feature impacting Kubernetes contributors and potentially developers of extension API servers, cluster administrators should understand its behavior, especially during its rollout phases.

Declarative validation is being rolled out gradually. In Kubernetes 1.33, the APIs that use declarative validation include:

• ReplicationController

• DeclarativeValidation: (Beta, Default: true) When enabled, the API server runs both the new declarative validation and the old hand-written validation for migrated types/fields. The results are compared internally.
• DeclarativeValidationTakeover: (Beta, Default: false) This gate determines which validation result is authoritative (i.e., returned to the user and used for admission decisions).

Default Behavior (Kubernetes 1.33):

• With DeclarativeValidation=true and DeclarativeValidationTakeover=false (the default values for the gates), both validation systems run.
• The results of the hand-written validation are used. The declarative validation runs in a mismatch mode for comparison.
• Mismatches between the two validation systems are logged by the API server and increment the declarative_validation_mismatch_total metric. This helps developers identify and fix discrepancies during the Beta phase.
• Cluster upgrades should be safe regarding this feature, as the authoritative validation logic doesn't change by default.

Administrators can choose to explicitly enable DeclarativeValidationTakeover=true to make the declarative validation authoritative for migrated fields, typically after verifying stability in their environment (e.g., by monitoring the mismatch metric).

Disabling declarative validation

As a cluster administrator, you might consider disabling declarative validation whilst it is still beta, under specific circumstances:

• Unexpected Validation Behavior: If enabling DeclarativeValidationTakeover leads to unexpected validation errors or allows objects that were previously invalid.
• Performance Regressions: If monitoring indicates significant latency increases (e.g., in apiserver_request_duration_seconds) correlated with the feature's enablement.
• High Mismatch Rate: If the declarative_validation_mismatch_total metric shows frequent mismatches, suggesting potential bugs in the declarative rules affecting the cluster's workloads, even if DeclarativeValidationTakeover is false.

To revert to only using hand-written validation (as used before Kubernetes v1.33), disable the DeclarativeValidation feature gate, for example via command-line arguments: (--feature-gates=DeclarativeValidation=false). This also implicitly disables the effect of DeclarativeValidationTakeover.

Considerations for downgrade and rollback

Disabling the feature acts as a safety mechanism. However, be aware of a potential edge case (considered unlikely due to extensive testing): If a bug in declarative validation (when DeclarativeValidationTakeover=true) incorrectly allowed an invalid object to be persisted, disabling the feature gates might then cause subsequent updates to that specific object to be blocked by the now-authoritative (and correct) hand-written validation. Resolving this might require manual correction of the stored object, potentially via direct etcd modification in rare cases.

For details on managing feature gates, see Feature Gates.