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

[sftim]

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.

[sftim]

Is this in-tree APIs or extension APIs from CRDs or aggregated external APIs or some mix of the other.

[aaron-prindle]

This is for the in-tree APIs that currently have a declarative validation migration/declaration in place (more fields/whole-types will be converted over time in v1.34+). Currently this is ReplicationSet.[Replias|MinReadySeconds]

kubernetes/kubernetes#130725

I've updated the text to state this now (see below), thanks!

Enables declarative validation of in-tree Kubernetes APIs. When enabled, APIs with declarative validation rules (defined using IDL tags in the Go code) will have both the generated declarative validation code and the original hand-written validation code executed. ...

[sftim]

See DeclarativeValidationTakeover for more.

Change this to a hyperlink to the documentation (which you, or a colleague from the SIG, will need to write).

[aaron-prindle]

I am happy to write this documentation but I am currently a bit confused as I was intending for this to essentially just link to the other feature gate documentation that is already a part of this PR. I have added such a link now:

The original hand-written validation are still the authoritative validations when this is enabled but this can be changed if the DeclarativeValidationTakeover feature gate is enabled in addition to this gate. ...

Can you clarify what we hope for this additional documentation to have? Our current plan was to add more docs for v1.34 as we build out more validators but it is possible to add such docs now as well. Thanks!

[sftim]

Change ”declarative validation“ to a link to the docs for this (which you, or a colleague from the SIG, will need to write).

[aaron-prindle]

I have tentatively pointed this to link to the DeclarativeValidation feature gate file (already a part of this PR). I'm happy to write this additional documentation but our current plan was to add such docs in v1.34 so going to hold off for now as we discuss a bit more

[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

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: jpbetz
Once this PR has been reviewed and has the lgtm label, please ask for approval from sftim. For more information see the Code Review Process.

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

Needs approval from an approver in each of these files:

• content/en/docs/OWNERS

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

[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.