---
WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL SOURCE IN THE https://github.com/istio/api REPO
source_repo: https://github.com/istio/api
title: Envoy Filter
description: Configuration affecting insertion of custom Envoy filters.
location: https://istio.io/docs/reference/config/networking/v1alpha3/envoy-filter.html
layout: protoc-gen-docs
generator: protoc-gen-docs
number_of_entries: 8
---
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.
The following example for Kubernetes enables Envoy’s Lua filter for all
inbound 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
filterName: envoy.lua
filterType: HTTP
filterConfig:
inlineCode: |
... lua code ...
EnvoyFilter
Field |
Type |
Description |
workloadLabels |
map<string, string> |
One 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.
NOTE: There can be only one EnvoyFilter bound to a specific workload.
The behavior is undefined if multiple EnvoyFilter configurations are
specified for the same workload.
|
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.
|
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. If not
specified, applies to listeners on all protocols. 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).
|
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
|