Upgrade an ASM instance with in-place and canary release - Alibaba Cloud Service Mesh

Service Mesh (ASM) updates the list of supported Istio major versions approximately every three months, along with periodic patch versions that deliver security fixes and new capabilities. Expired ASM instances no longer receive security patches, bug fixes, or full technical support. Upgrade proactively to reduce security risks and access the latest features.

ASM supports two upgrade methods:

In-place upgrade -- Upgrades the control plane to the next adjacent version. After the control plane upgrade, manually upgrade data plane gateways and restart workloads to re-inject sidecars.
Canary release -- Runs two control plane versions side by side, allowing incremental workload migration with rollback support. Supports skipping up to one minor version.

Prerequisites

Before you begin, make sure that you have:

An ASM instance

Upgrade sequence

Regardless of the method, every ASM upgrade follows this sequence:

Choose the target version and method -- Review precautions and version-specific changes.
Run the upgrade precheck -- ASM validates your instance for known incompatibilities.
Upgrade the control plane -- Apply the new version to the control plane components.
Upgrade the data plane -- Upgrade gateways and restart workloads to re-inject sidecars with the new version.
Verify -- Confirm that workloads run with the expected sidecar version.

Key concepts

Term	Description
Control plane	Manages service discovery, configuration management, policy decisions, and certificate management. In ASM, the control plane consists primarily of Istio components such as Istio-Pilot (service discovery and traffic management) and Istio-Citadel (certificate management).
Data plane	A set of Envoy proxies deployed as sidecars alongside your application containers. These proxies intercept traffic, apply routing and policy decisions from the control plane, and report telemetry data such as latency, traffic, and error rates.
In-place upgrade	Upgrades the control plane and data plane in sequence. Only adjacent-version upgrades are supported. Rollbacks are not supported.
Canary release	Deploys a new control plane version alongside the current one. Workloads are migrated incrementally by namespace labels. Rollbacks are supported during the process.

Version format

ASM versions follow this format:

<major>.<minor>.<patch>.<asm-patch>[-<sequence>-aliyun]

Example: v1.18.0.158-gc6cf0b9c-aliyun (Enterprise Edition)

Field	Description	Example
`major.minor.patch`	Open-source Istio version	1.18.0
`asm-patch`	ASM-specific patch number	158
`sequence`	Git commit hash	gc6cf0b9c

Choose an upgrade method

Consideration	In-place upgrade	Canary release
Version skip	Adjacent version only	Up to one minor version
Rollback	Not supported	Supported during the upgrade
Applicable editions	All editions	Enterprise Edition or Ultimate Edition, version 1.16.4.91 or later
Best for	Patch-level upgrades (asm-patch changes only)	Minor version upgrades where pre-migration validation is needed

For ASM instances earlier than version 1.16.4.91, only in-place upgrades are supported.

Upgrade path examples

The following table shows example paths from v1.16 to v1.18. Select a path based on your environment.

Initial version	Target version	Available methods
1.16.4.93	1.17.2.42	In-place upgrade or canary release
1.17.2.42	1.18.0.158	In-place upgrade or canary release
1.16.4.93	1.18.0.158	Canary release only

Available interfaces

Interface	Supported methods
ASM console	In-place upgrade, canary release
API	In-place upgrade only (UpgradeMeshVersion, DescribeUpgradeVersion, DescribeServiceMeshUpgradeStatus)

Usage notes

Schedule during off-peak hours. Restarting pods to re-inject sidecars causes brief service interruptions. Plan the data plane upgrade window accordingly.
Do not modify traffic rules during the upgrade. Avoid phased releases or traffic rule changes while the control plane upgrade is in progress.
Gateway upgrades trigger a rolling restart. Manually upgrading an ASM gateway restarts its pods sequentially.
Precheck coverage is limited. ASM runs a pre-upgrade compatibility check, but not all incompatible configurations or API changes are detected. Review the release notes for your target version before upgrading.
Forced upgrades for expired instances. ASM reserves the right to forcibly upgrade an expired instance to the earliest supported version at a scheduled time. Upgrade proactively to maintain control over the timing.
Automatic hot updates for patch versions. When only the asm-patch number changes (for example, v1.18.0.123 to v1.18.0.146), ASM applies hot updates automatically without notification. Data plane gateway and sidecar proxy versions remain unchanged during hot updates.

Upgrade an ASM instance (in-place)

Procedure

Log on to the ASM console. In the left-side navigation pane, choose Service Mesh > Mesh Management.
Click the name of the ASM instance. In the left-side navigation pane, choose ASM Instance > Upgrade Management.
On the Upgrade Management page, click the In-place Upgrade tab, and then click Perform Upgrade Precheck. In the Important dialog box, click OK.
After the precheck passes, click Upgrade. In the Important dialog box, click OK. The control plane upgrade begins. Wait for it to complete before proceeding.
In the Data Plane section, find the Upgrade column, select the target gateway, and click Upgrade Gateway. In the Important dialog box, click OK. The gateway pods restart in a rolling fashion.
Restart workloads to re-inject sidecars with the new version. For more information, see Redeploy workloads.

Upgrade an ASM instance (canary release)

A canary release lets you run two control plane versions simultaneously and migrate workloads incrementally. This provides a safer upgrade path for production environments because you can validate the new version before fully committing.

For the complete canary release procedure, see Use canary release to enhance upgrade stability.

Sidecar injection labels during canary release

When a canary release is active, two control plane versions coexist. Use namespace labels to control which sidecar version is injected into workloads.

Current version labels:

Label	Effect
`istio-injection=enabled`	Injects the current (stable) version sidecar
`istio.io/rev=stable`	Injects the current version sidecar
`istio.io/rev=<x-y-z>` (for example, `1-17-2`)	Injects the sidecar for the specified version

Canary version labels:

Label	Effect
`istio.io/rev=canary`	Injects the canary version sidecar
`istio.io/rev=<x-y-z>` (for example, `1-18-0`)	Injects the sidecar for the specified version (recommended)

Important

Do not add both istio-injection and istio.io/rev labels to the same namespace. These labels are mutually exclusive.

Example: To upgrade from 1.17.2.42 to a 1.18.0 version, label a test namespace to use the canary sidecar:

kubectl label namespace <test-namespace> istio.io/rev=1-18-0 --overwrite

After verifying that workloads in the test namespace are healthy, apply the label to the remaining namespaces.

FAQ

Does an in-place upgrade affect data plane traffic?

No. An in-place upgrade only affects the control plane. Existing sidecar proxies and gateways continue to handle traffic normally until you manually upgrade them.

How many upgrade steps are needed to reach my target version?

In-place upgrades only support adjacent-version jumps, so reaching a version two minor releases ahead requires two separate upgrades. Canary releases support skipping one minor version, which may reduce the total steps. Refer to the upgrade path table above to plan your route.

After upgrading ASM, do I need to upgrade the associated ACK cluster?

Check ASM and ACK version compatibility to determine whether an ACK cluster upgrade is needed. If so, see Manually upgrade a cluster.

How do I upgrade sidecars injected before a canary version became official?

On the Upgrade Management page, click the Canary Upgrade tab, then click the Data plane tab. In the Workloads To Be Upgraded section, click Rolling Upgrade next to the target workload to trigger a rolling update of its deployment.

Alibaba Cloud Service Mesh:Upgrade an ASM instance