Well Known Filter State Objects

The following lists the filter state object keys used by the Envoy extensions to programmatically modify their behavior:

envoy.network.upstream_server_name

Sets the transport socket option to override the SNI in the upstream connections. Accepts a host name as a constructor, e.g. “lyft.com”.

envoy.network.application_protocols

Sets the transport socket option to override the ALPN list in the upstream connections. This setting takes precedence over the upstream cluster configuration. Accepts a comma-separated list of protocols as a constructor, e.g. “h2,http/1.1”.

envoy.network.upstream_subject_alt_names

Enables additional verification of the upstream peer certificate SAN names. Accepts a comma-separated list of SAN names as a constructor.

envoy.tcp_proxy.cluster

TCP proxy dynamic cluster name selection on a per-connection basis. Accepts a cluster name as a constructor.

envoy.udp_proxy.cluster

UDP proxy dynamic cluster name selection on a per-session basis. Accepts a cluster name as a constructor.

envoy.network.transport_socket.original_dst_address

Original destination cluster dynamic address selection. Accepts an IP:PORT string as a constructor. Fields:

ip: IP address value as a string;
port: port value as a number.

envoy.filters.listener.original_dst.local_ip

Original destination listener filter destination address selection for the internal listeners. Accepts an IP:PORT string as a constructor. Fields:

ip: IP address value as a string;
port: port value as a number.

envoy.filters.listener.original_dst.remote_ip

Original destination listener filter source address selection for the internal listeners. Accepts an IP:PORT string as a constructor. Fields:

ip: IP address value as a string;
port: port value as a number.

envoy.upstream.dynamic_host

Dynamic forward proxy upstream host override on a per-connection basis. Accepts a host string as a constructor.

envoy.upstream.dynamic_port

Dynamic forward proxy upstream port override on a per-connection basis. Accepts a port number string as a constructor.

envoy.tcp_proxy.disable_tunneling

TCP proxy tunneling override to disable tunneling on a per-connection bases. Accepts values “true” and “false”.

envoy.filters.network.http_connection_manager.local_reply_owner

Shared filter status for logging which filter config name in the HTTP filter chain sent the local reply.

envoy.network.transport_socket.http_11_proxy.info

Sets per-request HTTP/1.1 proxy information for upstream connections. This is used to inform the http_11_proxy transport socket of the proxy information for the upstream connection. Accepts a constructor string of the form "<target_host:port>,<proxy_ip:port>". If proxy_ip is an IPv6 address, it must use bracket notation (for example, [::1]:15002). For example: "example.com:443,127.0.0.1:15002" or "example.com:443,[::1]:15002".

envoy.tcp_proxy.per_connection_idle_timeout_ms

TCP proxy idle timeout duration override on a per-connection basis. Accepts a count of milliseconds number string as a constructor.

envoy.ratelimit.hits_addend

Rate Limit Hits Addend override on a per-route basis. Accepts a number string as a constructor.

envoy.geoip

Network GeoIP filter stores geolocation lookup results in this filter state object. The object contains fields for geographic data such as country, city, region, and ASN. Supports serialization for access logging and field-level access. Fields:

country: ISO country code;
city: city name;
region: ISO region code;
asn: autonomous system number;
anon: anonymization network check result (true or false);
anon_vpn: VPN check result (true or false);
anon_hosting: hosting provider check result (true or false);
anon_tor: TOR exit node check result (true or false);
anon_proxy: public proxy check result (true or false);
isp: ISP name;
apple_private_relay: iCloud Private Relay check result (true or false).

envoy.filters.http.mcp.request

MCP filter stores parsed MCP (Model Context Protocol) JSON-RPC request attributes when request_storage_mode is set to FILTER_STATE or DYNAMIC_METADATA_AND_FILTER_STATE. The object stores extracted fields from the parsed request.

envoy.network.network_namespace

Contains the value of the downstream connection’s Linux network namespace if it differs from the default.

envoy.network.upstream_bind_override.network_namespace

Allows overriding the network namespace on the upstream connections using the Linux network namespace local address selector extension. The object should serialize to the network namespace filepath, and the empty string value clears the network namespace. This object is expected to be shared from the downstream filters with the upstream connections.

envoy.tls.certificate_mappers.on_demand_secret

Allows overriding the certificate to use per-connection using the filter state certificate mapper.

envoy.tls.cert_validator.spiffe.workload_trust_domain

Specifies per-connection workload trust domain to be used in the SPIFFE certificate validator.

Filter state object factories

The following generic filter state factories can be used to create filter state objects via configuration with a factory lookup key.

envoy.string

A generic string object factory for creating filter state entries with custom key names. Use this as the factory_key when your object_key is a custom name not listed in this document.

Example configuration:

object_key: my.custom.key
factory_key: envoy.string
format_string:
  text_format_source:
    inline_string: "my-value"

This creates a filter state entry named my.custom.key containing the string my-value. The value can be accessed in access logs using %FILTER_STATE(my.custom.key)%.

envoy.hashable_string

Same as envoy.string but supports connection pool hashing when shared with the upstream. Please use with care as it can lead to significant increase in the number of upstream connections when used with HTTP upstreams.

envoy.network.ip

A factory to create IP addresses from IPv4 and IPv6 address strings.

Filter state object fields

The filter state object fields can be used in the format strings. For example, the following format string references the port number in the original destination cluster filter state object:

%FILTER_STATE(envoy.network.transport_socket.original_dst_address:FIELD:port)%