Skip to content

Add gateway:util:excludeFromCRD comments for complex CEL validations - #4714

Merged
k8s-ci-robot merged 1 commit into
kubernetes-sigs:mainfrom
AndrewCharlesHay:add-gateway-internal-comment-tag
Apr 14, 2026
Merged

k8s-ci-robot merged 1 commit into
kubernetes-sigs:mainfrom
AndrewCharlesHay:add-gateway-internal-comment-tag

Conversation

@AndrewCharlesHay

Copy link
Copy Markdown

What type of PR is this?
/kind cleanup
/kind documentation

What this PR does / why we need it:

Introduces a <gateway:internal-comment> tag to the CRD generator that lets developers embed plain-English explanations for complex CEL validation rules directly in Go source. Tagged blocks are stripped from the generated CRDs and never appear in the API specification — they exist solely to help future maintainers understand the logic.

The tag works similarly to <gateway:util:excludeFromCRD> but is semantically distinct: excludeFromCRD is for implementor-facing notes that belong in Go docs but not CRDs, while internal-comment is specifically for developer-facing rationale on validation rules.

Uses the new tag to document three sets of notably complex rules:

  1. CommonRouteSpec.ParentRefs (shared_types.go): four rules (2 standard, 2 experimental) enforcing that when the same parent is referenced more than once, every reference must carry a distinct, non-empty sectionName (and optionally port). The CEL __namespace__ field quirk and the exists_one uniqueness pattern are now explained inline.

  2. BackendTLSPolicySpec.TargetRefs (backendtlspolicy_types.go): two analogous rules for target references, with a note explaining why namespace is not checked (same-namespace-only targets).

  3. HTTPRouteSpec.Rules (httproute_types.go): the manually-unrolled 16-term sum rule — necessary because CEL lacks aggregate functions — now has a comment explaining why the loop is written the way it is.

Which issue(s) this PR fixes:
Fixes #2325

Does this PR introduce a user-facing change?:

NONE

Additional context:

The <gateway:internal-comment> block is processed in formatDescription after XValidation extraction, so it has no effect on validation rule generation. The generated CRD YAML files are unchanged by this PR.

@k8s-ci-robot k8s-ci-robot added release-note-none Denotes a PR that doesn't merit a release note. do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. kind/cleanup Categorizes issue or PR as related to cleaning up code, process, or technical debt. kind/documentation Categorizes issue or PR as related to documentation. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Mar 24, 2026
@k8s-ci-robot k8s-ci-robot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Mar 24, 2026
@AndrewCharlesHay
AndrewCharlesHay force-pushed the add-gateway-internal-comment-tag branch from 9fb2f72 to 3eeb979 Compare March 25, 2026 13:26
@AndrewCharlesHay

Copy link
Copy Markdown
Author

/retest

@AndrewCharlesHay AndrewCharlesHay changed the title Add <gateway:internal-comment> tag for documenting complex CEL validations Add gateway:internal-comment tag for documenting complex CEL validations Mar 25, 2026
@AndrewCharlesHay

Copy link
Copy Markdown
Author

/retest

@AndrewCharlesHay
AndrewCharlesHay force-pushed the add-gateway-internal-comment-tag branch from 3eeb979 to 35073b9 Compare March 26, 2026 15:50
@k8s-ci-robot k8s-ci-robot removed the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label Mar 26, 2026

@snorwin snorwin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should reuse <gateway:util:excludeFromCRD> for CEL descriptions as well, there is no need to introduce a second annotation serving the same purpose.

@rikatz

rikatz commented Apr 6, 2026

Copy link
Copy Markdown
Member

+1 to Norwin comment, we should stick with <gateway:util:excludeFromCRD>

@AndrewCharlesHay
AndrewCharlesHay force-pushed the add-gateway-internal-comment-tag branch from 35073b9 to ec07464 Compare April 6, 2026 22:09
@AndrewCharlesHay

Copy link
Copy Markdown
Author

Thanks for the feedback — replaced all <gateway:internal-comment> tags with the existing <gateway:util:excludeFromCRD> tag and removed the redundant generator block. Same behavior, no new machinery needed.

// The rule enforces that the total number of matches across all rules stays below
// the per-route limit of 128, even though individual rules and matches are each
// capped higher (16 rules × 64 matches = 1024 theoretical maximum).
// </gateway:util:excludeFromCRD>

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO this comment is more complex than the CEL itself, which defeats its purpose (the same applies to the other comments as well).

I would keep it much shorter:

// Validates that the total number of matches across all rules does not exceed 128.
// CEL does not support aggregate functions like sum() over lists, so each of the
// (up to 16) rules is checked individually and their match counts are summed explicitly.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I think that one is a clearer. I recommend swapping this out.

@AndrewCharlesHay
AndrewCharlesHay force-pushed the add-gateway-internal-comment-tag branch from ec07464 to 9fb1a67 Compare April 7, 2026 15:42
@AndrewCharlesHay

Copy link
Copy Markdown
Author

/retest

@youngnick

Copy link
Copy Markdown
Contributor

This LGTM aside from @snorwin's recommended changes, so I'll approve.

Nice work, thanks @AndrewCharlesHay.

/approve

@k8s-ci-robot k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Apr 10, 2026
@AndrewCharlesHay
AndrewCharlesHay force-pushed the add-gateway-internal-comment-tag branch from 9fb1a67 to bfb126b Compare April 10, 2026 18:11
@AndrewCharlesHay AndrewCharlesHay changed the title Add gateway:internal-comment tag for documenting complex CEL validations Add gateway:util:excludeFromCRD comments for complex CEL validations Apr 10, 2026
@linux-foundation-easycla

linux-foundation-easycla Bot commented Apr 10, 2026 •

Copy link
Copy Markdown

CLA Signed

The committers listed above are authorized under a signed CLA.

  • ✅ login: AndrewCharlesHay / name: Andrew Hay (6a93e9f)

@k8s-ci-robot k8s-ci-robot added cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. and removed cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Apr 10, 2026
@youngnick

Copy link
Copy Markdown
Contributor

Sigh, I missed the Co-Authored-By. @AndrewCharlesHay, unfortunately the Kubernetes project as a whole cannot accept commits that are co-authored by an LLM. Commits must only be authored by a human, and you need to be confident that your name is attached to this change. If that is the case, please remove the Co-Authored-By from your commit message if you wish this to be merged.

…tions

Add concise documentation comments for complex CEL validation rules using
the existing gateway:util:excludeFromCRD tag so they are excluded from
generated CRD output. Comments explain what each CEL rule validates
without over-explaining the implementation.

Signed-off-by: Andrew Hay <andrew.hay@benchmarkanalytics.com>
@AndrewCharlesHay
AndrewCharlesHay force-pushed the add-gateway-internal-comment-tag branch from bfb126b to 6a93e9f Compare April 13, 2026 18:58
@k8s-ci-robot k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. and removed cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. labels Apr 13, 2026
@AndrewCharlesHay

Copy link
Copy Markdown
Author

Sigh, I missed the Co-Authored-By. @AndrewCharlesHay, unfortunately the Kubernetes project as a whole cannot accept commits that are co-authored by an LLM. Commits must only be authored by a human, and you need to be confident that your name is attached to this change. If that is the case, please remove the Co-Authored-By from your commit message if you wish this to be merged.

@youngnick Sorry I just used Claude to write the commit message. It has been updated

@snorwin snorwin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@AndrewCharlesHay thanks, nice work.

/lgtm

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 14, 2026
@k8s-ci-robot

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: AndrewCharlesHay, snorwin, youngnick

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

The pull request process is described here

Details Needs approval from an approver in each of these files:

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
k8s-ci-robot merged commit 410c88f into kubernetes-sigs:main Apr 14, 2026
20 checks passed
@AndrewCharlesHay
AndrewCharlesHay deleted the add-gateway-internal-comment-tag branch April 14, 2026 15:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/cleanup Categorizes issue or PR as related to cleaning up code, process, or technical debt. kind/documentation Categorizes issue or PR as related to documentation. lgtm "Looks good to me", indicates that a PR is ready to be merged. release-note-none Denotes a PR that doesn't merit a release note. size/M Denotes a PR that changes 30-99 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

TODO: Have an internal in-code documentation of CEL validations for parentRefs

5 participants