Header Mutation Overview
The Envoy header mutation filter changes the HTTP headers on requests that reach a workload and on the responses it sends back. It can:- Remove a header that a client sent, so the client cannot forge headers that your application or a later filter trusts.
- Add a header, or overwrite one that is already there.
Header Mutation Configuration
Header mutation is configured in the Workload or GVCspec.sidecar.envoy.http filters array. When it is configured on the GVC, it applies to every workload in the GVC.
Header Mutation Rules
Each item inrequest_mutations or response_mutations sets exactly one of remove or append.
Header Name Validation
A header name the sidecar cannot load would break all inbound traffic to the workload, so the API rejects these when you save the spec:- Names that are not lowercase, or that contain characters not allowed in an HTTP header name, such as spaces.
- Pseudo-headers such as
:pathor:authority. host.- In
append.header.value, an empty string, line breaks (CR or LF), and NUL characters.
remove and append, or neither, and a rule that sets both the deprecated append boolean and append_action inside append.
When a spec is rejected, the error names the filter’s position in the http array and says it does not match any of the allowed types, for example "http[0]" does not match any of the allowed types.
Only
remove and append rules are supported. The other HeaderMutation options (remove_on_match, query_parameter_mutations, trailer mutations, most_specific_header_mutations_wins, and per-route configuration) are not available.Header Mutation Filter Ordering
The sidecar collects thehttp filters defined on the GVC and on the workload, sorts them by priority from lowest to highest, and runs them in that order. To strip a header before another filter reads it, give the header mutation filter the lower priority.
Filters you add always run after the platform’s built-in external authorization (configured through the workload’s firewall). A header mutation filter can therefore run before an ext_authz filter that you define in sidecar.envoy.http, but never before the platform’s own one.
Header Mutation Examples
Strip Client-Supplied Headers Before Your Own ext_authz
Anext_authz filter with failure_mode_allow: true lets requests through when the authorization service cannot be reached. With failure_mode_allow_header_add: true, it adds the x-envoy-auth-failure-mode-allowed header to those requests, so the application knows that authorization was skipped.
A client can send that header itself, or any other header your application trusts. The header mutation filter below runs first (priority: 10) and removes those headers. Only the ext_authz filter (priority: 20) can then add them. This matters on the success path too: when authorization succeeds, ext_authz does not touch x-envoy-auth-failure-mode-allowed, so a copy the client sent would otherwise reach the application.
Set and Remove Request and Response Headers
This filter setsx-request-source to edge on every request, replacing any value the client sent. It also removes the server header from responses and adds x-frame-options to a response that does not already have it.
Apply Header Mutation to a Whole GVC
Set the same filter on the GVC to apply it to every workload in the GVC. UseexcludedWorkloads to leave out specific workloads.
Related Header Settings
- To accept or reject requests based on their headers, without changing them, use the inbound HTTP header filter.
- To validate JWTs and copy their claims into request headers, see JWT Authentication.