Set Metadata

  • This filter should be configured with the type URL type.googleapis.com/envoy.extensions.filters.http.set_metadata.v3.Config.

  • v3 API reference

The Set Metadata filter adds or updates dynamic metadata with static or dynamically formatted data. This filter is useful for attaching contextual information to requests that can be consumed by other filters, used for load balancing decisions, included in access logs, or utilized for routing decisions.

The filter supports both untyped metadata (using google.protobuf.Struct) and typed metadata (using google.protobuf.Any). Dynamic metadata values are updated according to specific merge rules that vary based on the value type and the allow_overwrite configuration.

Common use cases include:

  • Tagging requests with environment or service information for downstream processing.

  • Adding routing hints for load balancer subset selection.

  • Enriching access logs with additional context.

  • Storing computed values for use by subsequent filters in the chain.

Configuration

The filter can be configured with multiple metadata entries, each targeting a specific namespace. Each entry can contain either static values or use the deprecated legacy configuration format.

Metadata Merge Rules

Dynamic metadata values are updated with the following rules. If a key does not exist, it is copied into the current metadata. If the key exists, the following rules apply:

  • Typed metadata values: When typed_value is used, it will overwrite existing values if and only if allow_overwrite is set to true. Otherwise, the operation is skipped.

  • Untyped metadata values: When value is used and allow_overwrite is set to true, or when the deprecated value field is used, values are merged using the following scheme:

    • Different type values: The existing value is replaced entirely.

    • Scalar values (null, string, number, boolean): The existing value is replaced.

    • Lists: New values are appended to the existing list.

    • Structures: The merge rules are applied recursively to nested structures.

Merge Example

For instance, if the namespace already contains this structure:

myint: 1
mylist: ["a"]
mykey: ["val"]
mytags:
  tag0: 1

and the value to set is:

myint: 2
mylist: ["b","c"]
mykey: 1
mytags:
  tag1: 1

After applying this filter, the namespace will contain:

myint: 2
mylist: ["a","b","c"]
mykey: 1
mytags:
  tag0: 1
  tag1: 1

Configuration Examples

Basic Static Metadata

A simple configuration that adds static metadata to the envoy.lb namespace:

set-metadata-basic-static.yaml
29          - name: envoy.filters.http.set_metadata
30            typed_config:
31              "@type": type.googleapis.com/envoy.extensions.filters.http.set_metadata.v3.Config
32              metadata:
33              - metadata_namespace: envoy.lb
34                value:
35                  version: "v1.2.3"
36                  environment: "production"
37                  features:
38                  - "feature_a"
39                  - "feature_b"

Multiple Metadata Entries

Configuration with multiple metadata entries targeting different namespaces:

set-metadata-multiple-entries.yaml
29          - name: envoy.filters.http.set_metadata
30            typed_config:
31              "@type": type.googleapis.com/envoy.extensions.filters.http.set_metadata.v3.Config
32              metadata:
33              # Service identification metadata
34              - metadata_namespace: envoy.lb
35                allow_overwrite: true
36                value:
37                  service: "user-service"
38                  version: "v2.1.0"
39              # Request routing metadata
40              - metadata_namespace: envoy.filters.http.fault
41                allow_overwrite: true
42                value:
43                  upstream_cluster: "backend"
44                  retry_policy: "aggressive"

Typed Metadata Configuration

Configuration using typed metadata with google.protobuf.Any:

set-metadata-typed-configuration.yaml
29          - name: envoy.filters.http.set_metadata
30            typed_config:
31              "@type": type.googleapis.com/envoy.extensions.filters.http.set_metadata.v3.Config
32              metadata:
33              - metadata_namespace: custom.typed
34                allow_overwrite: true
35                typed_value:
36                  "@type": type.googleapis.com/envoy.extensions.filters.http.set_metadata.v3.Config
37                  metadata_namespace: nested_namespace
38                  value:
39                    custom_field: "typed_value"

Overwrite Control

Configuration demonstrating overwrite control behavior:

set-metadata-overwrite-control.yaml
29          - name: envoy.filters.http.set_metadata
30            typed_config:
31              "@type": type.googleapis.com/envoy.extensions.filters.http.set_metadata.v3.Config
32              metadata:
33              # First entry - will be set initially
34              - metadata_namespace: test.namespace
35                value:
36                  counter: 1
37                  list: ["first"]
38              # Second entry - will be ignored without allow_overwrite
39              - metadata_namespace: test.namespace
40                value:
41                  counter: 2
42                  list: ["second"]
43              # Third entry - will merge with allow_overwrite: true
44              - metadata_namespace: test.namespace
45                allow_overwrite: true
46                value:
47                  counter: 3
48                  list: ["third"]
49                  new_field: "added"

Note

In the above example, the final metadata will contain: counter: 3, list: ["first", "third"], and new_field: "added". The second entry is ignored because allow_overwrite is not set.

Statistics

The Set Metadata filter outputs statistics in the http.<stat_prefix>.set_metadata. namespace. The stat prefix comes from the owning HTTP connection manager.

Name

Type

Description

overwrite_denied

Counter

Total number of denied attempts to overwrite an existing metadata value when allow_overwrite is false