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.

EnvoyFilter.ApplyTo

ApplyTo specifies where in the Envoy configuration, the given patch should be applied.

EnvoyFilter.ClusterMatch

Conditions specified in ClusterMatch must be met for the patchto be applied to a cluster.

EnvoyFilter.DeprecatedListenerMatch.ListenerProtocol

EnvoyFilter.DeprecatedListenerMatch.ListenerType

EnvoyFilter.EnvoyConfigObjectMatch

One or more match conditions to be met before a patch is appliedto the generated configuration for a given proxy.

EnvoyFilter.EnvoyConfigObjectPatch

Changes to be made to various envoy config objects.

EnvoyFilter.Filter.FilterType

EnvoyFilter.InsertPosition.Index

Index/position in the filter chain.

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.

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.

EnvoyFilter.ListenerMatch.FilterMatch

Conditions to match a specific filter within a filter chain.

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.

EnvoyFilter.Patch

Patch specifies how the selected object should be modified.

EnvoyFilter.Patch.Operation

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

EnvoyFilter.PatchContext

PatchContext selects a class of configurations based on thetraffic flow direction and workload type.

EnvoyFilter.ProxyMatch

One or more properties of the proxy to match on.

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.

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.

EnvoyFilter.RouteConfigurationMatch.VirtualHostMatch

Match a specific virtual host inside a route configuration.