Envoy Filter CRD reference-Alibaba Cloud Service Mesh-阿里云帮助中心

Docs ICP Filing Console

Envoy Filter customizes the Envoy configuration generated by the control plane. You can use Envoy Filter to modify the values of certain fields, add specific filters, or add new listeners and clusters. In Envoy, a cluster is a group of upstream hosts that accept traffic from Envoy. Unlike other Istio network objects, Envoy Filters are applied cumulatively. Any number of Envoy Filters can exist for a given workload in a specific namespace. This topic describes the considerations, configuration examples, and fields for Envoy Filter.

Considerations

Use this feature with caution. An incorrect configuration can destabilize the entire service mesh.
Some aspects of this API are closely tied to the internal implementation of the Istio networking subsystem and Envoy's XDS API. The Envoy Filter API itself will remain backward compatible. However, during a Service Mesh upgrade, carefully check any Envoy configuration provided through this mechanism. This ensures that deprecated fields are removed and replaced as needed.
When multiple Envoy Filters are attached to the same workload in a given namespace, all patches are processed sequentially in the order of their creation time. Conflicts between multiple Envoy Filter configurations result in undefined behavior.
To apply an Envoy Filter resource to all workloads (sidecars and gateways) in the system, you can define the resource in the `istio-system` namespace. Do not add the workloadSelector field to the resource.

Configuration examples

Example 1: Add a custom protocol filter to outbound port 9307 for all sidecars

The following example declares a global default EnvoyFilter resource in the `istio-system` namespace named `istio-config`. This adds a custom protocol filter to outbound port 9307 for all sidecars in the system. The filter is declared to take effect before the `tcp_proxy` filter is executed. It also sets a 30 second idle timeout for all HTTP connections in gateways and sidecars.

Expand to view the EnvoyFilter YAML

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.filters.network.tcp_proxy"
    patch:
      operation: INSERT_BEFORE
      value:
        # This is the full filter config including the name and typed_config section.
        name: "envoy.extensions.filters.network.mongo_proxy"
        typed_config:
          "@type": "type.googleapis.com/envoy.extensions.filters.network.mongo_proxy.v3.MongoProxy"
          ...
  - 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.filters.network.http_connection_manager"
    patch:
      operation: MERGE
      value:
        name: "envoy.filters.network.http_connection_manager"
        typed_config:
          "@type": "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager"
          common_http_protocol_options:
            idle_timeout: 30s

Example 2: Enable Envoy's Lua filter for all inbound HTTP calls to port 8080 of the reviews service in the bookinfo namespace

The following example enables Envoy's Lua filter for all inbound HTTP calls to port 8080 of the `reviews` service in the `bookinfo` namespace. The Lua filter invokes an external service `internal.org.net:8888`, which requires a special `cluster` definition in Envoy. This `cluster` information is also added to the sidecar as part of the configuration.

Expand to view the EnvoyFilter YAML

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.filters.network.http_connection_manager"
            subFilter:
              name: "envoy.filters.http.router"
    patch:
      operation: INSERT_BEFORE
      value: # lua filter specification
       name: envoy.filters.http.lua
       typed_config:
          "@type": "type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua"
          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
        load_assignment:
          cluster_name: lua_cluster
          endpoints:
          - lb_endpoints:
            - endpoint:
                address:
                  socket_address:
                    protocol: TCP
                    address: "internal.org.net"
                    port_value: 8888

Example 3: Override a filter in the ingress gateway listener in the istio-system namespace

The following example overrides some fields, such as HTTP idle timeout and X-Forward-For trusted hops, in the `http_connection_manager` filter. The filter is in the ingress gateway listener in the `istio-system` namespace for the SNI hostname app.example.com.

Expand to view the EnvoyFilter YAML

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: hcm-tweaks
  namespace: istio-system
spec:
  workloadSelector:
    labels:
      istio: ingressgateway
  configPatches:
  - applyTo: NETWORK_FILTER # http connection manager is a filter in Envoy
    match:
      context: GATEWAY
      listener:
        filterChain:
          sni: app.example.com
          filter:
            name: "envoy.filters.network.http_connection_manager"
    patch:
      operation: MERGE
      value:
        typed_config:
          "@type": "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager"
          xff_num_trusted_hops: 5
          common_http_protocol_options:
            idle_timeout: 30s

Example 4: Insert an attributegen filter in the myns namespace

The following example inserts an `attributegen` filter to generate the `istio_operationId` attribute, which is consumed by the `istio.stats` filter. `filterClass: STATS` encodes this dependency.

Expand to view the EnvoyFilter YAML

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: reviews-request-operation
  namespace: myns
spec:
  workloadSelector:
    labels:
      app: reviews
  configPatches:
  - applyTo: HTTP_FILTER
    match:
      context: SIDECAR_INBOUND
    patch:
      operation: ADD
      filterClass: STATS # This filter will run *before* the Istio stats filter.
      value:
        name: istio.request_operation
        typed_config:
         "@type": type.googleapis.com/udpa.type.v1.TypedStruct
         type_url: type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm
         value:
           config:
             configuration: |
               {
                 "attributes": [
                   {
                     "output_attribute": "istio_operationId",
                     "match": [
                       {
                         "value": "ListReviews",
                         "condition": "request.url_path == '/reviews' && request.method == 'GET'"
                       }]
                   }]
               }
             vm_config:
               runtime: envoy.wasm.runtime.null
               code:
                 local: { inline_string: "envoy.wasm.attributegen" }

Example 5: Insert an HTTP ext_authz filter in the myns namespace

Expand to view the EnvoyFilter YAML

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: myns-ext-authz
  namespace: myns
spec:
  configPatches:
  - applyTo: HTTP_FILTER
    match:
      context: SIDECAR_INBOUND
    patch:
      operation: ADD
      filterClass: AUTHZ # This filter will run *after* the Istio authz filter.
      value:
        name: envoy.filters.http.ext_authz
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
          grpc_service:
            envoy_grpc:
              cluster_name: acme-ext-authz
            initial_metadata:
            - key: foo
              value: myauth.acme # required by local ext auth server.

Field reference

EnvoyFilter

EnvoyFilter provides a mechanism to customize the Envoy configuration generated by the control plane. EnvoyFilters are applied in order of precedence from highest to lowest: all EnvoyFilters in the `istio-system` namespace, followed by all matching EnvoyFilters in the workload's namespace.

Field	Type	Required	Description
workloadSelector	WorkloadSelector	No	Criteria for selecting pods to apply the patch configuration. If omitted, the patch set in this configuration applies to all workload instances in the same namespace. If the EnvoyFilter is in the `istio-system` namespace, it applies to all applicable workloads in any namespace.
configPatches	EnvoyConfigObjectPatch[]	Yes	One or more patches with matching conditions.
priority	int32	No	The priority defines the order in which patch sets are applied within a context. The order of patch application is important when one patch depends on another. The API provides the following main principles for patch sorting: Patch sets in the `istio-system` namespace are applied before patch sets in the workload's namespace. Patches in a patch set are processed in the order they appear in the configPatches list. If multiple patch sets exist, they are sorted in ascending order by priority, creation time, and fully qualified resource name. The default value for priority is 0. The value ranges from min-int32 to max-int32. Patch sets with negative priorities are processed before default patch sets. Patch sets with positive priorities are processed after default patch sets. Start with priority values that are multiples of 10 to leave room for further insertions.

EnvoyFilter.ProxyMatch

Properties of the proxy to be matched.

Field

Type

Required

Description

proxyVersion

string

No

A regular expression in Golang RE2 format. Use it to select an Istio proxy of a specific version. The Istio version of a proxy is read from the ISTIO_VERSION node metadata field. The sidecar proxy provides this value when it connects to the control plane. The value is embedded in the Istio proxy Docker image as an environment variable (ISTIO_META_ISTIO_VERSION). Custom proxy implementations must provide this metadata variable to use the Istio version check option.

metadata

map<string, string>

No

This option matches the node metadata that the proxy provides when it connects to the control plane. Although Envoy's node metadata type is a Struct, Pilot only processes string key-value pairs. All keys specified in the metadata must match the exact values. If any specified key does not exist or the value does not match, the match fails.

EnvoyFilter.ClusterMatch

The conditions specified in ClusterMatch must be met to apply the patch to the cluster.

Field

Type

Required

Description

portNumber

uint32

No

The service port of the cluster. If omitted, this applies to clusters on any port.

Note

For inbound clusters, this field should be the destination port of the service.

service

string

No

The fully qualified service name for this cluster. If omitted, this applies to clusters for any service. For services defined by a Service Entry, the service name is the same as the host defined in the Service Entry.

Note

For inbound clusters, this field is ignored.

subset

string

No

The subset associated with the service. If omitted, this applies to clusters for any subset of the service.

name

string

No

The exact name of the cluster to match. To match a specific cluster by name, such as an internally generated Passthrough cluster, leave all fields in clusterMatch empty except for name.

EnvoyFilter.RouteConfigurationMatch

The conditions specified in RouteConfigurationMatch must be met to apply the patch to a route configuration object or a specific virtual host within the route configuration.

Field

Type

Required

Description

portNumber

uint32

No

The service port number or gateway server port number that generates this route configuration. If omitted, this applies to route configurations for all ports.

portName

string

No

Applies only to the GATEWAY context. The name of the gateway server port that generates this route configuration.

gateway

string

No

The namespace/name of the Istio gateway configuration that generates this route configuration. This applies only when the context is GATEWAY. Use the `namespace/name` format. Use this field with portNumber and portName to select the Envoy route configuration for a specific HTTPS server in the gateway configuration object.

vhost

VirtualHostMatch

No

Matches a specific virtual host in the route configuration and applies the patch to the virtual host.

name

string

No

The name of the route configuration to match. Use this to match a specific route configuration by name, such as the route configuration generated by the internal `http_proxy` for all sidecars.

EnvoyFilter.ListenerMatch

The conditions specified in ListenerMatch must be met to apply the patch to a specific listener in all filter chains, or to a specific filter chain within a listener.

Field

Type

Required

Description

portNumber

uint32

No

The service port or gateway port that sends or receives traffic to the pod. If not specified, matches all listeners. Even for inbound listeners generated for a pod, use only the service port (not the pod port) to match the listener.

filterChain

FilterChainMatch

No

Matches a specific filter chain in the listener. If specified, the patch is applied to the filter chain (and the specified specific filter) instead of other filter chains in the listener.

listenerFilter

string

No

Matches a specific listener filter. If specified, the patch is applied to the specified listener filter.

name

string

No

Matches a specific listener by name. Listeners generated by Pilot are typically named IP:Port.

EnvoyFilter.Patch

Patch specifies how the selected object should be modified.

Field	Type	Required	Description
operation	Operation	No	Specifies how the patch should be applied.
value	Struct	No	The JSON configuration for the object being patched. This is merged with the existing Proto at the path using Proto merge semantics.
filterClass	FilterClass	No	Determines the filter insertion order.

EnvoyFilter.EnvoyConfigObjectMatch

The match conditions that must be met before applying a patch to the generated configuration for a given proxy.

Field	Type	Required	Description
context	PatchContext	No	The specific configuration generation context to match. The control plane generates Envoy configurations in the contexts of gateways, inbound traffic to a sidecar, and outbound traffic from a sidecar.
proxy	ProxyMatch	No	Matches properties associated with the proxy.
listener	ListenerMatch (oneof)	No	Matches Envoy listener properties.
routeConfiguration	RouteConfigurationMatch (oneof)	No	Matches Envoy HTTP route configuration properties.
cluster	ClusterMatch (oneof)	No	Matches Envoy cluster properties.

EnvoyFilter.EnvoyConfigObjectPatch

Changes to be made to an Envoy configuration object.

Field	Type	Required	Description
applyTo	ApplyTo	No	Specifies where in the Envoy configuration the patch should be applied. The match should select the appropriate object based on applyTo. For an applyTo of HTTP_FILTER, set the match condition on the listener, select the network filter on `envoy.filters.network.http_connection_manager`, and select the sub-filter of the HTTP filter related to the insertion position. For an applyTo of CLUSTER, if a match condition is provided, it should match on the cluster, not on the listener.
match	EnvoyConfigObjectMatch	No	Matches a listener, route configuration, or cluster.
patch	Patch	No	The patch to apply.

EnvoyFilter.RouteConfigurationMatch.RouteMatch

Matches a specific route within a virtual host in the route configuration.

Field

Type

Required

Description

name

string

No

The default generated Route object is named `default`. Route objects generated by a virtual service will have the name used in the virtual service's HTTP route.

action

No

Matches a route with a specific action type.

EnvoyFilter.RouteConfigurationMatch.VirtualHostMatch

Matches a specific virtual host in the route configuration.

Field

Type

Required

Description

name

string

No

VirtualHosts objects generated by Istio are named host:port, where host typically corresponds to the host field of a VirtualService or the hostname of a service in the registry.

route

No

Matches a specific route within the virtual host.

EnvoyFilter.ListenerMatch.FilterChainMatch

For listeners with multiple filter chains, such as an inbound listener on a sidecar with permissive mTLS or a gateway listener with multiple SNI matches, you can use a filter chain match to select the specific filter chain to modify.

Field

Type

Required

Description

name

string

No

The name assigned to the filter chain.

sni

string

No

The SNI value used by the filter chain's match condition. If the filter chain has no sni match, this condition will be false.

transportProtocol

string

No

Applies only to the SIDECAR_INBOUND context. If not empty, the transport protocol is considered when determining a filter chain match. When the tls_inspector listener filter detects a new connection, this value is compared with the new connection's transport protocol. Valid values are:

raw_buffer: The default, used when no transport protocol is detected.
tls: Set when the TLS inspector detects the TLS protocol.

applicationProtocols

string

No

Applies only to sidecars. If not empty, this is set to a comma-separated list of application protocols to use for determining a filter chain match. When a listener filter such as `http_inspector` detects a new connection, this value is compared with the new connection's application protocol. Values include h2, http/1.1, and http/1.0.

filter

No

The name of the specific filter to apply the patch to. Set this field to envoy.filters.network.http_connection_manager to add a filter or apply a patch to the HTTP Connection Manager.

destinationPort

uint32

No

The destinationPort value used by the filter chain's match. If the filter chain has no destinationPort match, this condition will be false.

EnvoyFilter.ListenerMatch.FilterMatch

Conditions for matching a specific filter in a filter chain.

Field

Type

Required

Description

name

string

No

The name of the filter to match. For standard Envoy filters, use the canonical filter name. For more information, see Canonical filters.

subFilter

No

The next-level filter to match within this filter. This is typically used for the HTTP Connection Manager and Thrift filters.

EnvoyFilter.ListenerMatch.SubFilterMatch

Conditions for matching a specific sub-filter within a filter. This field is typically used to match an HTTP filter within the envoy.filters.network.http_connection_manager network filter. It also applies to Thrift filters.

Field	Type	Required	Description
name	string	No	The name of the filter to match.

EnvoyFilter.RouteConfigurationMatch.RouteMatch.Action

Action specifies the routing action that Envoy takes when an HTTP route matches.

Field	Description
ANY	All of the following three actions are executed.
ROUTE	Routes traffic to a cluster or a weighted cluster.
REDIRECT	Redirects the request.
DIRECT_RESPONSE	Returns a response directly with a specific payload.

EnvoyFilter.Patch.Operation

Operation specifies how the patch should be applied to the selected configuration.

Field	Description
MERGE	Merges the provided configuration with the generated configuration using Proto merge semantics. If you want to specify the configuration completely, use REPLACE instead.
ADD	Adds the provided configuration to an existing list (listener, cluster, virtual host, network filter, or HTTP filter). This operation is ignored when applyTo is set to ROUTE_CONFIGURATION or HTTP_ROUTE.
REMOVE	Removes the selected object from a list (listener, cluster, virtual host, network filter, route, or HTTP filter). You do not need to specify a value. This operation is ignored when applyTo is set to ROUTE_CONFIGURATION or HTTP_ROUTE.
INSERT_BEFORE	Performs an insert operation on a named object array. This operation is useful only in the context of filters or routes where the order of elements matters. Routes should be sorted from the most specific to the most general match conditions because the first matching element is selected. For clusters and virtual hosts, the order of elements in the array does not matter. This operation inserts before the selected filter or sub-filter. If no filter is selected, the specified filter is inserted at the beginning of the list.
INSERT_AFTER	Performs an insert operation on a named object array. This operation is useful only in the context of filters or routes where the order of elements matters. Routes should be sorted from the most specific to the most general match conditions because the first matching element is selected. For clusters and virtual hosts, the order of elements in the array does not matter. This operation inserts after the selected filter or sub-filter. If no filter is selected, the specified filter is inserted at the end of the list.
INSERT_FIRST	Performs an insert operation on a named object array. This operation is useful only in the context of filters or routes where the order of elements matters. Routes should be sorted from the most specific to the most general match conditions because the first matching element is selected. For clusters and virtual hosts, the order of elements in the array does not matter. Inserts at the beginning of the list, regardless of the presence of the selected filter. Use this field when you want a filter to be the first in the list based on the match condition specified in the Match clause.
REPLACE	Replaces the content of the named filter with new content. The REPLACE operation applies only to HTTP_FILTER and NETWORK_FILTER. If the named filter is not found, this operation is a no-op.

EnvoyFilter.Patch.FilterClass

FilterClass determines the insertion point of a filter in a filter chain, relative to filters that are implicitly inserted by the control plane. You can use this with the ADD operation. This is the preferred mechanism for adding filters over the INSERT_* operations, which rely on potentially unstable filter names. Filter ordering is important if your filter depends on or affects the functionality of another filter in the filter chain. Within a filter class, filters are inserted in the order of processing.

Field	Description
UNSPECIFIED	The control plane decides where to insert the filter. Do not specify a FilterClass if the filter is independent of other filters.
AUTHN	Inserts the filter after the Istio authentication filter.
AUTHZ	Inserts the filter after the Istio authorization filter.
STATS	Inserts the filter before the Istio statistics filter.

EnvoyFilter.ApplyTo

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

Field	Description
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 (DRS output) within the HTTP Connection Manager. This field does not apply to virtual hosts. Only the MERGE operation is allowed on the route configuration object.
VIRTUAL_HOST	Applies the patch to a virtual host within a route configuration.
HTTP_ROUTE	Applies the patch to a route object within a matched virtual host in the route configuration.
CLUSTER	Applies the patch to a cluster in the CDS output. It can also be used to add a new cluster.
EXTENSION_CONFIG	Applies a patch or adds an extension configuration in the ECDS output. Only HTTP filters support ECDS.
BOOTSTRAP	Applies the patch to the bootstrap configuration.
LISTENER_FILTER	Applies the patch to the listener filter.

EnvoyFilter.PatchContext

PatchContext selects a class of configurations based on the traffic direction and workload type.

Field	Description
ANY	All listeners, routes, or clusters in both sidecars and gateways.
SIDECAR_INBOUND	All inbound listeners, routes, or clusters in a sidecar.
SIDECAR_OUTBOUND	Outbound listeners, routes, or clusters in a sidecar.
GATEWAY	Gateway listeners, routes, or clusters.

Previous：Extend ASM data plane proxiesNext：EnvoyFilterTemplate and EnvoyFilterTemplateBinding CRD reference

该文章对您有帮助吗？