Envoy Header-To-Metadata Filter
This filter should be configured with the type URL
type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config.
This filter is configured with rules that will be matched against requests and responses. Each rule has either a cookie or a header and can be triggered either when the header or cookie is present or missing.
When a rule is triggered, dynamic metadata will be added based on the configuration of the rule. If the header or cookie is present, it’s value is extracted and used along with the specified key as metadata. If the header or cookie 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:
25 http_filters:
26 - name: envoy.filters.http.header_to_metadata
27 typed_config:
28 "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config
29 request_rules:
30 - header: x-version
31 on_header_present:
32 metadata_namespace: envoy.lb
33 key: version
34 type: STRING
35 on_header_missing:
36 metadata_namespace: envoy.lb
37 key: default
38 value: "true"
39 type: STRING
40 remove: false
As with headers, the value of the specified cookie will be extracted from the request and added as metadata with the key specified. Removing a cookie when a rule matches is unsupported.
25 http_filters:
26 - name: envoy.filters.http.header_to_metadata
27 typed_config:
28 "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config
29 request_rules:
30 - cookie: cookie
31 on_header_present:
32 metadata_namespace: envoy.lb
33 key: version
34 type: STRING
35 on_header_missing:
36 metadata_namespace: envoy.lb
37 key: default
38 value: 'true'
39 type: STRING
40 remove: false
A corresponding upstream cluster configuration could be:
45 clusters:
46 - name: versioned-cluster
47 type: STRICT_DNS
48 lb_policy: ROUND_ROBIN
49 lb_subset_config:
50 fallback_policy: ANY_ENDPOINT
51 subset_selectors:
52 - keys:
53 - default
54 - keys:
55 - 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:
25 http_filters:
26 - name: envoy.filters.http.header_to_metadata
27 typed_config:
28 "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config
29 request_rules:
30 - header: ":path"
31 on_header_present:
32 metadata_namespace: envoy.lb
33 key: cluster
34 regex_value_rewrite:
35 pattern:
36 regex: "^/(cluster[\\d\\w-]+)/?.*$"
37 substitution: "\\1"
Note that this filter also supports per route configuration:
14 route_config:
15 name: local_route
16 virtual_hosts:
17 - name: local_service
18 domains:
19 - "*"
20 routes:
21 - match:
22 prefix: "/version-to-metadata"
23 route:
24 cluster: service
25 typed_per_filter_config:
26 envoy.filters.http.header_to_metadata:
27 "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config
28 request_rules:
29 - header: x-version
30 on_header_present:
31 metadata_namespace: envoy.lb
32 key: version
33 type: STRING
34 remove: false
35 - match:
36 prefix: "/"
37 route:
38 cluster: some_service
This can be used to either override the global configuration or if the global configuration is empty (no rules), it can be used to only enable the filter at a per route level.
Statistics
Currently, this filter generates no statistics.