KEP-5073: Declarative Validation: Explain and update document with cross-field validation information #5290

aaron-prindle · 2025-05-08T13:27:59Z

One-line PR description: This addresses how we intend to handle cross-field validations with Declarative Validation.
Issue link: Declarative Validation Of Kubernetes Native Types With validation-gen #5073

aaron-prindle · 2025-05-08T15:18:50Z

/assign @deads2k @jpbetz @thockin
/cc @yongruilin

yongruilin · 2025-05-08T18:22:33Z

keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md

+#### Cross-Field Validation and Ratcheting
+For cross-field validations, the validation logic is evaluated at the common ancestor of the fields involved. This approach is necessary for supporting ratcheting. While validation tags (eg: +k8s:maximum=siblingField, +k8s:unionMember , etc.) may be placed on an individual field for clarity, the tag and its associated validation logic will be "hoisted" to the parent struct during code generation. This "hoisting" means the validation is treated as if it were defined on the common ancestor.  By anchoring the cross-field alidation logic at the common ancestor, regardless of tag placement, the ratcheting design can more reliably determine how to perform equality checks across the relevant type nodes and decide if re-validation is necessary.
+
+As noted in the Ratcheting section there is an additional challenge that arises if a cross-field validation rule (e.g. X < Y) is defined on a common ancestor struct/field, and an unrelated field (e.g. Z) within that same ancestor is modified. This change to Z makes the common ancestor “changed” overall, triggering re-validation of the X < Y rule. If this rule was recently evolved, it might now fail even if X and Y themselves are not modified by the user’s update. This could violate the principle “Unchanged fields do not cause update rejections”. In practice this means that the validation rules (or validation-gen generally) might have to be more explicit where each validation rule explains “I only care about these fields for ratcheting”.
+
+For the initial implementation, this behavior will be documented, and cross-field validation rules must handle ratcheting themselves.  This means that in the initial implementation of the cross-field dedicated tags referenced in the document (+k8s:unionMember, etc.), they will handle ratcheting of the fields they operate on directly.  See the Ratcheting section for more information on this issue as well as longer term plans on addressing this challenge.


Do you think it is more nature that first paragraph is in cross-field section and the 2nd & 3rd paragraphs are in ratcheting section? Maybe you don't need to put a sub-title for that 1st paragraph and then refer to the ratcheting section of how to handle this challenge case?

+1, I've combined paragraphs 2 & 3 into a single paragraph and de-duped the majority of text from the Ratcheting and Cross-Field Validation section in #5292. This paragraph now explains:

cross-field tags "hoist" all cross-field tags to the parent struct

cross-field tags implement ratcheting for the fields they operate on

jpbetz

nit only, looks good!

keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md

deads2k

I wasn't expecting to see CEL in the table. I agree with the rest, though particulars around usage of the tags will need to be worked out. Do you want to do it here, on a followup KEP update, on the implementation PR, or somewhere else?

keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md

deads2k · 2025-05-15T20:38:49Z

keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md

+       // +k8s:subfield({"type":"Denied", "status": "true"})=+k8s:unionMember
+
+       // +k8s:subfield({"type":"Failed"})=+k8s:optional
+       // +k8s:subfield({"type":"Failed"})=+k8s:immutable


The impl PR will go into the "immutable after create" versus "immutable once set"?

Yes, the related impl KEP Update will go into the "immutable after create" versus "immutable once set".

keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md

deads2k · 2025-05-15T20:40:44Z

oh, and a note that breaking on sentences makes it easier to comment on the right lines.

aaron-prindle · 2025-05-15T21:10:27Z

oh, and a note that breaking on sentences makes it easier to comment on the right lines.

Noted, I've updated the KEP Update changes here to break on sentences now.

…oss-field validation information

…tion-gen/README.md Co-authored-by: Joe Betz <[email protected]>

deads2k · 2025-06-11T21:24:08Z

I think this still works well with the other bits we've landed.

/lgtm
/approve

k8s-ci-robot · 2025-06-11T21:24:17Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: aaron-prindle, deads2k

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:

~~keps/sig-api-machinery/OWNERS~~ [deads2k]

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

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label May 8, 2025

k8s-ci-robot requested review from apelisse and deads2k May 8, 2025 13:28

k8s-ci-robot added kind/kep Categorizes KEP tracking issues and PRs modifying the KEP directory sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels May 8, 2025

aaron-prindle force-pushed the kep-5073-update-cross-field branch 2 times, most recently from 63eae72 to a65ce7c Compare May 8, 2025 14:37

k8s-ci-robot assigned deads2k, jpbetz and thockin May 8, 2025

k8s-ci-robot requested a review from yongruilin May 8, 2025 15:18

aaron-prindle closed this May 8, 2025

aaron-prindle reopened this May 8, 2025

yongruilin reviewed May 8, 2025

View reviewed changes

jpbetz reviewed May 8, 2025

View reviewed changes

keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md Outdated Show resolved Hide resolved

keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md Outdated Show resolved Hide resolved

aaron-prindle force-pushed the kep-5073-update-cross-field branch from e67cef8 to 8d62579 Compare May 8, 2025 19:30

deads2k requested changes May 15, 2025

View reviewed changes

aaron-prindle force-pushed the kep-5073-update-cross-field branch from f63f0af to 40bfe3a Compare May 15, 2025 21:09

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels May 15, 2025

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jun 6, 2025

aaron-prindle and others added 4 commits June 10, 2025 23:23

KEP-5073: Declarative Validation: Explain and update document with cr…

1c1f7d2

…oss-field validation information

Update keps/sig-api-machinery/5073-declarative-validation-with-valida…

a67afb2

…tion-gen/README.md Co-authored-by: Joe Betz <[email protected]>

Update keps/sig-api-machinery/5073-declarative-validation-with-valida…

308b805

…tion-gen/README.md Co-authored-by: Joe Betz <[email protected]>

resolving review feedback - update cross-field + ratcheting section

39cc5ea

aaron-prindle force-pushed the kep-5073-update-cross-field branch from 40bfe3a to 22e5865 Compare June 10, 2025 23:24

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jun 10, 2025

aaron-prindle force-pushed the kep-5073-update-cross-field branch 2 times, most recently from f4378f8 to 2342156 Compare June 10, 2025 23:39

addressing review comments

ff2a6da

aaron-prindle force-pushed the kep-5073-update-cross-field branch from 2342156 to ff2a6da Compare June 10, 2025 23:44

aaron-prindle mentioned this pull request Jun 11, 2025

KEP-5073: PRR update for v1.34 #5396

Merged

3 tasks

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jun 11, 2025

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jun 11, 2025

k8s-ci-robot merged commit 020fe69 into kubernetes:master Jun 11, 2025
2 of 4 checks passed

k8s-ci-robot added this to the v1.34 milestone Jun 11, 2025

jenshu mentioned this pull request Jul 22, 2025

Declarative Validation Of Kubernetes Native Types With validation-gen #5073

Open

24 tasks

KEP-5073: Declarative Validation: Explain and update document with cross-field validation information #5290

KEP-5073: Declarative Validation: Explain and update document with cross-field validation information #5290

Conversation

aaron-prindle commented May 8, 2025

Uh oh!

aaron-prindle commented May 8, 2025

Uh oh!

yongruilin May 8, 2025

Choose a reason for hiding this comment

Uh oh!

aaron-prindle May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jpbetz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

deads2k left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

deads2k May 15, 2025

Choose a reason for hiding this comment

Uh oh!

aaron-prindle May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

deads2k commented May 15, 2025

Uh oh!

aaron-prindle commented May 15, 2025

Uh oh!

deads2k commented Jun 11, 2025

Uh oh!

k8s-ci-robot commented Jun 11, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

aaron-prindle May 8, 2025 •

edited

Loading

aaron-prindle May 15, 2025 •

edited

Loading