EnvoyFilterTemplate and EnvoyFilterTemplateBinding CRD reference-Alibaba Cloud Service Mesh-阿里云帮助中心

ASM lets you create Envoy filters using EnvoyFilterTemplate and EnvoyFilterTemplateBinding. You can use the same EnvoyFilterTemplate to create multiple Envoy filters for different workloads and namespaces. This approach improves configuration reusability and management efficiency.

Configuration example

The following example contains an EnvoyFilterTemplate and an EnvoyFilterTemplateBinding. The template defines the content for an Envoy filter that applies to Istio versions 1.19 and later. The binding creates a global EnvoyFilter in the istio-system namespace. This filter applies to all data plane proxies of version 1.20, and its content is sourced from the template defined for Istio versions 1.19 and later.

Expand to view the EnvoyFilterTemplate YAML

apiVersion: istio.alibabacloud.com/v1
kind: EnvoyFilterTemplate
metadata:
  name: seth2windows
  namespace: istio-system
spec:
  templates:
  - istioVersion: "1.19-MAX_VERSION"
    value: |
      apiVersion: networking.istio.io/v1alpha3
      kind: EnvoyFilter
      spec:
        configPatches:
        - applyTo: NETWORK_FILTER
          match:
            context: ANY
            listener:
              filterChain:
                filter:
                  name: envoy.filters.network.http_connection_manager
              portNumber: 80
          patch:
            operation: MERGE
            value:
              typed_config:
                '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                http2_protocol_options:
                  initial_connection_window_size: 65536
                  initial_stream_window_size: 65536
        priority: 0
---
apiVersion: istio.alibabacloud.com/v1
kind: EnvoyFilterTemplateBinding
metadata:
  name: seth2windows-binding-1.20
  namespace: istio-system
spec:
  templateRef:
    istioVersion: "1.20"
    name: seth2windows
  workloads:
  - kind: Namespace
    namespace: istio-system

The preceding configuration creates the following EnvoyFilter:

Expand to view the EnvoyFilter YAML

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  labels:
    asm-system: "true"
    binding-name: seth2windows-binding-1.20
    binding-namespace: istio-system
    provider: asm
    workload-name: ""
    workload-namespace: istio-system
  name: seth2windows-binding-1.20-for-istio-system
  namespace: istio-system
spec:
  configPatches:
  - applyTo: NETWORK_FILTER
    match:
      context: ANY
      listener:
        filterChain:
          filter:
            name: envoy.filters.network.http_connection_manager
        portNumber: 80
      proxy:
        proxyVersion: ^1\.20.*
    patch:
      operation: MERGE
      value:
        typed_config:
          '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          http2_protocol_options:
            initial_connection_window_size: 65536
            initial_stream_window_size: 65536
  priority: 0

EnvoyFilterTemplate field descriptions

An EnvoyFilterTemplate defines different content for EnvoyFilters, where each filter applies to a different Istio version. Manually creating Envoy filters can cause version compatibility issues, which makes it challenging to upgrade and maintain the service mesh. Using an EnvoyFilterTemplate, you can customize EnvoyFilter content for different Istio versions. When you upgrade a data plane proxy, the Envoy filter for the new version takes effect on the proxy. This process reduces compatibility risks.

EnvoyFilterTemplateSpec

EnvoyFilterTemplateSpec is the core configuration of an EnvoyFilterTemplate and is defined in the spec section.

Field	Type	Required	Description
templates	TemplateValue[]	Yes	Specifies a series of EnvoyFilter template values. Each template value has a compatible Istio version or version range. The compatible Istio version ranges of the template values cannot overlap.

TemplateValue

Each TemplateValue specifies the YAML content of an Envoy filter and its compatible Istio version or version range.

Field

Type

Required

Description

istioVersion

string

Yes

The compatible Istio version or version range for the Envoy filter. The version must be a minor version of Istio, such as 1.19 or 1.20. You can use a hyphen (-) to connect two versions to specify a version range where the Envoy filter is effective.

When you specify a version range, you can use MIN_VERSION to represent the earliest known version and MAX_VERSION to represent the latest known version.

Examples:

"1.19": Applies to version 1.19.
"1.18-1.20": Applies to versions 1.18, 1.19, and 1.20.
"1.19-MAX_VERSION": Applies to version 1.19 and later.
"MIN_VERSION-1.19": Applies to version 1.19 and earlier.

value

string

Yes

The YAML content of the Envoy filter. This must be a YAML string that conforms to the EnvoyFilter field definitions. For more information about the EnvoyFilter field definitions, see Envoy Filter CRD reference.

The EnvoyFilter content defined in `TemplateValue` does not need to include the `metadata` or `workloadSelector` fields. These fields are filled in when the EnvoyFilter is created based on the EnvoyFilterTemplateBinding definition.

EnvoyFilterTemplateBinding field descriptions

An EnvoyFilterTemplateBinding associates with an EnvoyFilterTemplate. It specifies the workloads and data plane proxy versions to which the EnvoyFilter content defined in the EnvoyFilterTemplate is applied.

EnvoyFilterTemplateBindingSpec

EnvoyFilterTemplateBindingSpec is the core configuration of an EnvoyFilterTemplateBinding and is defined in the spec section.

Field	Type	Required	Description
templateRef	EnvoyFilterTemplateRef	Yes	A template reference. It specifies the EnvoyFilterTemplate that the EnvoyFilterTemplateBinding references and the binding version information.
workloads	WorkloadRef[]	No	Specifies the workloads for which to create Envoy filters.

EnvoyFilterTemplateRef

Field

Type

Required

Description

name

string

Yes

The name of the referenced EnvoyFilterTemplate.

istioVersion

string

Yes

Specifies the versions of data plane proxies on which the Envoy filter takes effect.

The version must be a minor version of Istio, such as 1.19 or 1.20. You can use a hyphen (-) to connect two versions to specify a version range where the Envoy filter is effective.

When you specify a version range, you can use MIN_VERSION to represent the earliest known version and MAX_VERSION to represent the latest known version.

Examples:

"1.19": Applies to version 1.19.
"1.18-1.20": Applies to versions 1.18, 1.19, and 1.20.
"1.19-MAX_VERSION": Applies to version 1.19 and later.
"MIN_VERSION-1.19": Applies to version 1.19 and earlier.

WorkloadRef

A WorkloadRef defines the scope of an Envoy filter by specifying the workloads on which the filter takes effect.

Field	Type	Required	Description
namespace	string	Yes	The name of the namespace in which to create the Envoy filter.
name	string	No	The name of the workload. This name determines the name of the final EnvoyFilter. Set this to the name of a Service or Deployment. If the Envoy filter applies to the entire namespace, you do not need to specify this field.
kind	string	No	The type of workload to which the Envoy filter is bound. This field is used for display purposes only.
selector	map<string, string>	No	Specifies a set of labels used as conditions to select pods. This is converted to the `workloadSelector` field of the EnvoyFilter. If you do not specify this field, the created Envoy filter applies to the entire namespace.

References

For more information about the relationship between EnvoyFilter templates and Envoy filters and for an operational example, see Create an Envoy filter from an EnvoyFilter template.
For more information about the fields of an EnvoyFilter, see Envoy Filter CRD reference.
ASM provides a series of out-of-the-box feature extensions in the marketplace. You can select and customize various plug-ins based on your business needs to meet diverse requirements. For more information, see Use the marketplace to extend service mesh capabilities.