EnvoyFilterTemplate and EnvoyFilterTemplateBinding CRD reference - Alibaba Cloud Service Mesh

Service Mesh (ASM) provides two CustomResourceDefinitions (CRDs) -- EnvoyFilterTemplate and EnvoyFilterTemplateBinding -- for creating reusable, version-aware Envoy filter configurations. Define a filter template once, then bind it to workloads, namespaces, and Istio versions without duplicating YAML.

Why use these CRDs instead of raw EnvoyFilter resources?

Version safety. Manually maintained EnvoyFilter resources can become incompatible after an ASM instance upgrade because the Envoy proxy version changes. EnvoyFilterTemplate lets you define version-specific filter configurations so the correct filter is automatically applied after an upgrade.
Reusability. A single template produces multiple EnvoyFilter resources across workloads and namespaces through separate bindings.
Less duplication. Metadata and workload selectors are auto-populated from the binding. You do not need to duplicate them in the template.

Important

The istioVersion ranges defined in a single EnvoyFilterTemplate must not overlap.

How it works

Create an EnvoyFilterTemplate that contains one or more filter configurations, each targeting a specific Istio version range.
Create an EnvoyFilterTemplateBinding that references the template and specifies which workloads and Envoy proxy versions the filter applies to.
ASM automatically generates the corresponding EnvoyFilter resources with the correct metadata, labels, and workload selectors.

Configuration example

The following example defines an EnvoyFilterTemplate that sets HTTP/2 connection and stream window sizes on port 80 for ASM instances running Istio 1.19 and later. A corresponding EnvoyFilterTemplateBinding then generates an Envoy filter targeting proxies on version 1.20, applied globally in the istio-system namespace.

EnvoyFilterTemplate

EnvoyFilterTemplateBinding

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

Generated EnvoyFilter

ASM produces the following EnvoyFilter from the template and binding above. The labels and the proxyVersion match condition are auto-populated from the binding:

EnvoyFilterTemplate fields

EnvoyFilterTemplate defines Envoy filter configurations for different Istio versions. After an ASM instance upgrade, the matching filter configuration is automatically applied to the upgraded Envoy proxies, which reduces compatibility risks compared to manually maintained EnvoyFilter resources.

EnvoyFilterTemplateSpec

Field	Type	Required	Description
`templates`	TemplateValue[]	Yes	A list of Envoy filter template entries. Each entry targets a specific Istio version or version range. Version ranges across entries must not overlap.

TemplateValue

Each TemplateValue pairs an Envoy filter configuration (in YAML) with the Istio version range it applies to.

Field	Type	Required	Description
`istioVersion`	string	Yes	The Istio version or version range this filter targets. Specify an Istio minor version such as `1.19` or `1.20`. Hyphenate two versions to define a range. Use `MIN_VERSION` for the earliest known version and `MAX_VERSION` for the latest. See Version range syntax.
`value`	string	Yes	The Envoy filter configuration in YAML format. Must conform to the EnvoyFilter CRD spec. Omit the `metadata` and `workloadSelector` fields -- ASM auto-populates them from the EnvoyFilterTemplateBinding at generation time.

Version range syntax

Example	Meaning
`"1.19"`	Matches ASM instances running Istio 1.19 only.
`"1.18-1.20"`	Matches Istio 1.18, 1.19, and 1.20.
`"1.19-MAX_VERSION"`	Matches Istio 1.19 and all later versions.
`"MIN_VERSION-1.19"`	Matches Istio 1.19 and all earlier versions.

EnvoyFilterTemplateBinding fields

An EnvoyFilterTemplateBinding associates with one EnvoyFilterTemplate and specifies the workloads and Envoy proxy versions for which ASM generates EnvoyFilter resources.

EnvoyFilterTemplateBindingSpec

Field	Type	Required	Description
`templateRef`	EnvoyFilterTemplateRef	Yes	References the EnvoyFilterTemplate and specifies the Envoy proxy version to target. ASM uses this to select the correct template entry and to set the `proxyVersion` match in the generated EnvoyFilter.
`workloads`	WorkloadRef[]	No	The workloads to generate Envoy filters for.

EnvoyFilterTemplateRef

Field	Type	Required	Description
`name`	string	Yes	The name of the EnvoyFilterTemplate to reference.
`istioVersion`	string	Yes	The Envoy proxy version to target. Uses the same Version range syntax as `TemplateValue.istioVersion`. ASM converts this value into a `proxyVersion` regex match (for example, `"1.20"` becomes `^1\.20.*`) in the generated EnvoyFilter.

WorkloadRef

Defines the workloads the generated Envoy filter applies to.

Field	Type	Required	Default behavior	Description
`namespace`	string	Yes	--	The namespace where the Envoy filter is created. To apply the filter globally across the ASM instance, set this to `istio-system`.
`name`	string	No	Filter applies namespace-wide.	The workload name. This value becomes part of the generated EnvoyFilter name. Set this to the Service or Deployment name when you target a specific workload.
`kind`	string	No	--	The workload type (for example, `Namespace`, `Deployment`, or `Service`). Used for display purposes only and does not affect filter behavior.
`selector`	map<string, string>	No	Filter applies to all pods in the namespace.	A set of labels to select specific pods. ASM converts this into the `workloadSelector` field of the generated EnvoyFilter. If omitted, the filter applies to all pods in the specified namespace.

References

Create an Envoy filter by using an Envoy filter template: Step-by-step operations for creating and managing Envoy filter templates.
Enable plug-ins to extend ASM capabilities: Select and customize plug-ins from the ASM plug-in marketplace.