Precautions and usage notes for updating an ASM instance - Alibaba Cloud Service Mesh

To prevent security and stability risks of expired instances and ensure business continuity, Service Mesh (ASM) allows you to perform an in-place update or a canary release to update the control plane and user plane of an ASM instance. This topic provides the precautions and usage notes, update path, update process, and procedure for updating an ASM instance.

Prerequisites

An ASM instance is created.

Terms

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

Term	Description
In-place update	Phased and gradual updates of the control plane and data plane are supported. You can update the control plane in the ASM console. After the control plane is updated, you must manually update 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 ASM instance. 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 users to centrally configure and manage traffic rules, policies, and other related settings of the ASM instance. Policy decision: defines and implements access control, throttling, fault injection, and routing policies. Certificate management: manages certificates and keys for communication between services 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 pods as application containers. Its core responsibilities include the following aspects: Traffic interception: redirects all network traffic to and from the pods in the ASM instance. 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 volume, and error rates. Policy execution: performs access control, throttling, and other policies. In ASM, the data plane is mainly implemented by using Envoy proxies provided by Istio. Envoy proxies are deployed close to application services in the form of sidecars and provide network proxy capabilities with high performance.

Why are updates 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. ASM instances of expired versions pose security and stability risks. We recommend that you update ASM instances in a timely manner. For more information about the versions supported by ASM, see Support for Istio versions.

Proactively updating ASM instances brings the following benefits:

Reduced security and stability risks: As ASM versions iterate, security and stability vulnerabilities are continuously fixed. Long-term use of expired ASM instances may pose security and stability risks to your business.
Better maintenance support: For expired instance versions, ASM no longer provides security patches and problem fixes, and cannot guarantee the quality of technical support. You can enjoy improved technical support and customer service when using new ASM versions.
Use of the new features of new versions: With the evolution of open source Istio versions, new versions provide new features and improvements. ASM will also adapt to the new versions to bring you a better development and O&M experience.

Precautions and usage notes

Precautions

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

Usage notes of in-place update

When you perform an in-place update, you can only update an ASM instance to a neighboring version. Cross-version updates and rollbacks are not supported.

Usage notes of canary release

A canary release allows you to verify a new version before the update. After you verify that the features of the new version work as expected, you can switch to the new version. This is different from an in-place update and serves as a more secure update option for your business. A canary release supports updates across a maximum of one minor version and supports rollbacks during an update process.

Type	Description
Instance editions and versions	Your ASM instance must be of Enterprise Edition or Ultimate Edition and its version is v1.16.4.91 or later.
Scenarios	When you update an ASM instance, you can skip the subsequent minor version. For example, you can directly update an ASM instance from v1.16.4 to v1.17.2. You can update your ASM instance from one minor version to another to use updated or new features. For example, you can update an ASM instance from v1.16.4 to v1.17.2 or v1.18.0. You can skip at most one minor version. Note If ASM releases a revision version, we recommend that you perform an in-place update of your ASM instance.
Version formats	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 revision version of the open source Istio. <major>.<minor>.<patch>: the version of the open source Istio. Example: 1.18.0. asm-patch: the revision version released by ASM based on the open source version. For example, in the version number of 1.18.0.158, 158 indicates the revision version released by ASM. sequence: the git commit command used for the code of the version.

Usage notes of sidecar proxy injection labels

After you enable the canary release feature for your ASM instance, two versions of the ASM instance exist on the control plane at the same time. For example, if you update an ASM instance from v1.17.2.42 to v1.18.0.x by implementing a canary release, both v1.17.2 and v1.18.0 are available for the ASM instance 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 sidecar proxies to be injected into the workloads in the namespace. By default, the istio-injection=enabled label is used to enable sidecar proxy injection. The system injects sidecar proxies into the namespace based on the version of the ASM instance.

The following section describes the version of the sidecar proxies to be injected into a namespace based on the label that you add to the namespace if two versions of an ASM instance exist at the same time.

Current version
- If you add the istio-injection=enabled label to the namespace, the sidecar proxies to be injected are of the same version as that of the ASM instance. The sidecar proxies are connected to the Istio control plane of the ASM instance.
- If you add the istio.io/rev=$revision label to the namespace, you must set the revision variable to specify the version of the sidecar proxies to be injected. The format of the revision variable is x-y-z. Example: 1-17-2.
- If you add the istio.io/rev=stable label to the namespace, the sidecar proxies to be injected are of the same version as that of the ASM instance.
Important
You cannot add both the istio-injection and istio.io/rev labels to a namespace at the same time.
Canary release version
If you want to inject a sidecar proxy that corresponds to the canary release version into the namespace of a service, you can add the istio.io/rev=$revision or istio.io/rev=canary label to the namespace. $revision indicates the version of the sidecar proxy, and its format is x-y-z. Example: 1-18-0. We recommend that you use the istio.io/rev=$revision label.
For more information, see Use canary release to enhance update stability.

Update path, method, and process

Update path

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

Initial version	Destination version	Update method
1.16.4.93	1.17.2.42	In-place update or canary release
1.17.2.42	1.18.0.158	In-place update or canary release
1.16.4.93	1.18.0.158	Canary release

Update method

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

Update process

Confirm the destination version and update method. Be familiar with the update precautions and usage notes before proceeding with an update.

Procedure

In-place update

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 In-place Upgrades tab of the Upgrade Management page, click Perform Upgrade Precheck. In the Note message, click OK.
After the upgrade precheck passes, click Upgrade. In the Note message, click OK.
In the Upgrade column of the Data Plane section, select the gateway that you want to update and click Upgrade Gateway. In the Note message, click OK.
Restart workloads based on your business requirements. For more information, see the "(Optional) Redeploy workloads" section in Configure sidecar proxies.

Canary release

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

FAQ about updates

When I switch a canary release version to an official version, the sidecar proxy injected into the previously deployed service is of the previous version. How do I update the version of the sidecar proxy?

On the Upgrade Management page, click the Canary Upgrade tab, and then click the Data plane tab. In the Workload to be upgraded section, find the workload that you want to update and click Rolling Upgrade in the Actions column to enable rolling updates for the service.

Do in-place updates affect the access of existing services?

In-place updates affect only the control plane, not the traffic on the data plane.

How many updates do I need to perform to update an ASM instance to a destination version?

In-place updates can be used only for updates between consecutive major versions. During a canary release, you can skip only one minor version at most. You can calculate the number of update times required based on the actual situation.

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

If the version of an ASM instance is earlier than v1.16.4.91, only in-place updates are supported. If the version of an ASM instance is v1.16.4.91 or later, in-place updates and canary releases are supported.

Which version do I need to update an ACK cluster to after its ASM instance is updated?

You can refer to Support status of Istio releases and perform an update based on your business requirements. For more information about how to update a Container Service for Kubernetes (ACK) cluster, see Update an ACK cluster.

References

You can diagnose ASM instances for potential issues in a timely manner. The check items include the versions of data-plane components, service ports, associated services, labels of applications and versions, destination addresses, and virtual service conflicts. For more information, see Diagnose ASM instances.
Container Intelligence Service (CIS) allows you to diagnose nodes, pods, Services, Ingresses, memory, and networks with a few clicks to locate issues in your ACK cluster. For more information, see Work with cluster diagnostics.
For more information about the latest features of ASM, see Release notes.