Envoy Filter
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
namespace,
followed by all matching EnvoyFilters in the workload’s namespace.
NOTE 1: Since this is break glass configuration, there will not be any backward compatibility across different Istio releases. In other words, this configuration is subject to change based on internal implementation of Istio networking subsystem.
NOTE 2: The 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 3: 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 4: *_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.
apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
name: custom-protocol
namespace: istio-config # as defined in meshConfig resource.
spec:
configPatches:
- applyTo: NETWORK_FILTER
match:
context: SIDECAR_OUTBOUND # will match outbound listeners in all sidecars
listener:
portNumber: 9307
filterChain:
filter:
name: "envoy.tcp_proxy"
patch:
operation: INSERT_BEFORE
value:
name: "envoy.config.filter.network.custom_protocol"
config:
...
- applyTo: NETWORK_FILTER # http connection manager is a filter in Envoy
match:
# context omitted so that this applies to both sidecars and gateways
listener:
filterChain:
filter:
name: "envoy.http_connection_manager"
patch:
operation: MERGE
value:
typed_config:
"@type": "type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager"
idle_timeout: 30s
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.
apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
name: reviews-lua
namespace: bookinfo
spec:
workloadSelector:
labels:
app: reviews
configPatches:
# The first patch adds the lua filter to the listener/http connection manager
- applyTo: HTTP_FILTER
match:
context: SIDECAR_INBOUND
listener:
portNumber: 8080
filterChain:
filter:
name: "envoy.http_connection_manager"
subFilter:
name: "envoy.router"
patch:
operation: INSERT_BEFORE
value: # lua filter specification
name: envoy.lua
config:
inlineCode: |
function envoy_on_request(request_handle)
-- Make an HTTP call to an upstream host with the following headers, body, and timeout.
local headers, body = request_handle:httpCall(
"lua_cluster",
{
[":method"] = "POST",
[":path"] = "/acl",
[":authority"] = "internal.org.net"
},
"authorize call",
5000)
end
# 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
match:
context: SIDECAR_OUTBOUND
patch:
operation: ADD
value: # cluster specification
name: "lua_cluster"
type: STRICT_DNS
connect_timeout: 0.5s
lb_policy: ROUND_ROBIN
hosts:
- socket_address:
protocol: TCP
address: "internal.org.net"
port_value: 8888
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:
apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
name: hcm-tweaks
namespace: istio-system
spec:
workloadSelector:
labels:
istio: ingress-gateway
configPatches:
- applyTo: NETWORK_FILTER # http connection manager is a filter in Envoy
match:
context: GATEWAY
listener:
filterChain:
sni: app.example.com
filter:
name: "envoy.http_connection_manager"
patch:
operation: MERGE
value:
idle_timeout: 30s
xff_num_trusted_hops: 5
EnvoyFilter
EnvoyFilter provides a mechanism to customize the Envoy configuration generated by Istio Pilot.
EnvoyFilter.ApplyTo
ApplyTo specifies where in the Envoy configuration, the given patch should be applied.
Name | Description |
---|---|
INVALID | |
LISTENER | Applies the patch to the listener. |
FILTER_CHAIN | Applies the patch to the filter chain. |
NETWORK_FILTER | Applies the patch to the network filter chain, to modify an existing filter or add a new filter. |
HTTP_FILTER | Applies the patch to the HTTP filter chain in the http connection manager, to modify an existing filter or add a new filter. |
ROUTE_CONFIGURATION | 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. |
VIRTUAL_HOST | Applies the patch to a virtual host inside a route configuration. |
HTTP_ROUTE | 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. |
CLUSTER | Applies the patch to a cluster in a CDS output. Also used to add new clusters. |
EnvoyFilter.ClusterMatch
Conditions specified in ClusterMatch must be met for the patch to be applied to a cluster.
EnvoyFilter.DeprecatedListenerMatch.ListenerProtocol
Name | Description |
---|---|
ALL | All protocols |
HTTP | HTTP or HTTPS (with termination) / HTTP2/gRPC |
TCP | Any non-HTTP listener |
EnvoyFilter.DeprecatedListenerMatch.ListenerType
Name | Description |
---|---|
ANY | All listeners |
SIDECAR_INBOUND | Inbound listener in sidecar |
SIDECAR_OUTBOUND | Outbound listener in sidecar |
GATEWAY | Gateway listener |
EnvoyFilter.EnvoyConfigObjectMatch
One or more match conditions to be met before a patch is applied to the generated configuration for a given proxy.
EnvoyFilter.EnvoyConfigObjectPatch
Changes to be made to various envoy config objects.
EnvoyFilter.Filter.FilterType
Name | Description |
---|---|
INVALID | placeholder |
HTTP | Http filter |
NETWORK | Network filter |
EnvoyFilter.InsertPosition.Index
Index/position in the filter chain.
Name | Description |
---|---|
FIRST | Insert first |
LAST | Insert last |
BEFORE | Insert before the named filter. |
AFTER | Insert after the named filter. |
EnvoyFilter.ListenerMatch
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.
EnvoyFilter.ListenerMatch.FilterChainMatch
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.
EnvoyFilter.ListenerMatch.FilterMatch
Conditions to match a specific filter within a filter chain.
EnvoyFilter.ListenerMatch.SubFilterMatch
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.
EnvoyFilter.Patch
Patch specifies how the selected object should be modified.
EnvoyFilter.Patch.Operation
Operation denotes how the patch should be applied to the selected configuration.
Name | Description |
---|---|
INVALID | |
MERGE | Merge the provided config with the generated config using json merge semantics. |
ADD | 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 | 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_BEFORE | 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_AFTER | 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. |
EnvoyFilter.PatchContext
PatchContext selects a class of configurations based on the traffic flow direction and workload type.
Name | Description |
---|---|
ANY | All listeners/routes/clusters in both sidecars and gateways. |
SIDECAR_INBOUND | Inbound listener/route/cluster in sidecar. |
SIDECAR_OUTBOUND | Outbound listener/route/cluster in sidecar. |
GATEWAY | Gateway listener/route/cluster. |
EnvoyFilter.ProxyMatch
One or more properties of the proxy to match on.
EnvoyFilter.RouteConfigurationMatch
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.
EnvoyFilter.RouteConfigurationMatch.RouteMatch
Match a specific route inside a virtual host in a route configuration.
EnvoyFilter.RouteConfigurationMatch.RouteMatch.Action
Action refers to the route action taken by Envoy when a http route matches.
Name | Description |
---|---|
ANY | All three route actions |
ROUTE | Route traffic to a cluster / weighted clusters. |
REDIRECT | Redirect request. |
DIRECT_RESPONSE | directly respond to a request with specific payload. |
EnvoyFilter.RouteConfigurationMatch.VirtualHostMatch
Match a specific virtual host inside a route configuration.