EnvoyFilter provides a mechanism to customize the Envoy
configuration generated by Istio Pilot. Use EnvoyFilter to modify
values for certain fields, add specific filters, or even add
entirely new listeners, clusters, etc. This feature must be used
with care, as incorrect configurations could potentially
destabilize the entire mesh. Unlike other Istio networking objects,
EnvoyFilters are additively applied. Any number of EnvoyFilters can
exist for a given workload in a specific namespace. The order of
application of these EnvoyFilters is as follows: all EnvoyFilters
in the config root
followed by all matching EnvoyFilters in the workload’s namespace.
NOTE 1: Some aspects of this API is deeply tied to the internal implementation in Istio networking subsystem as well as Envoy’s XDS API. While the EnvoyFilter API by itself will maintain backward compatibility, any envoy configuration provided through this mechanism should be carefully monitored across Istio proxy version upgrades, to ensure that deprecated fields are removed and replaced appropriately.
NOTE 2: When multiple EnvoyFilters are bound to the same workload in a given namespace, all patches will be processed sequentially in order of creation time. The behavior is undefined if multiple EnvoyFilter configurations conflict with each other.
NOTE 3: *_To apply an EnvoyFilter resource to all workloads (sidecars and gateways) in the system, define the resource in the config root namespace, without a workloadSelector.
The example below declares a global default EnvoyFilter resource in
the root namespace called
istio-config, that adds a custom
protocol filter on all sidecars in the system, for outbound port
9307. The filter should be added before the terminating tcp_proxy
filter to take effect. In addition, it sets a 30s idle timeout for
all HTTP connections in both gateays and sidecars.
namespace: istio-config # as defined in meshConfig resource.
- applyTo: NETWORK_FILTER
context: SIDECAR_OUTBOUND # will match outbound listeners in all sidecars
# This is the full filter config including the name and config or typed_config section.
- applyTo: NETWORK_FILTER # http connection manager is a filter in Envoy
# context omitted so that this applies to both sidecars and gateways
The following example enables Envoy’s Lua filter for all inbound HTTP calls arriving at service port 8080 of the reviews service pod with labels “app: reviews”, in the bookinfo namespace. The lua filter calls out to an external service internal.org.net:8888 that requires a special cluster definition in envoy. The cluster is also added to the sidecar as part of this configuration.
# The first patch adds the lua filter to the listener/http connection manager
- applyTo: HTTP_FILTER
value: # lua filter specification
-- Make an HTTP call to an upstream host with the following headers, body, and timeout.
local headers, body = request_handle:httpCall(
[":method"] = "POST",
[":path"] = "/acl",
[":authority"] = "internal.org.net"
# The second patch adds the cluster that is referenced by the lua code
# cds match is omitted as a new cluster is being added
- applyTo: CLUSTER
value: # cluster specification
The following example overwrites certain fields (HTTP idle timeout and X-Forward-For trusted hops) in the HTTP connection manager in a listener on the ingress gateway in istio-system namespace for the SNI host app.example.com:
- applyTo: NETWORK_FILTER # http connection manager is a filter in Envoy
EnvoyFilter provides a mechanism to customize the Envoy configuration generated by Istio Pilot.
One or more properties of the proxy to match on.
Conditions specified in ClusterMatch must be met for the patch to be applied to a cluster.
Conditions specified in RouteConfigurationMatch must be met for the patch to be applied to a route configuration object or a specific virtual host within the route configuration.
Conditions specified in a listener match must be met for the patch to be applied to a specific listener across all filter chains, or a specific filter chain inside the listener.
Patch specifies how the selected object should be modified.
One or more match conditions to be met before a patch is applied to the generated configuration for a given proxy.
Changes to be made to various envoy config objects.
Match a specific route inside a virtual host in a route configuration.
Match a specific virtual host inside a route configuration.
For listeners with multiple filter chains (e.g., inbound listeners on sidecars with permissive mTLS, gateway listeners with multiple SNI matches), the filter chain match can be used to select a specific filter chain to patch.
Conditions to match a specific filter within a filter chain.
Conditions to match a specific filter within another filter. This field is typically useful to match a HTTP filter inside the envoy.httpconnectionmanager network filter. This could also be applicable for thrift filters.
Action refers to the route action taken by Envoy when a http route matches.
All three route actions
Route traffic to a cluster / weighted clusters.
directly respond to a request with specific payload.
Operation denotes how the patch should be applied to the selected configuration.
Merge the provided config with the generated config using json merge semantics.
Add the provided config to an existing list (of listeners, clusters, virtual hosts, network filters, or http filters). This operation will be ignored when applyTo is set to ROUTECONFIGURATION, or HTTPROUTE.
Remove the selected object from the list (of listeners, clusters, virtual hosts, network filters, or http filters). Does not require a value to be specified. This operation will be ignored when applyTo is set to ROUTECONFIGURATION, or HTTPROUTE.
Insert operation on an array of named objects. This operation is typically useful only in the context of filters, where the order of filters matter. For clusters and virtual hosts, order of the element in the array does not matter. Insert before the selected filter or sub filter. If no filter is selected, the specified filter will be inserted at the front of the list.
Insert operation on an array of named objects. This operation is typically useful only in the context of filters, where the order of filters matter. For clusters and virtual hosts, order of the element in the array does not matter. Insert after the selected filter or sub filter. If no filter is selected, the specified filter will be inserted at the end of the list.
Insert operation on an array of named objects. This operation is typically useful only in the context of filters, where the order of filters matter. For clusters and virtual hosts, order of the element in the array does not matter. Insert first in the list based on the presence of selected filter or not. This is specifically useful when you want your filter first in the list based on a match condition specified in Match clause.
ApplyTo specifies where in the Envoy configuration, the given patch should be applied.
Applies the patch to the listener.
Applies the patch to the filter chain.
Applies the patch to the network filter chain, to modify an existing filter or add a new filter.
Applies the patch to the HTTP filter chain in the http connection manager, to modify an existing filter or add a new filter.
Applies the patch to the Route configuration (rds output) inside a HTTP connection manager. This does not apply to the virtual host. Currently, only MERGE operation is allowed on the route configuration objects.
Applies the patch to a virtual host inside a route configuration.
Applies the patch to a route object inside the matched virtual host in a route configuration. Currently, only MERGE operation is allowed on the route objects.
Applies the patch to a cluster in a CDS output. Also used to add new clusters.
PatchContext selects a class of configurations based on the traffic flow direction and workload type.
All listeners/routes/clusters in both sidecars and gateways.
Inbound listener/route/cluster in sidecar.
Outbound listener/route/cluster in sidecar.