Envoy Header-To-Metadata Filter

  • This filter should be configured with the type URL type.googleapis.com/envoy.extensions.filters.network.thrift_proxy.filters.header_to_metadata.v3.HeaderToMetadata.

  • v3 API reference

This filter is configured with rules that will be matched against requests. Each rule has either a header and can be triggered either when the header is present or missing.

When a rule is triggered, dynamic metadata will be added based on the configuration of the rule. If the header is present, it’s value is extracted and used along with the specified key as metadata. If the header is missing, on missing case is triggered and the value specified is used for adding metadata.

The metadata can then be used for load balancing decisions, consumed from logs, etc.

A typical use case for this filter is to dynamically match requests with load balancer subsets. For this, a given header’s value would be extracted and attached to the request as dynamic metadata which would then be used to match a subset of endpoints.

Example

A sample filter configuration to route traffic to endpoints based on the presence or absence of a version header could be:

header-to-metadata-filter.yaml
20          thrift_filters:
21          - name: envoy.filters.thrift.header_to_metadata
22            typed_config:
23              "@type": type.googleapis.com/envoy.extensions.filters.network.thrift_proxy.filters.header_to_metadata.v3.HeaderToMetadata
24              request_rules:
25              - header: x-version
26                on_present:
27                  metadata_namespace: envoy.lb
28                  key: version
29                  type: STRING
30                on_missing:
31                  metadata_namespace: envoy.lb
32                  key: default
33                  value: 'true'
34                  type: STRING
35                remove: false

A corresponding upstream cluster configuration could be:

header-to-metadata-filter.yaml
37  clusters:
38  - name: versioned-cluster
39    type: STRICT_DNS
40    lb_policy: ROUND_ROBIN
41    lb_subset_config:
42      fallback_policy: NO_FALLBACK
43      subset_selectors:
44        - keys:
45            - default
46        - keys:
47            - version

This would then allow requests with the x-version header set to be matched against endpoints with the corresponding version. Whereas requests with that header missing would be matched with the default endpoints.

If the header’s value needs to be transformed before it’s added to the request as dynamic metadata, this filter supports regex matching and substitution:

header-to-metadata-filter-regex-substitution.yaml
20          thrift_filters:
21          - name: envoy.filters.thrift.header_to_metadata
22            typed_config:
23              "@type": type.googleapis.com/envoy.extensions.filters.network.thrift_proxy.filters.header_to_metadata.v3.HeaderToMetadata
24              request_rules:
25              - header: x-version
26                on_present:
27                  metadata_namespace: envoy.lb
28                  key: cluster
29                  regex_value_rewrite:
30                    pattern:
31                      regex: "^/(cluster[\\d\\w-]+)/?.*$"
32                    substitution: "\\1"

Statistics

Currently, this filter generates no statistics.