*: Respect route replacement mode in TrafficPolicy plugin

[timflannagan]

Description

This is the initial PR that implements the route replacement EP. These changes focus on proactively catching structurally valid but semantically invalid configurations that Envoy would NACK at runtime.

From the 1.x APIs, the transformation policy type is an excellent example where this type of guardrail is critical. While a policy might be structurally valid (correct YAML, valid fields), it could contain semantically invalid configurations like:

• Malformed template expressions
• Template references to non-existent headers or variables
• Invalid body transformations that would produce malformed JSON/XML

The TP plugin has been updated to perform additional validation checks depending on the route replacement mode that's been configured for the KG installation:

• PGV validation: Runs in standard mode, performs quick validation of Envoy configuration types performs basic structural and semantic validation. This short circuits expensive xDS validation when basic issues are found, such as invalid header values or malformed template syntax.
• xDS validation (via Envoy validate mode): Runs in strict mode and controls whether the plugin will convert Envoy types stored in the IR into a partial bootstrap config and passes this to Envoy in validate mode. This detects potential NACKs before they happen at runtime and catches complex semantic issues like invalid transformations.

Whenever either of these validation checks fail, the route translator replaces the invalid route with a 500 direct response action. Previously, errors encountered during attached policy IR construction only influenced the policy status, which led to valid routes with invalid policy attached to them being pushed to the xDS snapshot and risk undefined behavior, fail open scenarios w.r.t security policy, or NACKs from the proxy. Now, the route translator has been updated to respect these policy IR errors, and trigger route replacement, in addition to the existing policy status.

Additionally, several new libraries have been introduced with these changes:

• Dedicated Envoy bootstrap library. Responsible for providing a generic partial bootstrap builder
• Abstracting envoy validate mode via an xDS validation library

These abstractions will be used in follow-up work that builds on top of this foundation and performs additional validation checks (e.g. CDS, RDS, etc.) that help prevent potential NACKs from reaching the fleet of managed proxies.

Change Type

/kind feature

Changelog

The TrafficPolicy plugin now respects the route replacement mode setting (`KGW_ROUTE_REPLACEMENT_MODE`). When in strict mode, the plugin performs additional validation to catch invalid configurations before they reach Envoy. Invalid policies that would cause Envoy to NACK at runtime (e.g. malformed templates) will now be replaced with a direct response (HTTP 500) and report clear status conditions. This prevents fail-open scenarios where invalid policies could allow unintended traffic.

Additional Notes

Fixes #11535

[Copilot]

Pull Request Overview

This PR adds strict route replacement validation by integrating a new Envoy bootstrap builder and validator, updating the TrafficPolicy plugin to respect strict mode, and adjusting route translation to replace invalid routes with a 500 direct response.

• Introduces pkg/xds/bootstrap for constructing partial bootstrap configs.
• Implements pkg/validator to validate Envoy configs via binary or Docker.
• Updates TrafficPolicy translation to perform XDS validation in strict mode and replace invalid routes.

Reviewed Changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pkg/xds/bootstrap/builder.go	Implements ConfigBuilder for partial Envoy bootstrap configs
pkg/validator/validator.go	Adds Validator interfaces for Envoy validation
pkg/pluginsdk/ir/iface.go	Extends TypedFilterConfigMap with ToAnyMap()
internal/kgateway/translator/irtranslator/route.go	Adds direct response body and error accumulation in routes
internal/kgateway/extensions2/plugins/trafficpolicy/validate.go	Invokes XDS validation in TrafficPolicy Validate
internal/kgateway/extensions2/plugins/trafficpolicy/traffic_policy_plugin.go	Applies strict mode validation based on settings

Comments suppressed due to low confidence (3)

pkg/xds/bootstrap/builder.go:1

• The file header comment references 'config.go' but this file is 'builder.go'. Please update the comment to match the file name.

// pkg/xds/bootstrap/config.go

pkg/xds/bootstrap/builder.go:2

• Consider adding unit tests for ConfigBuilder (e.g., Verify that Build() produces a valid partial bootstrap with expected listeners, routes, and clusters).

package bootstrap

pkg/validator/validator.go:1

• Consider adding unit tests or integration tests for both binaryValidator and dockerValidator to ensure they correctly detect valid and invalid configurations.

package validator

[timflannagan]

Note: I kept the status optimization outside of this PR. There's some weirdness that I still need to figure out locally, and was leading to policy status being wiped / incorrectly reported on controller restarts.

[timflannagan]

Added a TODO for this code. In it's current form, it's incredibly hard to read and has a high risk of maintenance burden without a proper refactor that will be done in a follow-up.

[timflannagan]

Note: this test case and the listener-level attachment are no-ops. Follow-up work needs to be done to the route translator to handle higher-level attachment w.r.t. triggering route replacement.

[timflannagan]

Existing test case moved to the route replacement suite. Related to route replacement where the validateEnvoyRoute function will return an error, and that error triggers the output Envoy route to use a direct response action.

[timflannagan]

Just to highlight this behavior - this mainly has impact on the listener-level config that's disabled by default:

diff --git a/internal/kgateway/translator/gateway/testutils/outputs/route-replacement/strict/invalid-csrf-regex-config-out.yaml b/internal/kgateway/translator/gateway/testutils/outputs/route-replacement/strict/invalid-csrf-regex-config-out.yaml
index 8526acb691..f042e46727 100644
--- a/internal/kgateway/translator/gateway/testutils/outputs/route-replacement/strict/invalid-csrf-regex-config-out.yaml
+++ b/internal/kgateway/translator/gateway/testutils/outputs/route-replacement/strict/invalid-csrf-regex-config-out.yaml
@@ -23,11 +23,6 @@ Listeners:
       typedConfig:
         '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
         httpFilters:
-        - name: envoy.filters.http.csrf
-          typedConfig:
-            '@type': type.googleapis.com/envoy.extensions.filters.http.csrf.v3.CsrfPolicy
-            filterEnabled:
-              defaultValue: {}

[timflannagan]

Existing error handling that I moved to this package. Open question on whether it's correct.

[timflannagan]

Unrelated to these changes, but updated this formatting to be consistent with the other ApplyForX signatures.

[timflannagan]

Follow-up work will expand this library to be able to perform RDS/CDS validation. Good enough for now though.

[lgadban]

is this just irrelevant at this point?

[timflannagan]

I think so, but tagged ashish to double check whether it's still relevant.

[lgadban]

so the strict mode even in translator tests will still call out to envoy binary for mode validate right?

[timflannagan]

If the envoy binary exists on the file system, yes, otherwise falls back to the docker image for validation.