feat(trafficpolicy): add configurable Envoy route stat_prefix support

[mihir-dixit2k27]

Description

Motivation: Operators have no way to correlate Kubernetes xRoute resources with Envoy route-level metrics — all routes share the same default stat_prefix.

What changed: Adds an opt-in statPrefix field to TrafficPolicy that sets RouteAction.stat_prefix in Envoy, enabling per-route metric namespacing. Supports template variable substitution (%NAMESPACE%, %NAME%, %RULE_NAME%) resolved at apply-time using live route context — the raw template is stored in the IR and substitution happens in handlePerRoutePolicies() via pCtx.In.Parent. If %RULE_NAME% is used on an unnamed rule, the literal token is preserved in the resolved string and a controller warning is logged.

Related issues: Fixes #13564

Change Type

/kind feature

Changelog

Add opt-in `statPrefix` field to `TrafficPolicy` CRD for per-xRoute Envoy route metric namespacing. Supports `%NAMESPACE%`, `%NAME%`, and `%RULE_NAME%` template variables resolved at translation time.

Additional Notes

• Kubebuilder validation pattern ^[a-zA-Z0-9_%]+$ (MaxLength=256) rejects invalid Envoy stat names at admission time, before they can reach the data plane.
• %RULE_NAME% is intentionally left as a literal string when the HTTPRoute rule has no name — empty-string substitution would silently corrupt metric names in production. A controller warning is logged to surface this to operators.
• Tests could not be run locally due to Go 1.26 unavailability in the restricted WSL environment; CI is the verification path.

[Copilot]

Pull request overview

Adds opt-in per-route Envoy stat_prefix configuration to TrafficPolicy so operators can correlate xRoute resources with route-level metrics, with template substitution based on live route context.

Changes:

• Introduces spec.statPrefix in TrafficPolicy CRD (with templating tokens) and wires it through IR construction + merge/equality/validation.
• Applies RouteAction.stat_prefix during route translation with %NAMESPACE%, %NAME%, %RULE_NAME% substitution and warning behavior for unnamed rules.
• Adds unit tests covering IR storage and apply-time substitution behavior.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pkg/kgateway/extensions2/plugins/trafficpolicy/traffic_policy_plugin.go	Applies the resolved stat_prefix to Envoy routes during per-route policy handling.
pkg/kgateway/extensions2/plugins/trafficpolicy/stat_prefix.go	Adds statPrefixIR and IR construction from the CRD field (stores raw template).
pkg/kgateway/extensions2/plugins/trafficpolicy/stat_prefix_test.go	Adds tests for equality/validation, IR construction, and apply-time substitution.
pkg/kgateway/extensions2/plugins/trafficpolicy/merge.go	Ensures statPrefix participates in TrafficPolicy merge behavior.
pkg/kgateway/extensions2/plugins/trafficpolicy/constructor.go	Constructs stat prefix IR during TrafficPolicy translation.
api/v1alpha1/kgateway/traffic_policy_types.go	Adds the statPrefix API field and schema validation markers/docs.
api/v1alpha1/kgateway/zz_generated.deepcopy.go	Updates autogenerated deepcopy logic for the new API types/fields.

Comments suppressed due to low confidence (1)

pkg/kgateway/extensions2/plugins/trafficpolicy/traffic_policy_plugin.go:685

• handlePerRoutePolicies only checks out.GetAction() == nil but then unconditionally uses out.GetRoute() as a *RouteAction. If the route action is a redirect/direct_response (i.e., GetAction()!=nil but GetRoute()==nil), setting action.StatPrefix will panic when statPrefix is configured. Add a guard that returns early when out.GetRoute() is nil (or only apply statPrefix when the action is a RouteAction).

	// A parent route rule with a delegated backend will not have RouteAction set
	if out.GetAction() == nil {
		return
	}

	action := out.GetRoute()

[josh-pritchard]

Thanks for the contribution. The unit tests look good but a change like this to plugins also requires translator tests that will result in new golden files that are representative of the new feature.

[josh-pritchard]

Make sure to run a make generate locally as your missing generated clients and CRDs from name change.

[mihir-dixit2k27]

Thanks for the thorough review and guidance @josh-pritchard ! I've addressed all the feedback in the latest commits:

Added CEL XValidation to statPrefixto strictly restrict % characters to only the predefined template tokens.
Swapped the unicode arrows for ASCII -> in the API documentation.
Added the suggested nil-pointer guard to statPrefixIR.Validate().
Added a gateway translator test case (traffic-policy/stat-prefix.yaml) with the expected structured Envoy proxy output.

(Note: I wasn't able to run make generate locally to update the generated CRDs/deepcopy files because my WSL environment is currently on Go 1.25, and this project now strictly requires Go 1.26. If it's easier, could a maintainer run the codegen update for me? Alternatively, I can update my environment to Go 1.26 and push the generated files later today—just let me know your preference!)