Filter Chain (proto)

This extension has the qualified name envoy.filters.http.filter_chain

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension has an unknown security posture and should only be used in deployments where both the downstream and upstream are trusted.

Tip

This extension extends and can be used with the following extension category:

This extension must be configured with one of the following type URLs:

Filter Chain configuration overview.

Attention

This filter is specific to Envoy and is not supported in other xDS implementations.

extensions.filters.http.filter_chain.v3.FilterChainConfig

[extensions.filters.http.filter_chain.v3.FilterChainConfig proto]

Filter-level configuration for the filter chain filter. This filter acts as a wrapper that applies a configurable chain of HTTP filters to incoming requests.

When a request arrives the filter collects all active filter chains in order from least to most specific: default_filter_chain first, then any per-route chains ordered from the outermost scope (e.g. route configuration level) to the innermost scope (route level). Each filter in a less-specific chain is applied unless a more-specific chain contains a filter with the same name.

The final set of filters is applied in order from least to most specific, so that the least-specific filter runs first and the most-specific filter runs last. This allows more specific filters to override the behavior of less specific ones.

If no chains are found at all the filter passes through without modifying the request.

{
  "default_filter_chain": {...}
}
default_filter_chain

(extensions.filters.http.filter_chain.v3.FilterChain) Default filter chain to apply when processing every request.

This field is optional. When omitted the filter still participates in per-route override resolution.

extensions.filters.http.filter_chain.v3.FilterChainConfigPerRoute

[extensions.filters.http.filter_chain.v3.FilterChainConfigPerRoute proto]

Per-route configuration for the filter chain filter. This allows different filter chains to be applied on different routes.

Note

Only the initial route match is considered for filter chain selection. Subsequent internal route refreshes do not affect the filter chain applied to the request.

When multiple per-route configs exist along the route hierarchy (e.g. one at virtual-host level and one at route level) the same merge rules apply iteratively from least specific to most specific, so the most specific definition of any named filter always wins.

{
  "filter_chain": {...}
}
filter_chain

(extensions.filters.http.filter_chain.v3.FilterChain, REQUIRED) Filter chain to apply on this route. Must contain at least one filter.

Note

Not all HTTP filters are compatible to be used within this route level filter chain for now.

extensions.filters.http.filter_chain.v3.FilterChain

[extensions.filters.http.filter_chain.v3.FilterChain proto]

A filter chain is a list of HTTP filters that are applied in order. This message is used to define a reusable chain of filters.

{
  "filters": []
}
filters

(repeated config.core.v3.TypedExtensionConfig, REQUIRED) A list of HTTP filter configurations to be applied in order. Each filter in the chain will process the request/response in sequence. At least one filter must be specified.

Warning

Please do not configure the filter_chain filter itself or composite filter within this list recursively to avoid undefined behavior.

Note

It is possible to configure terminal filters (filters that do not expect next filter in the chain, e.g., envoy.filters.http.router) in the middle of the chain. However, use it with caution to avoid unexpected behavior.

Tip

This extension category has the following known extensions:

The following extensions are available in contrib images only: