Plan an upgrade

Note: This guide only supports Cloud Service Mesh with Istio APIs and doesnot support Google Cloud APIs. For more information see,Cloud Service Mesh overview.

This page provides information to help you plan a Cloud Service Mesh upgrade. Werecommend that you also review theIstio upgrade notes.

About canary upgrades

We recommend that you upgrade Cloud Service Mesh by first running a canary deploymentof the new control plane. With a canary upgrade,asmcli installs a newrevision of the controlplane alongside the old control plane. Both the old and new control planesare labeled with arevision label, which serves as an identifier for thecontrol planes.

To migrate workloads to the new control plane:

  1. Set the new control plane'srevision label on one of your namespaces.

  2. Perform a rolling restart. The restart re-injects the sidecar proxies in thePods so that the proxies use the new control plane.

  3. Monitor the effect of the upgrade on the workloads. If needed to test yourapplication, repeat the previous steps.

  4. After testing your application, you can migrate all traffic to the newcontrol plane or rollback to the old control plane.

A canary upgrade is much safer than doing an in-place upgrade where the newcontrol plane replaces the old control plane. For detailed steps, seeSwitch to the new control plane.

Caution: In-place upgrades are not supported and doing an in-place upgrade toversion 1.24 will cause downtime due to a breaking change in the pilot certprovider. If you do in-place upgrade, all workloads will need to be redeployedpost upgrade to connect to the control plane.

Customize the control plane

If you customized the previous installation, you need the same customizationswhen you upgrade Cloud Service Mesh. If you customized the installation by addingthe--set values flag toistioctl install, you must add those settings toanIstioOperator YAML file, referred to as an overlay file. You specify theoverlay file by using the--custom_overlay option with the filename when yourunasmcli.

Caution: Omitting the overlay file results in a successful installation.However, your service mesh has a different configuration than you intendedbecause the omitted values are reset back to the defaults whenthe control plane is redeployed.

Theasmcli directory in GitHub contains many overlay files. These files contain common customizationsto the default configuration. You can use these files as they are, or you canmake additional changes to them as needed. Some of the files are required toenable optional Cloud Service Mesh features.Theanthos-service-mesh package is downloaded when you runasmcli tovalidate your project and cluster.

When you install Cloud Service Mesh usingasmcli install, youcan specify one or more overlay files with the--option or--custom_overlay.If you don't need to make any changes to the files in theanthos-service-meshrepository, you can use--option, and the script fetches the file from GitHubfor you. Otherwise, you can make changes to the overlay file, and then use the--custom_overlay option to pass it to theasmcli.

Choose a certificate authority

If your current Cloud Service Mesh installation usesCloud Service Mesh certificate authority as the certificate authority (CA) for issuingmutual TLS (mTLS)certificates, we recommend that you continue to use Cloud Service Mesh certificate authorityfor the following reasons:

  • Cloud Service Mesh certificate authority is a highly reliable and scalable service that isoptimized for dynamically scaled workloads.
  • With Cloud Service Mesh certificate authority, Google manages the security and availabilityof the CA backend.
  • Cloud Service Mesh certificate authority lets you rely on a single root of trust acrossclusters.

If your current Cloud Service Mesh installation usesIstio CA (previously called "Citadel"), you can switch to Cloud Service Mesh certificate authority whenyou upgrade, but you need to schedule downtime. During the upgrade, mTLS trafficis interrupted until all workloads are switched to using the new control planewith Cloud Service Mesh certificate authority.

Platform note: CA Service is only supported on the following platforms: GKE clusters on Google Cloud, Google Distributed Cloud (software only) for VMware, and Distributed Cloud. If you runasmcli install and specify--ca gcp_cas on other platforms, the installation appears successful, but your workloads will fail to start.

Certificates from Cloud Service Mesh certificate authority include the following data aboutyour application's services:

Important: The certificates issued by Cloud Service Mesh certificate authority should only be used to enablesecure service-to-service communication within your service mesh, and not beused for any other purpose. These certificates are sent whenever servicesattempt to communicate with each other using mutual TLS. Make sure that youdon't inadvertently expose confidential information by using these certificateswhen communicating outside your service mesh.

Identifying your CA

When you runasmcli install to upgrade, you specify the CA thatasmclishould enable on the new control plane.

Changing CAs causes downtime when your deploy workloads to the newcontrol plane. If you can't schedule downtime, make sure to specify that same CAfor the new control plane that the old control plane uses. If you aren't surewhich CA is enabled on your mesh, run the following commands:

  1. Get a list of Pods from one of your namespaces:

    kubectl get pods -nNAMESPACE

  2. ReplacePOD_NAME with the name of one of your Pods inthe following command:

    kubectl get podPOD_NAME -nNAMESPACE -o yaml | grep CA_ADDR -A 1

    If Cloud Service Mesh certificate authority is enabled on the namespace, you see thefollowing output:

    - name: CA_ADDR  value: meshca.googleapis.com:443

Prepare gateway configuration

Cloud Service Mesh gives you the option to deploy and manage gateways as part of yourservice mesh. A gateway describes a load balancer operating at the edge of themesh receiving incoming or outgoing HTTP/TCP connections. Gateways are Envoyproxies that provide you with fine-grained control over traffic entering andleaving the mesh.

asmcli doesn't install theistio-ingressgateway. We recommend that youdeploy and manage the control plane and gateways separately. For moreinformation, seeInstalling and upgrading gateways.

Upgrade your platform (optional)

As a best practice, you should upgrade Cloud Service Mesh to the latestsupported versionthat also supports your current platform. Then, upgrade your environment sothat it is within the range ofsupported platforms and Kubernetes versions.Lastly, if needed, upgrade to the latestsupported version of Cloud Service Mesh.

What's next?

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.