Envoy Filter

Envoy Filter

EnvoyFilter provides a mechanism to customize the Envoyconfiguration generated by Istio Pilot. Use EnvoyFilter to modifyvalues for certain fields, add specific filters, or even addentirely new listeners, clusters, etc. This feature must be usedwith care, as incorrect configurations could potentiallydestabilize the entire mesh. Unlike other Istio networking objects,EnvoyFilters are additively applied. Any number of EnvoyFilters canexist for a given workload in a specific namespace. The order ofapplication of these EnvoyFilters is as follows: all EnvoyFiltersin the config rootnamespace,followed by all matching EnvoyFilters in the workload’s namespace.

NOTE 1: Since this is break glass configuration, there will notbe any backward compatibility across different Istio releases. Inother words, this configuration is subject to change based oninternal implementation of Istio networking subsystem.

NOTE 2: The envoy configuration provided through this mechanismshould be carefully monitored across Istio proxy version upgrades,to ensure that deprecated fields are removed and replacedappropriately.

NOTE 3: When multiple EnvoyFilters are bound to the sameworkload in a given namespace, all patches will be processedsequentially in order of creation time. The behavior is undefinedif 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 theconfig rootnamespace,without a workloadSelector.

The example below declares a global default EnvoyFilter resource inthe root namespace called istio-config, that adds a customprotocol filter on all sidecars in the system, for outbound port9307. The filter should be added before the terminating tcp_proxyfilter to take effect. In addition, it sets a 30s idle timeout forall 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 inboundHTTP calls arriving at service port 8080 of the reviews service podwith labels “app: reviews”, in the bookinfo namespace. The luafilter calls out to an external service internal.org.net:8888 thatrequires a special cluster definition in envoy. The cluster is alsoadded 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 timeoutand X-Forward-For trusted hops) in the HTTP connection manager in alistener on the ingress gateway in istio-system namespace for theSNI 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 configurationgenerated by Istio Pilot.

Field	Type	Description	Required
`workloadSelector`	`WorkloadSelector`	Criteria used to select the specific set of pods/VMs on whichthis patch configuration should be applied. If omitted, the setof patches in this configuration will be applied to all workloadinstances in the same namespace. If omitted, the EnvoyFilterpatches will be applied to all workloads in the samenamespace. If the EnvoyFilter is present in the config rootnamespace, it will be applied to all applicable workloads in anynamespace.	No
`configPatches`	`EnvoyConfigObjectPatch[]`	One or more patches with match conditions.	Yes

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 anexisting filter or add a new filter.
`HTTP_FILTER`	Applies the patch to the HTTP filter chain in the httpconnection manager, to modify an existing filter or add a newfilter.
`ROUTE_CONFIGURATION`	Applies the patch to the Route configuration (rds output)inside a HTTP connection manager. This does not apply to thevirtual host. Currently, only MERGE operation is allowed on theroute 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 virtualhost in a route configuration. Currently, only MERGE operationis 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 patchto be applied to a cluster.

Field	Type	Description	Required
`portNumber`	`uint32`	The service port for which this cluster was generated. Ifomitted, applies to clusters for any port.	No
`service`	`string`	The fully qualified service name for this cluster. If omitted,applies to clusters for any service. For services definedthrough service entries, the service name is same as the hostsdefined in the service entry.	No
`subset`	`string`	The subset associated with the service. If omitted, applies toclusters for any subset of a service.	No
`name`	`string`	The exact name of the cluster to match. To match a specificcluster by name, such as the internally generated “Passthrough”cluster, leave all fields in clusterMatch empty, except thename.	No

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 appliedto the generated configuration for a given proxy.

Field	Type	Description	Required
`context`	`PatchContext`	The specific config generation context to match on. Istio Pilotgenerates envoy configuration in the context of a gateway,inbound traffic to sidecar and outbound traffic from sidecar.	No
`proxy`	`ProxyMatch`	Match on properties associated with a proxy.	No
`listener`	`ListenerMatch (oneof)`	Match on envoy listener attributes.	Yes
`routeConfiguration`	`RouteConfigurationMatch (oneof)`	Match on envoy HTTP route configuration attributes.	Yes
`cluster`	`ClusterMatch (oneof)`	Match on envoy cluster attributes.	Yes

EnvoyFilter.EnvoyConfigObjectPatch

Changes to be made to various envoy config objects.

Field	Type	Description	Required
`applyTo`	`ApplyTo`	Specifies where in the Envoy configuration, the patch should beapplied. The match is expected to select the appropriateobject based on applyTo. For example, an applyTo withHTTP_FILTER is expected to have a match condition on thelisteners, with a network filter selection onenvoy.http_connection_manager and a sub filter selection on theHTTP filter relative to which the insertion should beperformed. Similarly, an applyTo on CLUSTER should have a match(if provided) on the cluster and not on a listener.	No
`match`	`EnvoyConfigObjectMatch`	Match on listener/route configuration/cluster.	No
`patch`	`Patch`	The patch to apply along with the operation.	No

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 thepatch to be applied to a specific listener across all filterchains, or a specific filter chain inside the listener.

Field	Type	Description	Required
`portNumber`	`uint32`	The service port/gateway port to which traffic is beingsent/received. If not specified, matches all listeners. Even thoughinbound listeners are generated for the instance/pod ports, onlyservice ports should be used to match listeners.	No
`filterChain`	`FilterChainMatch`	Match a specific filter chain in a listener. If specified, thepatch will be applied to the filter chain (and a specificfilter if specified) and not to other filter chains in thelistener.	No
`name`	`string`	Match a specific listener by its name. The listeners generatedby Pilot are typically named as IP:Port.	No

EnvoyFilter.ListenerMatch.FilterChainMatch

For listeners with multiple filter chains (e.g., inboundlisteners on sidecars with permissive mTLS, gateway listenerswith multiple SNI matches), the filter chain match can be usedto select a specific filter chain to patch.

Field	Type	Description	Required
`name`	`string`	The name assigned to the filter chain.	No
`sni`	`string`	The SNI value used by a filter chain’s match condition. Thiscondition will evaluate to false if the filter chain has nosni match.	No
`transportProtocol`	`string`	Applies only to SIDECAR_INBOUND context. If non-empty, atransport protocol to consider when determining a filterchain match. This value will be compared against thetransport protocol of a new connection, when it’s detected bythe tls_inspector listener filter. Accepted values include: - `raw_buffer` - default, used when no transport protocol is detected. - `tls` - set when TLS protocol is detected by the TLS inspector.	No
`applicationProtocols`	`string`	Applies only to sidecars. If non-empty, a comma separated setof application protocols to consider when determining afilter chain match. This value will be compared against theapplication protocols of a new connection, when it’s detectedby one of the listener filters such as the http_inspector. Accepted values include: h2,http/1.1,http/1.0	No
`filter`	`FilterMatch`	The name of a specific filter to apply the patch to. Set thisto envoy.http_connection_manager to add a filter or apply apatch to the HTTP connection manager.	No

EnvoyFilter.ListenerMatch.FilterMatch

Conditions to match a specific filter within a filter chain.

Field	Type	Description	Required
`name`	`string`	The filter name to match on.	No
`subFilter`	`SubFilterMatch`	The next level filter within this filter to matchupon. Typically used for HTTP Connection Manager filters andThrift filters.	No

EnvoyFilter.ListenerMatch.SubFilterMatch

Conditions to match a specific filter within anotherfilter. This field is typically useful to match a HTTP filterinside the envoy.http_connection_manager network filter. Thiscould also be applicable for thrift filters.

Field	Type	Description	Required
`name`	`string`	The filter name to match on.	No

EnvoyFilter.Patch

Patch specifies how the selected object should be modified.

Field	Type	Description	Required
`operation`	`Operation`	Determines how the patch should be applied.	No
`value`	`Struct`	The JSON config of the object being patched. This will be merged usingjson merge semantics with the existing proto in the path.	No

EnvoyFilter.Patch.Operation

Operation denotes how the patch should be applied to the selectedconfiguration.

Name	Description
`INVALID`
`MERGE`	Merge the provided config with the generated config usingjson merge semantics.
`ADD`	Add the provided config to an existing list (of listeners,clusters, virtual hosts, network filters, or httpfilters). This operation will be ignored when applyTo is setto ROUTE_CONFIGURATION, or HTTP_ROUTE.
`REMOVE`	Remove the selected object from the list (of listeners,clusters, virtual hosts, network filters, or httpfilters). Does not require a value to be specified. Thisoperation will be ignored when applyTo is set toROUTE_CONFIGURATION, or HTTP_ROUTE.
`INSERT_BEFORE`	Insert operation on an array of named objects. This operationis typically useful only in the context of filters, where theorder of filters matter. For clusters and virtual hosts,order of the element in the array does not matter. Insertbefore the selected filter or sub filter. If no filter isselected, the specified filter will be inserted at the frontof the list.
`INSERT_AFTER`	Insert operation on an array of named objects. This operationis typically useful only in the context of filters, where theorder of filters matter. For clusters and virtual hosts,order of the element in the array does not matter. Insertafter the selected filter or sub filter. If no filter isselected, the specified filter will be inserted at the endof the list.

EnvoyFilter.PatchContext

PatchContext selects a class of configurations based on thetraffic 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.

Field	Type	Description	Required
`proxyVersion`	`string`	A regular expression in golang regex format (RE2) that can beused to select proxies using a specific version of istioproxy. The Istio version for a given proxy is obtained from thenode metadata field ISTIO_VERSION supplied by the proxy whenconnecting to Pilot. This value is embedded as an environmentvariable (ISTIO_META_ISTIO_VERSION) in the Istio proxy dockerimage. Custom proxy implementations should provide this metadatavariable to take advantage of the Istio version check option.	No
`metadata`	`map<string, string>`	Match on the node metadata supplied by a proxy when connectingto Istio Pilot. Note that while Envoy’s node metadata is oftype Struct, only string key-value pairs are processed byPilot. All keys specified in the metadata must match with exactvalues. The match will fail if any of the specified keys areabsent or the values fail to match.	No

EnvoyFilter.RouteConfigurationMatch

Conditions specified in RouteConfigurationMatch must be met forthe patch to be applied to a route configuration object or aspecific virtual host within the route configuration.

Field	Type	Description	Required
`portNumber`	`uint32`	The service port number or gateway server port number for whichthis route configuration was generated. If omitted, applies toroute configurations for all ports.	No
`portName`	`string`	Applicable only for GATEWAY context. The gateway server portname for which this route configuration was generated.	No
`gateway`	`string`	The Istio gateway config’s namespace/name for which this routeconfiguration was generated. Applies only if the context isGATEWAY. Should be in the namespace/name format. Use this fieldin conjunction with the portNumber and portName to accuratelyselect the Envoy route configuration for a specific HTTPSserver within a gateway config object.	No
`vhost`	`VirtualHostMatch`	Match a specific virtual host in a route configuration andapply the patch to the virtual host.	No
`name`	`string`	Route configuration name to match on. Can be used to match aspecific route configuration by name, such as the internallygenerated “http_proxy” route configuration for all sidecars.	No

EnvoyFilter.RouteConfigurationMatch.RouteMatch

Match a specific route inside a virtual host in a route configuration.

Field	Type	Description	Required
`name`	`string`	The Route objects generated by default are named as“default”. Route objects generated using a virtual servicewill carry the name used in the virtual service’s HTTProutes.	No
`action`	`Action`	Match a route with specific action type.	No

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.

Field	Type	Description	Required
`name`	`string`	The VirtualHosts objects generated by Istio are named ashost:port, where the host typically corresponds to theVirtualService’s host field or the hostname of a service in theregistry.	No
`route`	`RouteMatch`	Match a specific route within the virtual host.	No