early header mutations

[yuval-k]

Fixes #12940

Description

Early header mutations

Change Type

/kind feature

Changelog

Add earlyRequestHeaderModifier to HTTPListenerPolicy. this allows performing header modifications before a route is selected.

[Copilot]

Pull request overview

This PR adds support for early request header modification to the HTTPListenerPolicy resource, enabling header mutations to be applied before route selection occurs. This feature is particularly useful for security scenarios, such as ensuring that authentication headers cannot be spoofed by clients and are only added by authorized systems like ExternalAuth.

Key Changes

• Added earlyRequestHeaderModifier field to HTTPListenerPolicy API that accepts standard Gateway API HTTPHeaderFilter spec (add/set/remove operations)
• Introduced shared ConvertMutations utility function to eliminate code duplication between listener and route-level header mutation logic
• Configured Envoy's earlyHeaderMutationExtensions in the HttpConnectionManager to apply mutations before routing

Reviewed changes

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

Show a summary per file

File	Description
api/v1alpha1/http_listener_policy_types.go	Added EarlyRequestHeaderModifier field to API spec
install/helm/kgateway-crds/templates/gateway.kgateway.dev_httplistenerpolicies.yaml	Added CRD schema for early request header modifier field
api/v1alpha1/zz_generated.deepcopy.go	Generated deepcopy code for new field
internal/kgateway/extensions2/pluginutils/headers.go	New shared utility to convert Gateway API header filters to Envoy mutations
internal/kgateway/extensions2/plugins/trafficpolicy/header_modifiers.go	Refactored to use shared conversion utility
internal/kgateway/extensions2/plugins/httplistenerpolicy/httplistener_plugin.go	Implemented early header mutation support in plugin
internal/kgateway/extensions2/plugins/httplistenerpolicy/merge.go	Added merge logic for early header mutation extensions
test/e2e/features/http_listener_policy/types.go	Added manifest path for E2E test
test/e2e/features/http_listener_policy/suite.go	Added E2E test verifying route matching with early-added headers
test/e2e/features/http_listener_policy/testdata/http-listener-policy-early-header-route-match.yaml	Test manifest with route that requires header added by policy
internal/kgateway/translator/gateway/gateway_translator_test.go	Added translator test case for early header mutations
internal/kgateway/translator/gateway/testutils/inputs/httplistenerpolicy/early-header-mutation.yaml	Input test data with add/set/remove operations
internal/kgateway/translator/gateway/testutils/outputs/httplistenerpolicy/early-header-mutation.yaml	Expected Envoy configuration output

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The documentation mentions "ExternalAuthz" but the correct term appears to be "ExternalAuth" based on the comment. Consider using consistent terminology.

Suggested change

	// For example, if you use ExternalAuthz to add a header, you may want to remove it here, to make
	// For example, if you use ExternalAuth to add a header, you may want to remove it here, to make

[lgadban]

Just a couple of relatively minor things.
Would be nice to have a better API name but I can't really come up with anything.
LGTM otherwise though.

[lgadban]

it's borderline nit, but given the primary usecase we care about is sanitizing headers, would prefer a test that removes a header from the incoming request

[lgadban]

Suggested change

	// For example, if you use ExternalAuthz to add a header, you may want to remove it here, to make
	// sure it did not come from the client.
	// For example, if your external auth service adds a header, you should sanitize that header by removing it here,
	// to make sure it did not come from the client.

[lgadban]

Really just trying to get 'sanitize' somewhere in here.