Listener filters

Envoy’s listener filters may be used to manipulate connection metadata.

The main purpose of listener filters are to make adding further system integration functions easier by not requiring changes to Envoy core functionality, and also to make interaction between multiple such features more explicit.

The API for listener filters is relatively simple since ultimately these filters operate on newly accepted sockets.

Filters in the chain can stop and subsequently continue iteration to further filters. This allows for more complex scenarios such as calling a rate limiting service, etc.

Envoy includes several listener filters that are documented in this architecture overview as well as the configuration reference.

Filter chains

Filter chain match

Network filters are chained in an ordered list of FilterChain.

Each listener can have multiple FilterChain and an optional default_filter_chain.

Upon receiving a request, the FilterChain with the most specific match criteria is used.

If no matching FilterChain is found, the default filter chain will be used to serve the request, where configured, otherwise the connection will be closed.

Filter chain only update

Filter chains can be updated independently.

Upon listener config update, if the listener manager determines that the listener update is a filter chain only update, the listener update will be executed by adding, updating and removing filter chains.

The connections owned by these destroying filter chains will be drained as described here.

If the new filter chain and the old filter chain is protobuf message equivalent, the corresponding filter chain runtime info survives. The connections owned by the survived filter chains remain open.

Not all the listener config updates can be executed by filter chain update. For example, if the listener metadata is updated within the new listener config, the new metadata must be picked up by the new filter chains. In this case, the entire listener is drained and updated.

Network (L3/L4) filters

Network level (L3/L4) filters form the core of Envoy connection handling. The filter API allows for different sets of filters to be mixed and matched and attached to a given listener. There are three different types of network filters:

Read

Read filters are invoked when Envoy receives data from a downstream connection.

Write

Write filters are invoked when Envoy is about to send data to a downstream connection.

Read/Write

Read/Write filters are invoked both when Envoy receives data from a downstream connection and when it is about to send data to a downstream connection.

The API for network level filters is relatively simple since ultimately the filters operate on raw bytes and a small number of connection events (e.g., TLS handshake complete, connection disconnected locally or remotely, etc.).

Filters in the chain can stop and subsequently continue iteration to further filters. This allows for more complex scenarios such as calling a rate limiting service, etc.

Network level filters can also share state (static and dynamic) among themselves within the context of a single downstream connection. Refer to data sharing between filters for more details.

Tip

See the listener configuration and protobuf sections for reference documentation.

See here for included filters.

TCP proxy filter

The TCP proxy filter performs basic 1:1 network connection proxy between downstream clients and upstream clusters.

It can be used by itself as an stunnel replacement, or in conjunction with other filters such as the MongoDB filter or the rate limit filter.

The TCP proxy filter will respect the connection limits imposed by each upstream cluster’s global resource manager. The TCP proxy filter checks with the upstream cluster’s resource manager if it can create a connection without going over that cluster’s maximum number of connections, if it can’t the TCP proxy will not make the connection.

Tip

See the TCP proxy configuration and protobuf sections for reference documentation.

UDP proxy filter

Envoy supports UDP proxy via the UDP proxy listener filter.

DNS filter

Envoy supports responding to DNS requests by configuring a UDP listener DNS Filter.

The DNS filter supports responding to forward queries for A and AAAA records.

The answers are discovered from statically configured resources, clusters, or external DNS servers.

The filter will return DNS responses up to to 512 bytes. If domains are configured with multiple addresses, or clusters with multiple endpoints, Envoy will return each discovered address up to the aforementioned size limit.

Connection limiting filter

Envoy supports local (non-distributed) connection limiting of L4 connections via the Connection limit filter and runtime connection limiting via the Runtime listener connection limit.