Upgrade an ASM instance in canary mode - Alibaba Cloud Service Mesh

A canary upgrade deploys a new control plane version alongside the existing one, letting you test it with selected workloads before promoting it cluster-wide. If issues arise, roll back without affecting other workloads.

This topic covers the full canary upgrade lifecycle: deploying the new control plane, verifying workloads, promoting the new version, upgrading the data plane, and removing the old version. If verification fails, a separate section explains how to roll back and revoke the upgrade.

How canary upgrades work

ASM uses a revision-based upgrade model. Each control plane version runs as an independent revision identified by an istio.io/rev label. During a canary upgrade, the new revision runs side by side with the existing one, but no workloads connect to it until you explicitly switch their namespace labels.

The namespace label determines which control plane version injects the sidecar proxy for pods in that namespace:

Label	Sidecar version injected
`istio-injection: enabled`	Stable version (equivalent to `istio.io/rev: stable`)
`istio.io/rev: stable`	Stable version
`istio.io/rev: canary`	Canary version
`istio.io/rev: 1-23-6`	Specific version (v1.23.6)

Version skip policy: Canary upgrades can skip at most one minor version. For example, from version 1.22, you can upgrade to version 1.23 but not directly to version 1.24.

The upgrade follows this sequence:

Deploy the canary control plane revision.
Switch a namespace to the canary revision and redeploy selected workloads to verify.
If verification succeeds, promote the canary revision to stable.
Upgrade remaining data plane workloads through rolling updates.
Unpublish the old control plane revision.

If verification fails at step 2, switch the namespace back to the stable revision and revoke the upgrade. For details, see Roll back and revoke the upgrade.

Prerequisites

Before you begin, make sure that you have:

An ASM instance of the Enterprise or Ultimate Edition, version 1.22.6.114 or later. See Create an ASM instance
An ACK cluster added to the ASM instance. See Add a cluster to an ASM instance
The Bookinfo application deployed in the cluster. See Deploy an application in an ACK cluster associated with an ASM instance

Step 1: Verify the injection policy

A canary upgrade relies on namespace labels to control which sidecar version is injected. Confirm that the injection policy is correctly configured before starting.

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 the ASM instance. In the left-side navigation pane, choose Data Plane Component Management > Sidecar Proxy injection.
On the Injection Policy Configuration page, in the Injection Policy Configuration Management section, confirm that The Label Of The Namespace Where The Pod Is Located Needs To Meet The Condition is set to Contains Istio-injection: Enabled.
Note
The istio-injection: enabled label is equivalent to istio.io/rev: stable. During a canary upgrade, istio.io/rev: stable injects the stable version, and istio.io/rev: canary injects the canary version. After the upgrade completes, both labels continue to work, so no additional relabeling is required.
The following diagram shows the initial state before the upgrade:

Step 2: Deploy the canary control plane

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 the ASM instance. In the left-side navigation pane, choose ASM Instance > Upgrade Management.
On the Upgrade Management page, click the Canary Upgrade tab. On the Control Plane tab, select a Canary Version and Create A New Server Load Balancer (CLB) Instance, then click Confirm. In the Confirm Upgrade? dialog box, click OK. In this example, the ASM instance runs version 1.22, so the canary version is v1.23.6. Deploying the canary version creates a CLB instance. If you have no specific requirements, use the default CLB specifications. For CLB pricing details, see Billing overview of CLB.
Wait a few minutes for the asynchronous deployment to complete. After the canary version is deployed, the page shows both versions side by side.

The following diagram shows the state after the canary control plane is deployed. Both control plane versions are running, but all workloads still use the stable version:

Step 3: Verify the canary version with a workload

With the canary control plane running, switch the sidecar injection label for a namespace and redeploy a workload to test the new version. This example uses reviews-v2 from the Bookinfo application.

Switch the namespace label

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 the ASM instance. In the left-side navigation pane, choose ASM Instance > Global Namespace.
On the Global Namespace page, check the Automatic Injection column. Confirm that the default namespace label is istio-injection: enabled (which corresponds to the version 1.22 sidecar).
In the Automatic Injection column for the default namespace, click Switch To Inject Version 1-23-6. In the Confirm dialog box, click OK. The namespace label switches to istio.io/rev: canary, and the data plane namespace label synchronizes immediately. New pods in this namespace receive the version 1.23 sidecar. Other namespaces remain unchanged and continue using the version 1.22 sidecar.
Note
These steps apply to namespaces that already had automatic injection enabled before the upgrade. For namespaces where injection was not yet enabled, enable it as usual and select the sidecar version during setup. ASM adds the istio.io/rev: stable or istio.io/rev: canary label based on your selection.

Redeploy the workload

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, click the cluster name. In the left-side navigation pane, choose Workloads > Deployments.
On the Deployments page, find reviews-v2. In the Actions column, choose More > Redeploy. In the Redeploy dialog box, click OK.

Verify the result

On the Deployments page, click reviews-v2. On the Pods tab, confirm that:
- The pod started successfully after the rolling update.
- The pod is running the version 1.23 sidecar proxy.
Open a browser and access the Bookinfo page. Confirm that traffic to reviews-v2 works as expected.

The following diagram shows the state after reviews-v2 is upgraded. The reviews-v2 pod connects to the canary control plane, while all other workloads remain on the stable version:

If verification succeeds, proceed to Step 4: Promote the canary version.

If verification fails, see Roll back and revoke the upgrade.

Step 4: Promote the canary version

After verifying that the canary version works as expected, promote it to stable. This makes the new control plane the default for all namespaces.

Important

After promotion, the upgrade moves to the data plane phase. All workloads must switch to the version 1.23 sidecar, and the upgrade can no longer be revoked. Complete all verification before promoting.
During promotion, ASM automatically changes all istio.io/rev: canary labels to istio.io/rev: stable. After promotion, namespaces labeled istio.io/rev: stable or istio-injection: enabled inject the version 1.23 sidecar. The istio.io/rev: canary label no longer has any effect.

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 the ASM instance. In the left-side navigation pane, choose ASM Instance > Upgrade Management.
On the Upgrade Management page, on the Canary Upgrade tab, click Upgrade Version. In the Confirm to Switch the Version? dialog box, carefully read the prompt and click OK. After promotion, existing pods with the version 1.22 sidecar continue to run normally. All newly deployed or redeployed pods receive the version 1.23 sidecar.

The following diagram shows the state after promoting the canary version:

Step 5: Upgrade the data plane

After promotion, the ASM version is 1.23. Namespaces labeled istio.io/rev=stable, istio.io/rev=1-23-6, or istio-injection=enabled all inject the version 1.23 sidecar. Perform rolling updates to upgrade the sidecar on remaining workloads.

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 the ASM instance. In the left-side navigation pane, choose ASM Instance > Upgrade Management.
On the Upgrade Management page, on the Canary Upgrade tab, click the Data Plane tab.
Upgrade your ASM gateways and workloads:
- ASM gateways: In the ASM Gateway section, find the target gateway. In the Actions column, click Rolling Upgrade. In the Confirm to Perform Rolling Upgrade? dialog box, click OK.
- Workloads: In the Workloads To Be Upgraded section, select the Namespace, find the target workload, and in the Actions column, click Rolling Upgrade. In the Confirm to Perform Rolling Upgrade? dialog box, click OK.
Note
The list only shows gateways and workloads that have not yet been upgraded. To see a global view of remaining upgrades, click Mesh Status in the left-side navigation pane.

The following diagram shows the state after all data plane workloads are upgraded:

Step 6: Unpublish the old version

After all data plane workloads and gateways are upgraded, remove the old control plane to finish the canary upgrade.

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 the ASM instance. In the left-side navigation pane, choose ASM Instance > Upgrade Management.
On the Upgrade Management page, on the Canary Upgrade tab, click Unpublish Old Version. In the Confirm to Unpublish the Old Version of the Control Plane? dialog box, click OK.

The following diagram shows the final state -- only the new control plane version is running, and all workloads use the version 1.23 sidecar:

Status after unpublishing the old version

Roll back and revoke the upgrade

If the canary version does not meet expectations during Step 3, revert the namespace label to the stable version, redeploy the affected workload, and then revoke the upgrade to remove the canary control plane.

Revert the namespace label

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 the ASM instance. In the left-side navigation pane, choose ASM Instance > Global Namespace.
On the Global Namespace page, in the Automatic Injection column, find the default namespace and click Switch to inject version 1-22-6. In the Confirm dialog box, click OK. The label changes from istio.io/rev: canary to istio.io/rev: stable. New pods in this namespace receive the version 1.22 sidecar.

Redeploy the workload

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, click the cluster name. In the left-side navigation pane, choose Workloads > Deployments.
On the Deployments page, set Namespace to default. Find reviews-v2 and in the Actions column, choose More > Redeploy. In the Redeploy dialog box, click OK.
On the Deployments page, click reviews-v2. On the Pods tab, confirm that the pod restarted successfully with the version 1.22 sidecar proxy.

Revoke the canary upgrade

Important

Before revoking, confirm that all namespaces use the stable sidecar version. You cannot revoke the upgrade if any namespace still uses the canary label.

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 the ASM instance. In the left-side navigation pane, choose ASM Instance > Upgrade Management.
On the Upgrade Management page, on the Canary Upgrade tab, click Revoke Upgrade. In the Confirm to Revoke the Upgrade? dialog box, click OK. This deletes the canary control plane (version 1.23 in this example) and retains only the stable control plane (version 1.22).

The following diagram shows the state after revoking. The instance is back to its pre-upgrade state:

After revoking, you can restart the canary upgrade from Step 2 whenever you are ready. Repeat the deploy-verify-rollback cycle with different workloads (such as reviews-v1, reviews-v2, and reviews-v3) until verification passes.