Envoy Filter

4 minute read

EnvoyFilter describes Envoy proxy-specific filters that can be used to customize the Envoy proxy configuration generated by Istio networking subsystem (Pilot). This feature must be used with care, as incorrect configurations could potentially destabilize the entire mesh.

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: When multiple EnvoyFilters are bound to the same workload, all filter configurations will be processed sequentially in order of creation time. The behavior is undefined if multiple EnvoyFilter configurations conflict with each other.

NOTE 3: For filters of filterType: HTTP you must include a listenerMatch section with a listenerProtocol: HTTP or the filter have no effect.

The following example for Kubernetes enables Envoy’s Lua filter for all inbound HTTP calls arriving at service port 8080 of the reviews service pod with labels “app: reviews”.

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: reviews-lua
spec:
  workloadLabels:
    app: reviews
  filters:
  - listenerMatch:
      portNumber: 8080
      listenerType: SIDECAR_INBOUND # will match with the inbound listener for reviews:8080
      listenerProtocol: HTTP
    filterName: envoy.lua
    filterType: HTTP
    filterConfig:
      inlineCode: |
        ... lua code ...

EnvoyFilter

Field	Type	Description
`workloadLabels`	`map<string, string>`	Zero or more labels that indicate a specific set of pods/VMs whose proxies should be configured to use these additional filters. The scope of label search is platform dependent. On Kubernetes, for example, the scope includes pods running in all reachable namespaces. Omitting the selector applies the filter to all proxies in the mesh.
`filters`	`EnvoyFilter.Filter[]`	REQUIRED: Envoy network filters/http filters to be added to matching listeners. When adding network filters to http connections, care should be taken to ensure that the filter is added before envoy.httpconnectionmanager.

EnvoyFilter.Filter

Envoy filters to be added to a network or http filter chain.

Field	Type	Description
`listenerMatch`	`EnvoyFilter.ListenerMatch`	Filter will be added to the listener only if the match conditions are true. If not specified, the filters will be applied to all listeners where possible, potentially resulting in invalid configurations. It is recommended to specify the listener match criteria for all filter insertions.
`insertPosition`	`EnvoyFilter.InsertPosition`	Insert position in the filter chain. Defaults to FIRST
`filterType`	`EnvoyFilter.Filter.FilterType`	REQUIRED: The type of filter to instantiate.
`filterName`	`string`	REQUIRED: The name of the filter to instantiate. The name must match a supported filter compiled into Envoy.
`filterConfig`	`google.protobuf.Struct`	REQUIRED: Filter specific configuration which depends on the filter being instantiated.

EnvoyFilter.Filter.FilterType

Name	Description
`INVALID`	placeholder
`HTTP`	Http filter
`NETWORK`	Network filter

EnvoyFilter.InsertPosition

Indicates the relative index in the filter chain where the filter should be inserted.

Field	Type	Description
`index`	`EnvoyFilter.InsertPosition.Index`	Position of this filter in the filter chain.
`relativeTo`	`string`	If BEFORE or AFTER position is specified, specify the name of the filter relative to which this filter should be inserted.

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

Select a listener to add the filter to based on the match conditions. All conditions specified in the ListenerMatch must be met for the filter to be applied to a listener.

Field	Type	Description
`portNumber`	`uint32`	The service port/gateway port to which traffic is being sent/received. If not specified, matches all listeners. Even though inbound listeners are generated for the instance/pod ports, only service ports should be used to match listeners.
`portNamePrefix`	`string`	Instead of using specific port numbers, a set of ports matching a given port name prefix can be selected. E.g., “mongo” selects ports named mongo-port, mongo, mongoDB, MONGO, etc. Matching is case insensitive.
`listenerType`	`EnvoyFilter.ListenerMatch.ListenerType`	Inbound vs outbound sidecar listener or gateway listener. If not specified, matches all listeners.
`listenerProtocol`	`EnvoyFilter.ListenerMatch.ListenerProtocol`	Selects a class of listeners for the same protocol. Use the protocol selection to select all HTTP listeners (includes HTTP2/gRPC/HTTPS where Envoy terminates TLS) or all TCP listeners (includes HTTPS passthrough using SNI). When adding a HTTP filter, the listenerProtocol should be set to HTTP.
`address`	`string[]`	One or more IP addresses to which the listener is bound. If specified, should match at least one address in the list.

EnvoyFilter.ListenerMatch.ListenerProtocol

Name	Description
`ALL`	All protocols
`HTTP`	HTTP or HTTPS (with termination) / HTTP2/gRPC
`TCP`	Any non-HTTP listener

EnvoyFilter.ListenerMatch.ListenerType

Name	Description
`ANY`	All listeners
`SIDECAR_INBOUND`	Inbound listener in sidecar
`SIDECAR_OUTBOUND`	Outbound listener in sidecar
`GATEWAY`	Gateway listener