Header mutation rules (proto)

config.common.mutation_rules.v3.HeaderMutationRules

[config.common.mutation_rules.v3.HeaderMutationRules proto]

The HeaderMutationRules structure specifies what headers may be manipulated by a processing filter. This set of rules makes it possible to control which modifications a filter may make.

By default, an external processing server may add, modify, or remove any header except for an “Envoy internal” header (which is typically denoted by an x-envoy prefix) or specific headers that may affect further filter processing:

host
:authority
:scheme
:method

Every attempt to add, change, append, or remove a header will be tested against the rules here. Disallowed header mutations will be ignored unless disallow_is_error is set to true.

Attempts to remove headers are further constrained – regardless of the settings, system-defined headers (that start with :) and the host header may never be removed.

In addition, a counter will be incremented whenever a mutation is rejected. In the ext_proc filter, that counter is named rejected_header_mutations.

{
  "allow_all_routing": {...},
  "allow_envoy": {...},
  "disallow_system": {...},
  "disallow_all": {...},
  "allow_expression": {...},
  "disallow_expression": {...},
  "disallow_is_error": {...}
}

allow_all_routing: (BoolValue) By default, certain headers that could affect processing of subsequent filters or request routing cannot be modified. These headers are host, :authority, :scheme, and :method. Setting this parameter to true allows these headers to be modified as well.

allow_envoy: (BoolValue) If true, allow modification of envoy internal headers. By default, these start with x-envoy but this may be overridden in the Bootstrap configuration using the header_prefix field. Default is false.

disallow_system: (BoolValue) If true, prevent modification of any system header, defined as a header that starts with a : character, regardless of any other settings. A processing server may still override the :status of an HTTP response using an ImmediateResponse message. Default is false.

disallow_all: (BoolValue) If true, prevent modifications of all header values, regardless of any other settings. A processing server may still override the :status of an HTTP response using an ImmediateResponse message. Default is false.

allow_expression: (type.matcher.v3.RegexMatcher) If set, specifically allow any header that matches this regular expression. This overrides all other settings except for disallow_expression.

disallow_expression: (type.matcher.v3.RegexMatcher) If set, specifically disallow any header that matches this regular expression regardless of any other settings.

disallow_is_error: (BoolValue) If true, and if the rules in this list cause a header mutation to be disallowed, then the filter using this configuration will terminate the request with a 500 error. In addition, regardless of the setting of this parameter, any attempt to set, add, or modify a disallowed header will cause the rejected_header_mutations counter to be incremented. Default is false.

config.common.mutation_rules.v3.HeaderMutation

[config.common.mutation_rules.v3.HeaderMutation proto]

The HeaderMutation structure specifies an action that may be taken on HTTP headers.

{
  "remove": ...,
  "append": {...},
  "remove_on_match": {...}
}

remove

(string) Remove the specified header if it exists.

Precisely one of remove, append, remove_on_match must be set.

append

(config.core.v3.HeaderValueOption) Append new header by the specified HeaderValueOption.

Precisely one of remove, append, remove_on_match must be set.

remove_on_match

(config.common.mutation_rules.v3.HeaderMutation.RemoveOnMatch) Remove the header if the key matches the specified string matcher.

Precisely one of remove, append, remove_on_match must be set.

config.common.mutation_rules.v3.HeaderMutation.RemoveOnMatch

[config.common.mutation_rules.v3.HeaderMutation.RemoveOnMatch proto]

{
  "key_matcher": {...}
}

key_matcher: (type.matcher.v3.StringMatcher, REQUIRED) A string matcher that will be applied to the header key. If the header key matches, the header will be removed.