Repository navigation
Add gateway:util:excludeFromCRD comments for complex CEL validations - #4714
Conversation
9fb2f72 to
3eeb979
Compare
|
/retest |
gateway:internal-comment tag for documenting complex CEL validations
|
/retest |
3eeb979 to
35073b9
Compare
snorwin
left a comment
There was a problem hiding this comment.
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.
|
+1 to Norwin comment, we should stick with |
35073b9 to
ec07464
Compare
|
Thanks for the feedback — replaced all |
| // 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> |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Yeah, I think that one is a clearer. I recommend swapping this out.
ec07464 to
9fb1a67
Compare
|
/retest |
|
This LGTM aside from @snorwin's recommended changes, so I'll approve. Nice work, thanks @AndrewCharlesHay. /approve |
9fb1a67 to
bfb126b
Compare
gateway:internal-comment tag for documenting complex CEL validations|
|
|
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>
bfb126b to
6a93e9f
Compare
@youngnick Sorry I just used Claude to write the commit message. It has been updated |
snorwin
left a comment
There was a problem hiding this comment.
@AndrewCharlesHay thanks, nice work.
/lgtm
|
[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 DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
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:excludeFromCRDis for implementor-facing notes that belong in Go docs but not CRDs, whileinternal-commentis specifically for developer-facing rationale on validation rules.Uses the new tag to document three sets of notably complex rules:
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-emptysectionName(and optionallyport). The CEL__namespace__field quirk and theexists_oneuniqueness pattern are now explained inline.BackendTLSPolicySpec.TargetRefs(backendtlspolicy_types.go): two analogous rules for target references, with a note explaining why namespace is not checked (same-namespace-only targets).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?:
Additional context:
The
<gateway:internal-comment>block is processed informatDescriptionafter XValidation extraction, so it has no effect on validation rule generation. The generated CRD YAML files are unchanged by this PR.