docs: add declarative validation patterns for feature-gates.md

[yongruilin]

Documents declarative validation (DV) patterns for interacting with feature gates using +k8s:ifEnabled and +k8s:ifDisabled tags. The existing doc only covered handwritten validation patterns. As Kubernetes migrates to
declarative validation, feature authors need guidance on:

• Using +k8s:forbidden + +k8s:ifEnabled for feature-gated new API fields
• Using +k8s:ifEnabled/+k8s:ifDisabled for conditional field constraints and enum values
• Wiring feature gates to validation options via rest.WithOptions
• How DV ratcheting replaces the handwritten "already in use" pattern

Also clarifies existing validation subsections as "Handwritten validation" to disambiguate from the DV approach.

Which issue(s) this PR fixes:

Fixes #

[yongruilin]

/assign @thockin

[jpbetz]

This documentation is surprising. While we do wipe the field for purposes of create. We continue to respect the field once it is "in use". I think we should update this paragraph and a paragraph about "in-use".

Take for example pod.spec.initContainer.resetPolicy. If this field is set when creating a pod, it creates a pod with a sidecar container. Ignoring or unsetting the field results in a pod that will treat the sidecar container as a normal init container, which is almost certainly going to break the workload.

Some other examples: InPlacePodVerticalScaling, HPAConfigurableTolerance, PreferSameTrafficDistribution, RecursiveReadOnlyMounts, ContainerStopSignals.

In all these examples, once a field is set, even after the FG is disabled, it continue to remain set AND remain mutable.

[yongruilin]

Yes, the current wording implies fields are always discarded when the gate is off, but in practice most dropDisabled* functions follow a !Enabled(featureX) && !fieldInUse(old). (Though not consistent — some cases drop unconditionally without an in-use check)

This also carries into validation - when gates off, some keeps validating when the fields is "in-use", while some directly forbid any update.

I think a feature gate should control the entrypoint, not the lifecycle of existing data:

• Create / not in use: drop the field — no new adoption of a disabled feature.
• In use: preserve the field, keep it mutable, and validate normally — data integrity matters, and freezing the field prevents users from fixing bad values when the gate was disabled precisely because something went wrong.

@thockin since you authored this section, thoughts?

[thockin]

IIRC this was the result of considering all of the options, where none of them are good. The lesser evil.

If we were to auto-wipe the data, we will cause havoc with apply-loops and saved state (e.g. cgroup config).

If we tell people to keep handling a feature, even when the gate is disabled, the worst case is that they are triggering a bug which crashes components making the cluster unusable.

If we tell them to mostly ignore the feature, the worst case is that some things misbehave, but the feature is neutralized and less likely to cause damage.

None of these are clearly correct.

This is a very unlikely scenario, either way, so (again, IIRC) we just decided to do the least-worst thing.

[thockin]

IIRC this was the result of considering all of the options, where none of them are good. The lesser evil.

If we were to auto-wipe the data, we will cause havoc with apply-loops and saved state (e.g. cgroup config).

If we tell people to keep handling a feature, even when the gate is disabled, the worst case is that they are triggering a bug which crashes components making the cluster unusable.

If we tell them to mostly ignore the feature, the worst case is that some things misbehave, but the feature is neutralized and less likely to cause damage.

None of these are clearly correct.

This is a very unlikely scenario, either way, so (again, IIRC) we just decided to do the least-worst thing.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

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

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

Details

Needs approval from an approver in each of these files:

• contributors/devel/sig-architecture/OWNERS

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