Merge pull request #50265 from aaron-prindle/declarative-validation-new-doc

docs: add new declarative validation doc page and link to it

Author: k8s-ci-robot

content/en/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation.md

@@ -49,6 +49,7 @@ let you meet it.
 * To get the aggregator working in your environment, [configure the aggregation layer](/docs/tasks/extend-kubernetes/configure-aggregation-layer/).
 * Then, [setup an extension api-server](/docs/tasks/extend-kubernetes/setup-extension-api-server/) to work with the aggregation layer.
 * Read about [APIService](/docs/reference/kubernetes-api/cluster-resources/api-service-v1/) in the API reference
+*   Learn about [Declarative Validation Concepts](/docs/reference/using-api/declarative-validation.md), an internal mechanism for defining validation rules that in the future will help support validation for extension API server development.
 
 Alternatively: learn how to
 [extend the Kubernetes API using Custom Resource Definitions](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/).

content/en/docs/reference/using-api/declarative-validation.md

@@ -0,0 +1,63 @@
+---
+title: Declarative API Validation
+reviewers:
+- aaron-prindle
+- yongruilin
+- jpbetz
+- thockin
+content_type: concept
+weight: 20
+---
+
+{{< feature-state for_k8s_version="v1.33" state="beta" >}}
+
+Kubernetes {{< skew currentVersion >}} 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](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/),
+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](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/), cluster administrators should understand its behavior, especially during its rollout phases.
+
+
+
+Declarative validation is being rolled out gradually.
+In Kubernetes {{< skew currentVersion >}}, the APIs that use declarative validation include:
+
+* [ReplicationController](/docs/concepts/workloads/controllers/replicationcontroller/)
+
+{{< note >}}
+For the beta of this feature, Kubernetes is intentionally using a superseded API as a test bed for the change.
+Future Kubernetes releases may roll this out to more APIs.
+{{< /note >}}
+
+
+*   `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 {{< skew currentVersion >}}):**
+
+*   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 {#opt-out}
+
+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](/docs/reference/command-line-tools-reference/feature-gates/).