docs: align TrafficPolicy attachment docs with per-route settings#14378
Merged
davidjumani merged 4 commits intoJul 13, 2026
Merged
Conversation
A TrafficPolicy targeting a Gateway HTTP listener section attaches at the Envoy virtual-host level. Timeouts (and other route-action-level settings) are only applied per route, so they were silently dropped for such policies even though the policy reported as Accepted. HTTPS listener and whole-Gateway targeting were unaffected since they attach at the RouteConfiguration level. Generalize ApplyVhostPlugin to apply the full per-route settings to every route in the vhost via a shared applyPerRouteSettings helper, mirroring applyGatewayLevelPerRouteSettings. The existing 'only set if not already set' guards preserve merge precedence. Add gateway translator tests for TrafficPolicy timeout targeting the whole Gateway, an HTTP listener, and an HTTPS listener. Signed-off-by: omar <[email protected]>
Following kgateway-dev#14374, TrafficPolicy timeouts (and other route-action-level settings) now take effect when a policy attaches at a Gateway or Gateway listener section, not just an HTTPRoute. Update the API docs to match and reconcile the CEL validations: - Timeouts doc: applicable to HTTPRoutes and Gateways (including per-listener sectionName), with route-level precedence noted. - Retry doc: applicable to HTTPRoutes, Gateways, Gateway listeners, and ListenerSets, with route-level precedence noted. - Drop the retry sectionName CEL rules so whole-Gateway retry is admittable, matching timeouts and the documented behavior. - Add a urlRewrite HTTPRoute-only CEL rule (mirroring autoHostRewrite) so the documented 'HTTPRoute targets only' contract is enforced. - Update apivalidation e2e cases accordingly. Signed-off-by: omar <[email protected]>
gateway-bot
added
kind/documentation
kind/fix
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates TrafficPolicy’s API documentation and admission validations to match the actual attachment/precedence behavior (Gateway / listener vs per-route), and adjusts validation test coverage accordingly. It also includes translator/plugin changes and goldens that exercise/enable Gateway and listener-level timeout behavior (stacked on #14374 as noted in the PR description).
Changes:
- Update TrafficPolicy
timeoutsandretrydocstrings/CRD descriptions to reflect applicability at HTTPRoute and Gateway (including listenersectionName) with route-level precedence. - Relax retry admission by removing CEL rules that previously required
sectionNamewhen targetingGateway; add a CEL rule enforcingurlRewriteas HTTPRoute-only. - Update e2e API validation cases and add gateway translator golden tests for whole-Gateway and per-listener timeout targeting.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| test/e2e/tests/apivalidation/apivalidation.go | Updates validation cases: adds urlRewrite invalid-target rejection and changes retry sectionName expectations. |
| api/v1alpha1/kgateway/traffic_policy_types.go | Updates TrafficPolicy field docs and adds/removes CEL validations (urlRewrite HTTPRoute-only; drops retry sectionName rules). |
| install/helm/kgateway-crds/templates/gateway.kgateway.dev_trafficpolicies.yaml | Regenerated/updated CRD schema docs and CEL validations matching the API changes. |
| pkg/kgateway/extensions2/plugins/trafficpolicy/traffic_policy_plugin.go | Refactors per-route application into a helper and applies per-route settings for vhost-attached policies. |
| pkg/kgateway/translator/gateway/gateway_translator_test.go | Adds translator test cases covering timeout attachment at whole-Gateway and listener section levels. |
| pkg/kgateway/translator/gateway/testutils/inputs/traffic-policy/timeout-gateway-whole.yaml | New input fixture for whole-Gateway timeout behavior. |
| pkg/kgateway/translator/gateway/testutils/inputs/traffic-policy/timeout-gateway-http-listener.yaml | New input fixture for HTTP listener timeout targeting. |
| pkg/kgateway/translator/gateway/testutils/inputs/traffic-policy/timeout-gateway-https-listener.yaml | New input fixture for HTTPS listener timeout targeting. |
| pkg/kgateway/translator/gateway/testutils/outputs/traffic-policy/timeout-gateway-whole.yaml | New golden output validating whole-Gateway timeouts are emitted on all covered routes. |
| pkg/kgateway/translator/gateway/testutils/outputs/traffic-policy/timeout-gateway-http-listener.yaml | New golden output validating HTTP-listener-only timeout emission. |
| pkg/kgateway/translator/gateway/testutils/outputs/traffic-policy/timeout-gateway-https-listener.yaml | New golden output validating HTTPS-listener-only timeout emission. |
Comment on lines
+395
to
400
| for _, route := range routes { | ||
| if route.GetRoute() == nil { | ||
| continue | ||
| } | ||
| p.handlePerRoutePolicies(spec, route) | ||
| } |
| // specific TrafficPolicy or a builtin HTTPRoute policy) fully overrides the | ||
| // one applied here, and the "only set if not already set" guards in | ||
| // handlePerRoutePolicies keep that precedence explicit. | ||
| p.applyPerRouteSettings(policy.spec, out.Routes) |
Comment on lines
+108
to
+109
| // covers; a route-level timeout (from a more specific TrafficPolicy or the | ||
| // built-in HTTPRoute timeouts) takes precedence. |
Comment on lines
+117
to
+118
| // covers; a route-level retry policy (from a more specific TrafficPolicy or the | ||
| // built-in HTTPRoute retry) takes precedence. |
puertomontt
force-pushed
the
trafficpolicy-attachment-docs
branch
from
July 9, 2026 18:31
86c22e0 to
3c5445e
Compare
davidjumani
approved these changes
Jul 13, 2026
…trafficpolicy-attachment-docs Signed-off-by: omar <[email protected]>
davidjumani
approved these changes
Jul 13, 2026
davidjumani
enabled auto-merge
July 13, 2026 15:56
Signed-off-by: omar <[email protected]>
davidjumani
approved these changes
Jul 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Follow-up to #14374. That PR made TrafficPolicy
timeouts(and the otherroute-action-level settings) take effect when a policy attaches at a Gateway or
a Gateway listener section, not just at an HTTPRoute. This PR updates the API
documentation to match that behavior and reconciles the CEL validations that
had drifted from it:
(including individual Gateway listeners via
sectionName), with route-levelprecedence noted. Previously it claimed HTTPRoute-only.
listeners, and ListenerSets, with route-level precedence noted.
sectionNameCEL rules, so a retry policy may target awhole Gateway (no
sectionName) and be admitted — matchingtimeoutsand thebehavior delivered by apply TrafficPolicy retry per route instead of per vhost #14360/fix: apply TrafficPolicy timeouts per route at the vhost level #14374. Relaxing validation is non-breaking.
urlRewriteHTTPRoute-only CEL rule (mirroringautoHostRewrite),so the already-documented "only honored for HTTPRoute targets" contract is
actually enforced at admission rather than silently applying gateway-wide.
apivalidatione2e cases: remove the two now-obsolete retrysectionNamerejection cases, add a positive case (whole-Gateway retry isadmitted), and add a
urlRewrite-invalid-target rejection case.Note
Stacked on #14374 — the timeouts doc describes behavior that only exists once
that PR merges. Please merge #14374 first; this branch will then contain only
its own changes.
Change Type
/kind documentation
/kind fix
Changelog