Precautions and instructions for upgrading an ASM instance - Alibaba Cloud Service Mesh

To ensure business continuity and prevent security and stability risks from expired instances, Service Mesh (ASM) supports in-place upgrades and canary releases to upgrade the control plane and data plane. This topic describes the precautions, instructions, upgrade paths, methods, and procedures for upgrading an ASM instance.

Prerequisites

An ASM instance is created.

Terms

Expand to view the descriptions of in-place upgrade, canary release, control plane, and data plane

Term	Description
In-place upgrade	Phased and gradual upgrades of the control plane and data plane are supported. You can upgrade the control plane in the ASM console. After the control plane is upgraded, you must manually upgrade the sidecar proxies and gateways on the data plane.
Canary release	A rollback can be performed during a canary release. You can run a new version of the control plane and migrate some services to the new version. After you verify that the services run properly, you can migrate the remaining services to the new version. You can perform a rollback if an issue is found during the verification process.
Control plane	The control plane is responsible for managing and configuring various policies and rules of the Service Mesh. Its core responsibilities include the following aspects: Service discovery: maintains service registration information for the data plane. This way, services can discover and communicate with each other. Configuration management: provides a unified API for you to centrally configure and manage traffic rules, policies, and other related settings of the Service Mesh. Policy decision: defines and executes access control, throttling, fault injection, and routing policies. Certificate management: manages certificates and keys for inter-service communication and implements encrypted communication. In ASM, the control plane mainly consists of Istio components. For example, Istio-Pilot implements service discovery and traffic management, and Istio-Citadel manages the certificates for secure communication.
Data plane	The data plane consists of a series of lightweight network proxies. These proxies are deployed as sidecars of services and run in the same pod as application containers. Its core responsibilities include the following aspects: Traffic interception: intercepts all network traffic that flows into and out of a pod. Traffic routing: performs specific traffic forwarding, load balancing, and routing decisions based on the configurations of the control plane. Data reporting: collects and reports data about inter-service communication, such as latency, traffic, and error rates. Policy execution: implements access control, rate limiting, and other policies. In ASM, the data plane is mainly implemented using Envoy proxies provided by Istio. Envoy proxies are deployed close to application services in the form of sidecars and provide high-performance network proxy capabilities.

Why are upgrades required?

ASM typically updates the list of supported Istio major versions every three months. After a major version is released, ASM occasionally releases patch versions, such as 1.19.x.y, to provide new features and fix vulnerabilities. Expired ASM instances pose security and stability risks. We recommend that you upgrade your ASM instances in a timely manner. For more information about the versions supported by ASM, see Versioning mechanism.

Proactively upgrading your ASM instances provides the following benefits:

Reduced security and stability risks: Security and stability vulnerabilities are continuously fixed as ASM versions iterate. Using expired ASM instances for an extended period may pose security and stability risks to your business.
Improved maintenance support: For expired instance versions, ASM no longer provides security patches or bug fixes and cannot guarantee the quality of technical support. You can receive improved technical support and customer service when you use new ASM versions.
Access to new features: As open source Istio evolves, new versions provide new features and improvements. ASM adapts to these new versions to provide a better experience for developers and for operations and maintenance (O&M).

Precautions and instructions for upgrades

Precautions

To upgrade a mesh, you must manually restart the pods on the data plane to re-inject sidecars of the new version. We recommend that you perform the upgrade during off-peak hours.
If you manually upgrade an ASM gateway, a rolling restart is triggered.
During an upgrade, do not perform operations such as phased release or traffic rule configuration.
When you perform an in-place upgrade of an ASM instance, ASM performs a pre-upgrade check on your instance. However, this check does not ensure that all incompatible feature configurations and API operations are detected. You can stay informed about version release information using help documents, console information, and internal messages. Before you upgrade an instance, we recommend that you review the upgrade precautions for the corresponding version.
For security reasons, ASM provides the following mechanisms:
- ASM reserves the right to forcibly upgrade an expired instance to the earliest supported version at a specified time after the instance version expires. We recommend that you upgrade the instance in advance as described in this topic.
- For patch version upgrades, such as from v1.18.0.123 to v1.18.0.146, the system periodically performs automatic hot updates without sending notifications. During an automatic hot update, the versions of the data plane gateways and sidecar proxies remain unchanged.

Instructions on in-place upgrades

When you perform an in-place upgrade, you can only upgrade an ASM instance to an adjacent version. Cross-version upgrades and rollbacks are not supported.

Instructions on canary releases

Compared with an in-place upgrade, a canary release lets you verify a new version before you switch to it. This provides a more secure upgrade method for your business. A canary release supports upgrades across a maximum of one minor version and supports rollbacks during the upgrade process.

Type	Description
Applicable versions	Enterprise Edition or Ultimate Edition instances of version 1.16.4.91 or later.
Scenarios	Scenarios where you upgrade an instance across one minor version. For example, you can upgrade an instance from 1.16.4 to 1.17.2. Scenarios where you upgrade an instance when the minor version changes. For example, you can upgrade an instance from 1.16.4 to 1.17.2 or 1.18.0. You can upgrade an instance across a maximum of one minor version. Note If only the asm-patch version changes, we recommend that you perform an in-place upgrade.
Version format	The version of an ASM instance is in the following format: <major>.<minor>.<patch>.<asm-patch>[-<sequence>-aliyun]. Example: v1.18.0.158-gc6cf0b9c-aliyun (Enterprise Edition). The following list describes the fields in the format: major: the major version. minor: the minor version. patch: the patch version. <major>.<minor>.<patch>: the version of the open source Istio. Example: 1.18.0. asm-patch: the patch version released by ASM based on the open source version. For example, in the version number of 1.18.0.158, 158 indicates the patch version released by ASM. sequence: the Git commit for the code of the version.

Instructions on Sidecar injection labels

After you enable the canary release feature for an ASM instance, two versions of the instance exist on the control plane at the same time. For example, if you upgrade an ASM instance from 1.17.2.42 to a specific 1.18.0 version using a canary release, both versions 1.17.2 and 1.18.0 are available on the control plane at the same time.

During a canary release, you can add an injection label to a namespace in a Kubernetes cluster to specify the version of sidecars to be injected into the workloads in the namespace. The default label is istio-injection=enabled, which injects the current version.

The following section describes the mapping between the injected sidecar version and the namespace label when two versions exist at the same time:

Current version
- The sidecar injected by the istio-injection=enabled label corresponds to the current version of ASM and connects to the control plane of the current version.
- Add the istio.io/rev=$revision label to the namespace to specify the sidecar version to inject. The format of the revision variable is x-y-z, such as 1-17-2.
- Add the istio.io/rev=stable label to the namespace to specify that the sidecar version to inject is the current version of ASM.
Important
You cannot add both the istio-injection and istio.io/rev labels to a namespace at the same time.
Canary version
If a business service needs to be injected with a sidecar that corresponds to the canary version, you can add the istio.io/rev=$revision or istio.io/rev=canary label to the namespace. The format of $revision is x-y-z, such as 1-18-0. We recommend that you use the istio.io/rev=$revision label.
For more information about how to perform a canary release, see Use canary release to enhance upgrade stability.

Upgrade paths, methods, and processes

Upgrade paths

The example in this section uses an upgrade from v1.16 to v1.18 to describe the upgrade path. This example is for reference only. You can select an upgrade path based on your actual environment.

Initial version	Destination version	Upgrade method
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

Upgrade methods

ASM console: supports in-place upgrades and canary releases. For more information, see Procedure.
API: supports in-place upgrades. For more information, see UpgradeMeshVersion, DescribeUpgradeVersion, and DescribeServiceMeshUpgradeStatus.

Upgrade process

Confirm the destination version and upgrade method. Familiarize yourself with the upgrade precautions and instructions before you proceed.

Procedure

In-place 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, click the In-place Upgrade tab, and then click Perform Upgrade Precheck. In the Important dialog box that appears, click OK.
After the upgrade precheck is passed, click Start Upgrade. In the Important dialog box, click OK.
In the Data Plane section, find the Upgrade column, select the target gateway, and click Upgrade Gateway. In the Important dialog box, click OK.
Restart workloads as needed. For more information, see Redeploy workloads.

Canary release

For more information, see Use canary release to enhance upgrade stability.

FAQ about upgrades

When a canary version is switched to the official version, the sidecar injected into the previously deployed service is of an earlier version. How do I upgrade the sidecar to the new version?

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

Does an in-place upgrade affect the traffic of existing services?

An in-place upgrade affects only the control plane, not the traffic on the data plane.

How many times does an ASM instance need to be upgraded to reach the destination version?

In-place upgrades support only upgrades between adjacent major versions. Canary releases support upgrades across a maximum of one minor version. You can calculate the number of required upgrades as needed.

Can I select any upgrade method for each version of an ASM instance?

For ASM instances of versions earlier than 1.16.4.91, only in-place upgrades are supported. For ASM instances of version 1.16.4.91 or later, both in-place upgrades and canary releases are supported.

After an ASM instance is upgraded, to which version does the corresponding ACK cluster need to be upgraded?

You can refer to ASM and ACK version compatibility and upgrade the cluster as needed. For more information about how to upgrade an ACK cluster, see Manually upgrade a cluster.

Alibaba Cloud Service Mesh:Upgrade an ASM instance