When you update or maintain a Service Mesh (ASM) instance, self-managed Envoy filters can break due to version incompatibility. Envoy filter templates solve this by automatically adapting filters to each ASM version -- you define a template once, bind it to workloads or namespaces, and ASM creates and maintains the corresponding Envoy filters through upgrades.
| Approach | Version compatibility | Reusability | Maintenance |
|---|---|---|---|
| Envoy filter template | Automatic -- filters adapt when the ASM instance is updated | One template creates filters for multiple workloads | Modify the template once; all filters update |
| Standalone Envoy filter | Manual -- requires checking and fixing after each update | Each filter is configured independently | Update each filter individually |
Key behaviors:
A template is a blueprint; an Envoy filter is an instance of that template. The template defines how traffic is processed but does not apply to traffic directly.
One template can produce multiple Envoy filters across different workloads and namespaces.
Modifying a template automatically updates all Envoy filters created from it.
Deleting a template automatically deletes all its Envoy filters.
Unbinding a template from a workload or namespace automatically deletes the Envoy filter for that scope.
Binding a template to the
istio-systemnamespace makes it globally effective and automatically unbinds it from all other workloads and namespaces.
Prerequisites
An ASM instance of v1.12.4.0 or later with at least one cluster added. See Add a cluster to an ASM instance and Update an ASM instance
Create an Envoy filter template
Log on to the ASM console. In the left-side navigation pane, choose Service Mesh > Mesh Management.
On the Mesh Management page, click the name of your ASM instance. In the left-side navigation pane, choose Plugin Extension Center > EnvoyFilter Template.
Click Create EnvoyFilter Template.
In the Basic Information section, enter a name for the template.
In the Multi-version adapted EnvoyFilter templates section, click Add an EnvoyFilter template for specific adapted istio version.
Select an Istio version from the Adapted istio version drop-down list, configure the filter parameters, and click Create.
NoteFor ASM instances of version 1.18.0.146 or later, No Minimum Version Limit and No Maximum Version Limit are selected by default. To restrict the version range, clear either option and enter a specific version.
For details on EnvoyFilter configuration fields and examples, see Envoy Filter.
The template appears on the EnvoyFilter Template page.
Bind the template to a workload or namespace
After you create a template, bind it to one or more workloads or namespaces. ASM then automatically creates the corresponding Envoy filters.
Bind to a workload
Log on to the ASM console. In the left-side navigation pane, choose Service Mesh > Mesh Management.
On the Mesh Management page, click the name of your ASM instance. In the left-side navigation pane, choose Plugin Extension Center > EnvoyFilter Template.
Find the template and click Edit template in the Actions column.
Open the binding configuration:
Version earlier than 1.18.0.146: Click the Bind template to workloads tab, then click Bind EnvoyFilter to Workloads.
Version 1.18.0.146 or later: Scroll to the Bind template to workloads section. If the message "The EnvoyFilter template has adapted this version, but the correspond EnvoyFilters has not been created" appears, click Create first. Then click Bind EnvoyFilter to Workloads.
In the Bind EnvoyFilter to Workloads dialog box, set the Namespace and Workload Type parameters, click Bind next to the target workload in the Not bound section, and click OK.
To verify, go to Plugin Extension Center > EnvoyFilter in the left-side navigation pane. The automatically created Envoy filter appears on the EnvoyFilter page.
Bind to a namespace
Log on to the ASM console. In the left-side navigation pane, choose Service Mesh > Mesh Management.
On the Mesh Management page, click the name of your ASM instance. In the left-side navigation pane, choose Plugin Extension Center > EnvoyFilter Template.
Find the template and click Edit template in the Actions column.
Open the binding configuration:
Version earlier than 1.18.0.146: Click the Bind template to workloads tab, then click Bind EnvoyFilter to Namespace.
Version 1.18.0.146 or later: Scroll to the Bind template to workloads section. If the message "The EnvoyFilter template has adapted this version, but the correspond EnvoyFilters has not been created" appears, click Create first. Then click Bind EnvoyFilter to Namespace.
In the Bind EnvoyFilter to Namespace dialog box, click the target namespace in the Not bound section and click OK.
NoteBinding a template to the
istio-systemnamespace makes it globally effective. The template is automatically unbound from all other workloads and namespaces.
To verify, go to Plugin Extension Center > EnvoyFilter in the left-side navigation pane. The automatically created Envoy filter appears on the EnvoyFilter page.
Modify a template
Only custom templates can be modified. Preset templates, labeled ASM plug-in on the EnvoyFilter Template page, cannot be modified.
Log on to the ASM console. In the left-side navigation pane, choose Service Mesh > Mesh Management.
On the Mesh Management page, click the name of your ASM instance. In the left-side navigation pane, choose Plugin Extension Center > EnvoyFilter Template.
Find the template and click Edit template in the Actions column.
Update the template parameters and click Modify template contents.
All Envoy filters created from this template are automatically updated.
Unbind or delete templates and filters
Delete an Envoy filter by unbinding its template from the target scope, or delete the template itself to remove all associated filters.
Unbind a template from a workload
On the EnvoyFilter Template page, click Edit template for the target template. On the Bind template to workloads tab, click Bind EnvoyFilter to Workloads. In the dialog box, click Unbind next to the workload in the Bound section and click OK. The Envoy filter for that workload is automatically deleted.
Unbind a template from a namespace
On the EnvoyFilter Template page, click Edit template for the target template. On the Bind template to workloads tab, click Bind EnvoyFilter to Namespace. In the dialog box, click the namespace in the Bound section and click OK. The Envoy filter for that namespace is automatically deleted.
Delete a template
On the EnvoyFilter Template page, find the template and click Delete in the Actions column. Click OK to confirm. All Envoy filters created from this template are automatically deleted.