Skip to main content

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.
The filter runs in the workload’s inbound sidecar. It only changes traffic that enters the workload, never traffic the workload sends out.

Header Mutation Configuration

Header mutation is configured in the Workload or GVC spec.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 in request_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 :path or :authority.
  • host.
  • In append.header.value, an empty string, line breaks (CR or LF), and NUL characters.
The API also rejects a rule that sets both 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 the http 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.
Always set priority on both filters. When two filters have the same priority, or neither has one, their order depends on the order they are listed in, which can change when GVC and workload filters are merged.
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

An ext_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 sets x-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. Use excludedWorkloads to leave out specific workloads.