Description of EnvoyFilterTemplate and EnvoyFilterTemplateBinding fields - Alibaba Cloud Service Mesh

Service Mesh (ASM) allows you to create an Envoy filter by using EnvoyFilterTemplate and EnvoyFilterTemplateBinding CustomResourceDefinitions (CRDs). The same Envoy filter template can be used to create multiple Envoy filters, and these Envoy filters can be applied to different workloads and namespaces. This makes configurations reusable and improves management efficiency.

Configuration example

The following code block specifies an EnvoyFilterTemplate CRD. The CRD specifies the content of an Envoy filter template that applies to ASM instances whose Istio version is 1.19 and later. It also specifies an EnvoyFilterTemplateBinding CRD. You can use the CRD to create an Envoy filter that takes effect in the istio-system namespace. This indicates that the Envoy filter takes effect in an ASM instance globally. The Envoy filter applies to all Envoy proxies whose version is 1.20. The filter content is derived from the Envoy filter template defined in the EnvoyFilterTemplate CRD. The template applies to ASM instances whose Istio version is 1.19 and later.

Show the YAML code of EnvoyFilterTemplate

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 YAML code creates the following Envoy filter:

Show the YAML code of the Envoy filter

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

Description of EnvoyFilterTemplate fields

EnvoyFilterTemplate defines a series of Envoy filters. These Envoy filters apply to different Istio versions. Self-managed Envoy filters may be incompatible with ASM instances after the instances are updated or maintained. You can use the EnvoyFilterTemplate CRD to customize different Envoy filters for different Istio versions. After you upgrade the version of an Envoy proxy, you can apply an appropriate Envoy filter in the upgraded proxy. This reduces compatibility risks.

EnvoyFilterTemplateSpec

EnvoyFilterTemplateSpec, the spec section in the preceding example, is the core configuration of EnvoyFilterTemplate.

Field	Type	Required	Description
templates	TemplateValue[]	Yes	Specifies a series of Envoy filter template values. Each template value applies to a specific Istio version or Istio version range. The applicable Istio version ranges of multiple template values cannot be overlapped.

TemplateValue

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

Field

Type

Required

Description

istioVersion

string

Yes

The Istio version or Istio version range to which the Envoy filter is applicable. The version must be an Istio minor version, such as 1.19 or 1.20. You can hyphenate two versions to indicate that the Envoy filter takes effect for the specified version range.

If you want to specify that the Envoy filter takes effect for 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": The Envoy filter applies to ASM instances of v1.19.
"1.18-1.20": The Envoy filter applies to ASM instances of v1.18, v1.19 and v1.20.
"1.19-MAX_VERSION": The Envoy filter applies to ASM instances whose version is 1.19 or later.
"MIN_VERSION-1.19": The Envoy filter applies to ASM instances whose version is 1.19 or earlier.

value

string

Yes

The YAML content of the Envoy filter. The YAML content must be strings and must conform to the description of CRD fields for Envoy filters.

You do not need to configure the metadata and workloadSelector fields when you define the Envoy filter by using the TemplateValue field. When you create an Envoy filter, the metadata and workloadSelector fields are automatically populated based on the EnvoyFilterTemplateBinding CRD.

Description of EnvoyFilterTemplateBinding fields

One EnvoyFilterTemplateBinding CRD is associated with an EnvoyFilterTemplate CRD and specifies the workloads and versions of Envoy proxies for which the Envoy filter defined in the EnvoyFilterTemplate CRD takes effect.

EnvoyFilterTemplateBindingSpec

EnvoyFilterTemplateBindingSpec, that is, the spec section, is the core configuration of EnvoyFilterTemplateBinding.

Field	Type	Required	Description
templateRef	EnvoyFilterTemplateRef	Yes	The template reference. It specifies the EnvoyFilterTemplate CRD referenced by the EnvoyFilterTemplateBinding CRD and the version of the bound ASM instance.
workloads	WorkloadRef[]	No	Specifies the workloads for which you need to create Envoy filters.

EnvoyFilterTemplateRef

Field

Type

Required

Description

name

string

Yes

The name of the referenced EnvoyFilterTemplate.

istioVersion

string

Yes

Specifies the version of the Envoy proxy on which the Envoy filter takes effect.

The version must be an Istio minor version, such as 1.19 or 1.20. You can hyphenate two versions to indicate that the Envoy filter takes effect for the specified version range.

Examples:

"1.19": The Envoy filter applies to ASM instances of v1.19.
"1.18-1.20": The Envoy filter applies to ASM instances of v1.18, v1.19 and v1.20.
"1.19-MAX_VERSION": The Envoy filter applies to ASM instances whose version is 1.19 or later.
"MIN_VERSION-1.19": The Envoy filter applies to ASM instances whose version is 1.19 or earlier.

WorkloadRef

WorkloadRef defines the workloads for which the Envoy filter takes effect.

Field	Type	Required	Description
namespace	string	Yes	The name of the namespace in which the Envoy filter is created.
name	string	No	The name of the workload. This name is part of the name of the created Envoy filter. We recommend that you set this field to the name of the Service or Deployment. If the Envoy filter takes effect globally in a namespace, you do not need to specify this parameter.
kind	string	No	The type of the workload to which the Envoy filter is bound. This field is used for display purposes only.
selector	map<string, string>	No	Specifies a series of labels based on which you select the pod in which the Envoy filter takes effect. This field is automatically converted into the workloadSelector field for the Envoy filter. If you do not specify this parameter, the created Envoy filter takes effect in the entire namespace.

References

For more information about operations and the relationships between Envoy filter templates and Envoy filters, see Create an Envoy filter by using an Envoy filter template.
ASM provides out-of-the-box features in the plug-in marketplace to allow you to extend ASM capabilities as needed. You can select and customize various plug-ins based on your business requirements to satisfy diverse needs. For more information, see Enable plug-ins to extend ASM capabilities.