docs: add necessary feature gate information for KEP-5073 - Declarative Validation of K8s Native Types With validation-gen

[aaron-prindle]

PR related to docs changes necessary for KEP 5073

KEP Issue: kubernetes/enhancements#5073
KEP PR: kubernetes/enhancements#5074

KEP Implementation PRs:

• Migrate to declarative validation - ReplicationController spec.replicas and spec.minReadySeconds fields: Migrate to declarative validation: ReplicationController spec.replicas and spec.minReadySeconds fields kubernetes#130725
• Enable Declarative Validation for ReplicationController: Enable Declarative Validation for ReplicationController kubernetes#130724
• add declarative validation metrics and associated runtime verification tests: [Declarative Validation] feat: add declarative validation metrics and associated runtime verification tests kubernetes#130705
• Add default + optional handling: Declarative validation: Add default + optional handling kubernetes#130706
• add Add CoveredByDeclarative to field error struct: [Declarative Validation] Add CoveredByDeclarative to field error struct kubernetes#130695
• add feature gates: feat: add DeclarativeValidation and DeclarativeValidationMismatchMetric feature gates kubernetes#130478, [Declarative Validation] update Declarative Validation featuregate kubernetes#130703
• add validation-gen framework: KEP-5073: Declarative Validation: Add validation generator kubernetes#130349

(related: kubernetes/enhancements#5073 (comment))

[netlify]

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Name	Link
🔨 Latest commit	fc8270a
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/67e19ff822dcde0009a29568

[netlify]

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	fc8270a
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/67e19ff822dcde0009a2956d
😎 Deploy Preview	https://deploy-preview-49732--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[hacktivist123]

Hello @aaron-prindle 👋 please take a look at Documenting for a release - PR Ready for Review to get your PR ready for review before Tuesday 25th March 2025 18:00 PDT. Thank you!

[aaron-prindle]

@hacktivist123 thanks for the information here. This PR is ready for review and I have changed the status to such. The docs mention:

When you complete your content, the documentation person assigned to your feature reviews it. To ensure technical accuracy, the content may also require a technical review from corresponding SIG(s). Use their suggestions to get the content to a release ready state.

I am not sure if our feature has an assigned documentation person, do you happen to know who that might be or if we assign that person? I'm going to tag @sftim for now to attempt to get into a review queue but happy to change it if there is a more appropriate person for review. Thanks!

/assign @sftim

[aaron-prindle]

I think we should merge this PR (which adds descriptions for feature gates) after the docs have merged into the v1.33, so that the feature gate descriptions can link to those docs.

@aaron-prindle do you have plans to write documentation about declarative validation rules? I imagine some will be needed.

There was not plans to write this documentation for the v1.33 release, initially the idea was to only add the feature gate documentation in v1.33. Declarative Validation is a maintainer+developer facing feature primarily, not an end-user facing feature (it unlocks some end users features but not in the near term). In v1.34 the plan was to add a full set of kubernetes developer facing documentation that explains:

• how to create new Declarative Validation "Validators"/tag (ex: Add +k8s:minimum validation tag kubernetes#130730)
• how to use Declarative Validation generally and have docs for each "Validator"/tag (will be auto-gen from Docs field here: https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/code-generator/cmd/validation-gen/validators/limits.go#L70-L80)
• how to enable/plumb a new k8s type into Declarative Validation with proper gating (ex: Enable Declarative Validation for ReplicationController kubernetes#130724)
• how to migrate a field in k/k to use Declarative Validation (ex: Migrate to declarative validation: ReplicationController spec.replicas and spec.minReadySeconds fields kubernetes#130725)

The plan was to do this in v1.34 when we have upstreamed more of the validators to k/k and have documented the plan for how we want developers using declarative validation for new k8s native APIs/fields as well as where we want to focus the k8s dev community on the migration (we are hoping to get the community to aid in the migration and document how they can be most effective)

[aaron-prindle]

/cc @jpbetz

[jpbetz]

/approve
/lgtm
For technical content

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: 3e8bf15161b422ea05926784183524a01d45a8cb

[aaron-prindle]

@sftim would it be possible to merge the feature gate PR as is for now w/o the additional documentation mentioned? Currently the plan from folks working on Declarative Validation was for additional documentation to land once we have added some additional Validators upstream and then we can document the usage of those additional validators in our initial documentation piece. We plan to add the documentation noted in the comments above in a future PR

[sftim]

In v1.34 the plan was to add a full set of kubernetes developer facing documentation that explains

We ask for documentation the first time a feature gate is added, unless the feature gate doesn't have an effect (in which case, usually the project should revert the feature gate in the code).

If someone is writing an extension API server, and they want to use this, what do they need to know? We should aim to document a minimum useful level of detail.

[jpbetz]

In v1.34 the plan was to add a full set of kubernetes developer facing documentation that explains

We ask for documentation the first time a feature gate is added, unless the feature gate doesn't have an effect (in which case, usually the project should revert the feature gate in the code).

If someone is writing an extension API server, and they want to use this, what do they need to know? We should aim to document a minimum useful level of detail.

This one is tricky. The feature gate switches the implementation of validation (for only 2 fields in ReplicationController in 1.33). When the feature gates are on there is an additional metric. The feature gate docs plus the metrics docs feel like they explain this reasonably well.

The apiserver, as a library, cannot reasonably use it yet because the validation tags implemented are only sufficient for the fields we've migrated so far.

I agree with the sentiment that we should document features as we go. I'm struggling a bit to find a somewhere we could write something meaningful. We're adding validation-gen next to defaulter-gen and others. Most of the documentation for the adjacent code exists in the readme in package docs and readme files. https://kubernetes.io/docs/tasks/extend-kubernetes/setup-extension-api-server/ does not feel like a good place to put a page.

I was expecting us to do the bulk of declarative validation in the code and in the contrib repository (for guides on how to migrate).

Should we introduce a new page for "apiserver development" or "extension apiserver internals"? Does that fit into the website?

[sftim]

I agree that this doesn't seem to need much documentation, but I think it needs some.

Should we introduce a new page for "apiserver development" or "extension apiserver internals"? Does that fit into the website?

Maybe just a stub. We already have https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/ and that page could link to the stub.
[Ideally: we eventually document more than a stub, but that's a separate improvement]

We don't need any documentation aimed at people contributing to Kubernetes itself (but if we did, it would live within https://k8s.dev/docs/ anyway and not on this site).

• When this change is stable, what differences will an end-user cluster administrator see?
• During the journey to stability, what do people need to know about declarative validation around cluster upgrades?
• Who might need to turn off this feature gate (v1.33 and also our expectations for future versions) and why.

[aaron-prindle]

Maybe just a stub. We already have https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/ and that page could link to the stub.
[Ideally: we eventually document more than a stub, but that's a separate improvement]

We don't need any documentation aimed at people contributing to Kubernetes itself (but if we did, it would live within https://k8s.dev/docs/ anyway and not on this site).

When this change is stable, what differences will an end-user cluster administrator see?
During the journey to stability, what do people need to know about declarative validation around cluster upgrades?
Who might need to turn off this feature gate (v1.33 and also our expectations for future versions) and why.

@sftim - I have submitted a PR to add documentation that addresses the questions in the quoted comment and links this documentation in the suggested page. Link to the PR is here: #50265

[aaron-prindle]

@sftim I have addressed all feedback from the initial round of reviews and the related PR for a separate Declarative Validation docs page spawned from comments here (#50265) is merged now. I believe this is ready for another round of reviews now, thanks.

[rayandas]

Hello @aaron-prindle 👋! I'm reaching out from the Docs team. Just checking in as we approach Docs Freeze on 8th April, 2025 18:00 PDT.
This documentation appears to still be under review. To meet the Docs Freeze, this PR must have a technical review as well as lgtm and approve labels applied, without any unaddressed comments or concerns from SIG Docs.
The status of this enhancement is marked as At risk for docs freeze. Thank you!

[tengqm]

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jpbetz, tengqm

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• content/en/docs/OWNERS [tengqm]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment