Upgrade Cloud Service Mesh

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 explains how to:

  • Runasmcli to upgrade from Cloud Service Mesh to Cloud Service Mesh1.23.6.

  • Optionally, deploy an ingress gateway.

  • Do a canary upgrade to migrate your workloads to the new control plane.

The Cloud Service Mesh version that you can upgrade from differs by platform.

GKE

You can upgrade directly to Cloud Service Mesh 1.23.6-asm.11 on Google Kubernetes Enginefrom the following versions:

1.21+

On-premises

You can upgrade directly to Cloud Service Mesh 1.23.6-asm.11 on Google Distributed Cloud (software only) for VMwareand Google Distributed Cloud (software only) for bare metal from the following versions:

1.21+

GKE on AWS

You can upgrade directly to Cloud Service Mesh 1.23.6-asm.11 on GKE on AWSfrom the following versions:

1.21+

GKE on Azure

GKE on Azure only supports Cloud Service Mesh 1.16. Upgrades fromearlier versions of Cloud Service Mesh are not supported.

Amazon EKS

If you have Cloud Service Mesh 1.7 installed on EKS, you will need toinstall Cloud Service Mesh 1.23on a new cluster. Upgrades from Cloud Service Mesh 1.7 to Cloud Service Mesh1.23 aren't supported.

Microsoft AKS

If you have Cloud Service Mesh 1.7 installed on AKS, you will need toinstall Cloud Service Mesh 1.23on a new cluster. Upgrades from Cloud Service Mesh 1.7 to Cloud Service Mesh1.23 aren't supported.

Before you begin

Warning: GitOps tools (including Config Sync, Argo CD, Terraform,and Jenkins) may interfere with your Cloud Service Mesh installation,migration, or upgrade processes. For best results, disable your GitOps toolsbefore you install, migrate, or upgrade Cloud Service Mesh.

Before you begin, make sure that you:

Control plane customizations

If you customized the previous installation, you need the same customizationswhen you upgrade to a new Cloud Service Mesh version or migrate from Istio. If youcustomized the installation by adding the--set values flag toistioctl install, you must add those settings to anIstioOperator YAML file,referred to as anoverlay file. You specify the overlayfile by using the--custom_overlay option with the filename when you run thescript. The script passes the overlay file toistioctl install.

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 and ingress gateway are redeployed.

Certification Authority

Changing the certificate authority (CA) during an upgrade causes downtime.During the upgrade, mTLS traffic is interrupted until all workloads areswitched to using the new control plane with the new CA.

Upgrade Cloud Service Mesh

The following outlines how to upgrade Cloud Service Mesh:

  1. If you are upgrading a multi-cluster mesh on GKE that usesCloud Service Mesh certificate authority, runasmcli create-mesh to configure themulti-cluster mesh to trustfleet workload identityfor no down time cross-cluster load balancing during the upgrade.

  2. Runasmcli install to install Cloud Service Mesh on a single cluster. See thefollowing sections for command line examples. The examples contain bothrequired arguments and optional arguments that you might find useful. Werecommend that you always specify theoutput_dir argument so thatyou can easily locate sample gateways and tools such asistioctl. Seethe navigation bar on the right for a list of the examples.

  3. Optionally,install or upgrade an ingress gateway. Bydefault,asmcli doesn't install theistio-ingressgateway. We recommendthat you deploy and manage the control plane and gateways separately. If youneed the defaultistio-ingressgateway installed with the in-clustercontrol plane, include the--option legacy-default-ingressgatewayargument.

  4. To complete setting up Cloud Service Mesh, you need to enable automatic sidecarinjection anddeploy or redeploy workloads.

Configure the multi-cluster mesh to trust fleet workload identity

If you are upgrading a multi-cluster mesh on GKE thatuses Cloud Service Mesh certificate authority as the certificate authority, you need to runasmcli create-mesh before upgrading each cluster. This command configuresCloud Service Mesh certificate authority to use the fleet workload identity pool,FLEET_PROJECT_ID.svc.id.goog, as the trust domain after youupgrade. Theasmcli create-mesh command:

  • Registers all clusters to the same fleet.
  • Configures the mesh to trust the fleet workload identity.
  • Creates remote secrets.

You can either specify the URI for each cluster or the path to thekubeconfig file.

Cluster URI

In the following command, replaceFLEET_PROJECT_ID withthe project ID of thefleet host projectand the cluster URI with the cluster name, zone or region, and project IDfor each cluster.

./asmclicreate-mesh\FLEET_PROJECT_ID\PROJECT_ID_1/CLUSTER_LOCATION_1/CLUSTER_NAME_1\PROJECT_ID_2/CLUSTER_LOCATION_2/CLUSTER_NAME_2# \# Add a line for each cluster in the mesh

kubeconfig file

In the following command, replaceFLEET_PROJECT_ID withthe project ID of thefleet host projectandPATH_TO_KUBECONFIG with the path to eachkubeconfig file.

./asmclicreate-mesh\FLEET_PROJECT_ID\PATH_TO_KUBECONFIG_1\PATH_TO_KUBECONFIG_2# \# Add a line for each cluster in the mesh

Upgrade with default features and Mesh CA

This section shows how to runasmcli to upgrade Cloud Service Mesh with thedefaultsupported features for your platformand enable Cloud Service Mesh certificate authority as the certificate authority.

GKE

Run the following command to upgrade the control plane with defaultfeatures and Cloud Service Mesh certificate authority. Enter your values in the providedplaceholders.

./asmcli install \  --project_idPROJECT_ID \  --cluster_nameCLUSTER_NAME \  --cluster_locationCLUSTER_LOCATION \  --fleet_idFLEET_PROJECT_ID \  --output_dirDIR_PATH \  --enable_all \  --ca mesh_ca
  • --project_id,--cluster_name, and--cluster_location Specify the project ID that the cluster is in, the cluster name, and either the cluster zone or region.
  • --fleet_id The project ID of the fleet host project. If you don't include this option,asmcli uses the project that the cluster was created in when registering the cluster.
  • --output_dir Include this option to specify a directory whereasmcli downloads theanthos-service-mesh package and extracts the installation file, which containsistioctl, samples, and manifests. Otherwiseasmcli downloads the files to atmp directory. You can specify either a relative path or a full path. The environment variable$PWD doesn't work here.Note: Make note of this--output_dir directory. You will need to reference it when deploying gateways.
  • --enable_all Allows the script to:
    • Grant required IAM permissions.
    • Enable the required Google APIs.
    • Set a label on the cluster that identifies the mesh.
    • Register the cluster to the fleet if it isn't already registered.
  • --ca mesh_ca Use Cloud Service Mesh certificate authority as thecertificate authority. Changing certificate authorities during anupgrade causes downtime.asmcliconfiguresCloud Service Mesh certificate authority to usefleetworkload identity

Other GKE Enterprise clusters

Run the following commands on other GKE Enterprise clusters to upgrade thecontrol plane with default features and Cloud Service Mesh certificate authority. Enteryour values in the provided placeholders.

  1. Set the current context to your user cluster:

    kubectl config use-contextCLUSTER_NAME

  2. Runasmcli install:

    ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --ca mesh_ca
    • --fleet_id The project ID of the fleet host project.
    • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
    • --output_dir Include this option to specify a directory whereasmcli downloads theanthos-service-mesh package and extracts the installation file, which containsistioctl, samples, and manifests. Otherwiseasmcli downloads the files to atmp directory. You can specify either a relative path or a full path. The environment variable$PWD doesn't work here.
    • --platform multicloud Specifies that the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
    • --enable_all Allows the script to:
      • Grant required IAM permissions.
      • Enable the required Google APIs.
      • Set a label on the cluster that identifies the mesh.
      • Register the cluster to the fleet if it isn't already registered.
    • --ca mesh_ca Use Cloud Service Mesh certificate authority as thecertificate authority. Changing certificate authorities during anupgrade causes downtime.asmcliconfiguresCloud Service Mesh certificate authority to usefleetworkload identity

Upgrade default features with CA Service

This section shows how to runasmcli to upgrade Cloud Service Mesh with thedefaultsupported features for your platformand enableCertificate Authority Service.

GKE

Run the following command to upgrade the control plane with defaultfeatures and Certificate Authority Service. Enter your values in the providedplaceholders.

./asmcliinstall\--project_idPROJECT_ID\--cluster_nameCLUSTER_NAME\--cluster_locationCLUSTER_LOCATION\--fleet_idFLEET_PROJECT_ID\--output_dirDIR_PATH\--enable_all\--cagcp_cas\--ca_poolprojects/PROJECT_NAME/locations/ca_region/caPools/CA_POOL
  • --project_id,--cluster_name, and--cluster_location Specify the project ID that the cluster is in, the cluster name, and either the cluster zone or region.
  • --fleet_id The project ID of the fleet host project. If you don't include this option,asmcli uses the project that the cluster was created in when registering the cluster.
  • --output_dir Include this option to specify a directory whereasmcli downloads theanthos-service-mesh package and extracts the installation file, which containsistioctl, samples, and manifests. Otherwiseasmcli downloads the files to atmp directory. You can specify either a relative path or a full path. The environment variable$PWD doesn't work here.Note: Make note of this--output_dir directory. You will need to reference it when deploying gateways.
  • --enable_all Allows the script to:
    • Grant required IAM permissions.
    • Enable the required Google APIs.
    • Set a label on the cluster that identifies the mesh.
    • Register the cluster to the fleet if it isn't already registered.
  • --ca gcp_cas Use Certificate Authority Service as thecertificate authority. Changing certificate authorities during anupgrade causes downtime.asmcliconfiguresCertificate Authority Service to usefleetworkload identity
  • --ca_pool The full identifier for the Certificate Authority ServiceCA Pool.

On-premises

Run the following commands on Google Distributed Cloud (software only) for VMware orGoogle Distributed Cloud (software only) for bare metal to upgrade the control plane with defaultfeatures and Certificate Authority Service. Enter your values in the providedplaceholders.

  1. Set the current context to your user cluster:

    kubectl config use-contextCLUSTER_NAME

  2. Runasmcli install:

    ./asmcliinstall\--kubeconfigKUBECONFIG_FILE\--fleet_idFLEET_PROJECT_ID\--output_dirDIR_PATH\--enable_all\--cagcp_cas\--platformmulticloud\--ca_poolprojects/PROJECT_NAME/locations/ca_region/caPools/CA_POOL
    • --fleet_id The project ID of the fleet host project.
    • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
    • --output_dir Include this option to specify a directory whereasmcli downloads theanthos-service-mesh package and extracts the installation file, which containsistioctl, samples, and manifests. Otherwiseasmcli downloads the files to atmp directory. You can specify either a relative path or a full path. The environment variable$PWD doesn't work here.
    • --platform multicloud Specifies that the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
    • --enable_all Allows the script to:
      • Grant required IAM permissions.
      • Enable the required Google APIs.
      • Set a label on the cluster that identifies the mesh.
      • Register the cluster to the fleet if it isn't already registered.
    • --ca gcp_cas Use Certificate Authority Service as thecertificate authority. Changing certificate authorities during anupgrade causes downtime.asmcliconfiguresCertificate Authority Service to usefleetworkload identity
    • --ca_pool The full identifier for theCertificate Authority ServiceCA Pool.

Upgrade default features with Istio CA

This section shows how to runasmcli to upgrade Cloud Service Mesh with thedefaultsupported features for your platformand enable Istio CA.

GKE

Run the following command to upgrade the control plane with defaultfeatures and Istio CA. Enter your values in the provided placeholders.

./asmcli install \  --project_idPROJECT_ID \  --cluster_nameCLUSTER_NAME \  --cluster_locationCLUSTER_LOCATION \  --fleet_idFLEET_PROJECT_ID \  --output_dirDIR_PATH \  --enable_all \  --ca citadel
  • --project_id,--cluster_name, and--cluster_location Specify the project ID that the cluster is in, the cluster name, and either the cluster zone or region.
  • --fleet_id The project ID of the fleet host project. If you don't include this option,asmcli uses the project that the cluster was created in when registering the cluster.
  • --output_dir Include this option to specify a directory whereasmcli downloads theanthos-service-mesh package and extracts the installation file, which containsistioctl, samples, and manifests. Otherwiseasmcli downloads the files to atmp directory. You can specify either a relative path or a full path. The environment variable$PWD doesn't work here.Note: Make note of this--output_dir directory. You will need to reference it when deploying gateways.
  • --enable_all Allows the script to:
    • Grant required IAM permissions.
    • Enable the required Google APIs.
    • Set a label on the cluster that identifies the mesh.
    • Register the cluster to the fleet if it isn't already registered.
  • --ca citadel Use Istio CA. Changing certificateauthorities during an upgrade causes downtime.

On-premises

Run the following commands on Google Distributed Cloud (software only) for VMware orGoogle Distributed Cloud (software only) for bare metal to upgrade the control plane withdefault features and Istio CA. Enter your values in the providedplaceholders.

  1. Set the current context to your user cluster:

    kubectl config use-contextCLUSTER_NAME

  2. Runasmcli install:

    ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --ca citadel \  --ca_certFILE_PATH \  --ca_keyFILE_PATH \  --root_certFILE_PATH \  --cert_chainFILE_PATH
    • --fleet_id The project ID of the fleet host project.
    • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
    • --output_dir Include this option to specify a directory whereasmcli downloads theanthos-service-mesh package and extracts the installation file, which containsistioctl, samples, and manifests. Otherwiseasmcli downloads the files to atmp directory. You can specify either a relative path or a full path. The environment variable$PWD doesn't work here.
    • --platform multicloud Specifies that the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
    • --enable_all Allows the script to:
      • Grant required IAM permissions.
      • Enable the required Google APIs.
      • Set a label on the cluster that identifies the mesh.
      • Register the cluster to the fleet if it isn't already registered.
    • --ca citadel Use Istio CA as the certificate authority.
    • --ca_cert The intermediate certificate
    • --ca_key The key for the intermediate certificate
    • --root_cert The root certificate
    • --cert_chain The certificate chain

AWS

Run the following commands on GKE on AWS to upgrade the controlplane with default features and Istio CA. Enter your values in theprovided placeholders. You can choose to enable Ingress for the publicsubnet or the private subnet.

Public

  1. Set the current context to your user cluster:

    kubectl config use-contextCLUSTER_NAME

  2. Runasmcli install:

    ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --ca citadel \  --ca_certFILE_PATH \  --ca_keyFILE_PATH \  --root_certFILE_PATH \  --cert_chainFILE_PATH
    • --fleet_id The project ID of the fleet host project.
    • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
    • --output_dir Include this option to specify a directory whereasmcli downloads theanthos-service-mesh package and extracts the installation file, which containsistioctl, samples, and manifests. Otherwiseasmcli downloads the files to atmp directory. You can specify either a relative path or a full path. The environment variable$PWD doesn't work here.
    • --platform multicloud Specifies that the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
    • --enable_all Allows the script to:
      • Grant required IAM permissions.
      • Enable the required Google APIs.
      • Set a label on the cluster that identifies the mesh.
      • Register the cluster to the fleet if it isn't already registered.
    • --ca citadel Use Istio CA as the certificate authority.
    • --ca_cert The intermediate certificate
    • --ca_key The key for the intermediate certificate
    • --root_cert The root certificate
    • --cert_chain The certificate chain

Private

  1. Set the current context to your user cluster:

    kubectl config use-contextCLUSTER_NAME

  2. Save the following YAML to a file calledistio-operator-internal-lb.yaml:

    apiVersion:install.istio.io/v1alpha1kind:IstioOperatorspec:components:ingressGateways:-enabled:truek8s:serviceAnnotations:service.beta.kubernetes.io/aws-load-balancer-internal:"true"name:istio-ingressgateway

  3. Runasmcli install:

    ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --ca citadel \  --ca_certFILE_PATH \  --ca_keyFILE_PATH \  --root_certFILE_PATH \  --cert_chainFILE_PATH  --custom_overlay istio-operator-internal-lb.yaml
    • --fleet_id The project ID of the fleet host project.
    • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
    • --output_dir Include this option to specify a directory whereasmcli downloads theanthos-service-mesh package and extracts the installation file, which containsistioctl, samples, and manifests. Otherwiseasmcli downloads the files to atmp directory. You can specify either a relative path or a full path. The environment variable$PWD doesn't work here.
    • --platform multicloud Specifies that the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
    • --enable_all Allows the script to:
      • Grant required IAM permissions.
      • Enable the required Google APIs.
      • Set a label on the cluster that identifies the mesh.
      • Register the cluster to the fleet if it isn't already registered.
    • --ca citadel Use Istio CA as the certificate authority.
    • --ca_cert The intermediate certificate
    • --ca_key The key for the intermediate certificate
    • --root_cert The root certificate
    • --cert_chain The certificate chain

Amazon EKS

Run the following commands on Amazon EKS to upgrade the control plane withdefault features and Istio CA. Enter your values in the providedplaceholders.

Platform note:If you have Cloud Service Mesh 1.7 installed on EKS, you will need to installCloud Service Mesh 1.23 on a new cluster. Upgrades fromCloud Service Mesh 1.7 to Cloud Service Mesh 1.23 aren'tsupported.

  1. Set the current context to your user cluster:

    kubectl config use-contextCLUSTER_NAME

  2. Runasmcli install:

    ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --ca citadel \  --ca_certFILE_PATH \  --ca_keyFILE_PATH \  --root_certFILE_PATH \  --cert_chainFILE_PATH
    • --fleet_id The project ID of the fleet host project.
    • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
    • --output_dir Include this option to specify a directory whereasmcli downloads theanthos-service-mesh package and extracts the installation file, which containsistioctl, samples, and manifests. Otherwiseasmcli downloads the files to atmp directory. You can specify either a relative path or a full path. The environment variable$PWD doesn't work here.
    • --platform multicloud Specifies that the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
    • --enable_all Allows the script to:
      • Grant required IAM permissions.
      • Enable the required Google APIs.
      • Set a label on the cluster that identifies the mesh.
      • Register the cluster to the fleet if it isn't already registered.
    • --ca citadel Use Istio CA as the certificate authority.
    • --ca_cert The intermediate certificate
    • --ca_key The key for the intermediate certificate
    • --root_cert The root certificate
    • --cert_chain The certificate chain

Microsoft AKS

Run the following commands on Microsoft AKS to upgrade the control plane withdefault features and Istio CA. Enter your values in the providedplaceholders.

Note: If you have Cloud Service Mesh 1.7 installed on AKS, you will need toinstall Cloud Service Mesh 1.23 on a new cluster. Upgrades fromCloud Service Mesh 1.7 to Cloud Service Mesh 1.23 aren't supported.

  1. Set the current context to your user cluster:

    kubectl config use-contextCLUSTER_NAME

  2. Runasmcli install:

    HUB_REGISTRATION_EXTRA_FLAGS=--has-private-issuer ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --ca citadel \  --ca_certFILE_PATH \  --ca_keyFILE_PATH \  --root_certFILE_PATH \  --cert_chainFILE_PATH
    • --fleet_id The project ID of the fleet host project.
    • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
    • --output_dir Include this option to specify a directory whereasmcli downloads theanthos-service-mesh package and extracts the installation file, which containsistioctl, samples, and manifests. Otherwiseasmcli downloads the files to atmp directory. You can specify either a relative path or a full path. The environment variable$PWD doesn't work here.
    • --platform multicloud Specifies that the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
    • --enable_all Allows the script to:
      • Grant required IAM permissions.
      • Enable the required Google APIs.
      • Set a label on the cluster that identifies the mesh.
      • Register the cluster to the fleet if it isn't already registered.
    • --ca citadel Use Istio CA as the certificate authority.
    • --ca_cert The intermediate certificate
    • --ca_key The key for the intermediate certificate
    • --root_cert The root certificate
    • --cert_chain The certificate chain

Upgrade with optional features

An overlay file is a YAML file containing anIstioOperator custom resource(CR) that you pass toasmcli to configure the control plane. You canoverride the default control plane configuration andenable an optional featureby passing the YAML file toasmcli. You can layer on more overlays, and eachoverlay file overrides the configuration on the previous layers.

GKE

Run the following command to install the control plane with an optionalfeature. To add multiple files, specify--custom_overlay and the filename,for example:--custom_overlayoverlay_file1.yaml--custom_overlay overlay_file2.yaml --custom_overlay overlay_file3.yamlEnter your values in the provided placeholders.

./asmcli install \  --project_idPROJECT_ID \  --cluster_nameCLUSTER_NAME \  --cluster_locationCLUSTER_LOCATION \  --fleet_idFLEET_PROJECT_ID \  --output_dirDIR_PATH \  --enable_all \  --ca mesh_ca \  --custom_overlayOVERLAY_FILE
  • --project_id,--cluster_name, and--cluster_location Specify the project ID that the cluster is in, the cluster name, and either the cluster zone or region.
  • --fleet_id The project ID of the fleet host project. If you don't include this option,asmcli uses the project that the cluster was created in when registering the cluster.
  • --output_dir Include this option to specify a directory whereasmcli downloads theanthos-service-mesh package and extracts the installation file, which containsistioctl, samples, and manifests. Otherwiseasmcli downloads the files to atmp directory. You can specify either a relative path or a full path. The environment variable$PWD doesn't work here.Note: Make note of this--output_dir directory. You will need to reference it when deploying gateways.
  • --enable_all Allows the script to:
    • Grant required IAM permissions.
    • Enable the required Google APIs.
    • Set a label on the cluster that identifies the mesh.
    • Register the cluster to the fleet if it isn't already registered.
  • --ca mesh_ca Use Cloud Service Mesh certificate authority as thecertificate authority. Changing certificate authorities during anupgrade causes downtime.asmcliconfiguresCloud Service Mesh certificate authority to usefleetworkload identity
  • --custom_overlay Specify the name of the overlay file.

Outside Google Cloud

Run the following commands on Google Distributed Cloud (software only) for VMware,Google Distributed Cloud (software only) for bare metal, GKE on AWS, Amazon EKS, or MicrosoftAKS. Enter your values in the provided placeholders.

Platform note:If you have Cloud Service Mesh 1.7 installed on EKS, you will need to installCloud Service Mesh 1.23 on a new cluster. Upgrades fromCloud Service Mesh 1.7 to Cloud Service Mesh 1.23 aren'tsupported.

  1. Set the current context to your user cluster:

    kubectl config use-contextCLUSTER_NAME

  2. Runasmcli install:

    ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --ca mesh_ca \  --custom_overlayOVERLAY_FILE
    • --fleet_id The project ID of the fleet host project.
    • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
    • --output_dir Include this option to specify a directory whereasmcli downloads theanthos-service-mesh package and extracts the installation file, which containsistioctl, samples, and manifests. Otherwiseasmcli downloads the files to atmp directory. You can specify either a relative path or a full path. The environment variable$PWD doesn't work here.
    • --platform multicloud Specifies that the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
    • --enable_all Allows the script to:
      • Grant required IAM permissions.
      • Enable the required Google APIs.
      • Set a label on the cluster that identifies the mesh.
      • Register the cluster to the fleet if it isn't already registered.
    • --ca mesh_ca Use Cloud Service Mesh certificate authority as thecertificate authority. Changing certificate authorities during anupgrade causes downtime.asmcliconfiguresCloud Service Mesh certificate authority to usefleetworkload identity
    • --custom_overlay Specify the name of the overlay file.

Upgrade gateways

If you have gateways deployed, you will need to upgrade these as well. For asimple upgrade follow the In-place Upgrades section in theInstall and upgrade gateways guide.

Warning: If you installed Cloud Service Mesh with any other method thanasmcli, thedefault ingress gateway installed will be removed unless you pass in the--option legacy-default-ingressgateway argument.

Switch to the new control plane

  1. Get the revision label that is onistiod.

    kubectl get pod -n istio-system -L istio.io/rev

    The output from the command is similar to the following.

    NAME                                                 READY   STATUS    RESTARTS   AGE   REVistiod-asm-1236-11-67998f4b55-lrzpz           1/1     Running   0          68m   asm-1228-5istiod-asm-1236-11-67998f4b55-r76kr           1/1     Running   0          68m   asm-1228-5istiod-1228-5-1-5cd96f88f6-n7tj9    1/1     Running   0          27s   asm-1236-11istiod-1228-5-1-5cd96f88f6-wm68b    1/1     Running   0          27s   asm-1236-11

    1. In the output, under theREV column, note the value of the revisionlabel for the new version. In this example, the value isasm-1236-11.

    2. Also note the value in the revision label for the oldistiod version.You need this to delete the old version ofistiod when you finishmoving workloads to the new version. In the example output, the value ofthe revision label for the old version isasm-1228-5.

  2. Add the revision label to an application namespace and remove theistio-injection label (if it exists). In the following command, changeREVISION to the value that matches the new revision ofistiod.

    kubectllabelnamespaceNAMESPACEistio.io/rev=REVISIONistio-injection---overwrite

    If you see"istio-injection not found" in the output, you canignore it. That means that the namespace didn't previously have theistio-injection label. Because auto-injection behavior isundefined when a namespace has both theistio-injection and therevision label, allkubectl label commands in the Cloud Service Meshdocumentation explicitly ensure that only one is set.

  3. Restart the Pods to trigger re-injection.

    kubectl rollout restart deployment -nNAMESPACE

  4. Test your application to verify that the workloads are working correctly.

  5. If you have workloads in other namespaces, repeat the steps to label thenamespace and restart Pods.

  6. If you are satisfied that your application is working as expected, continuewith the steps to transition to the new version ofistiod. If there's anissue with your application, follow the steps to rollback.

    Complete the transition

    If you are satisfied that your application is working as expected, removethe old control plane to complete the transition to the new version.

    1. Change to the directory where the files from theanthos-service-meshGitHub repository are located.

    2. Configure the validating webhook to use the new control plane:

      kubectl apply -f asm/istio/istiod-service.yaml

    3. Move the default tag:

      <OUTPUT_DIR>/istioctl tag set default --revision <NEW REVISION NAME>

    4. Delete the old version ofistiod. The command that you use dependson whether you are migrating from Istio or upgrading from a previousversion of Cloud Service Mesh.

      Migrate

      If you migrated from Istio, the oldistio-ingressgateway doesn'thave a revision label:

      kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod -n istio-system --ignore-not-found=true

      Upgrade

      1. If you upgraded from a previous Cloud Service Mesh version, in thefollowing command, make sure thatOLD_REVISIONmatches the revision label for the previous version ofistiod:

        kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod-OLD_REVISION -n istio-system --ignore-not-found=true

      2. Delete thevalidatingwebhookconfiguration resource for old revision:

        kubectl delete validatingwebhookconfiguration istio-validator-OLD_REVISION-istio-system -n istio-system --ignore-not-found

    5. Remove the old version of theIstioOperator configuration:

      kubectl delete IstioOperator installed-state-OLD_REVISION -n istio-system

      The expected output is similar to the following:

      istiooperator.install.istio.io "installed-state-OLD_REVISION" deleted

    Rollback

    If you encountered an issue when testing your application with the newversion ofistiod, follow these steps to rollback to the previousversion:

    1. Relabel your namespace to enable auto-injection with the previousversion ofistiod. The command that you use depends on whether youused a revision label oristio-injection=enabled with the previousversion.

      • If you used a revision label for auto-injection:

        kubectl label namespaceNAMESPACE istio.io/rev=OLD_REVISION --overwrite

      • If you usedistio-injection=enabled:

        kubectl label namespaceNAMESPACE istio.io/rev- istio-injection=enabled --overwrite

      Expected output:

      namespace/NAMESPACE labeled

    2. Confirm that the revision label on the namespace matches the revisionlabel on the previous version ofistiod:

      kubectl get nsNAMESPACE --show-labels

    3. Restart the Pods to trigger re-injection so the proxies have the previousversion:

      kubectl rollout restart deployment -nNAMESPACE

    4. Remove the new version ofistiod. Make sure that the value ofREVISION in the following command is correct.

      kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod-REVISION -n istio-system --ignore-not-found=true

    5. Remove the new version of theIstioOperator configuration.

    Note: if you upgrade to Cloud Service Mesh 1.21 or later, theIstioOperator resource does not exist.
     kubectl delete IstioOperator installed-state-REVISION -n istio-system

    Expected output is similar to the following:

     istiooperator.install.istio.io "installed-state-REVISION" deleted

    1. If you didn't include the--disable_canonical_service flag,asmcli enabled the Canonical Service controller. We recommend thatyou leave it enabled, but if you need to disable it, seeEnabling and disabling the Canonical Service controller.

    2. If you have gateways deployed, make sure to change the revision labelon the namespace or deployment to match the previous version ofistiod. Follow the same process outlined under the In-place Upgragessection in theInstall and upgrade gatewaysguide.

Deploying and redeploying workloads

Your installation (or upgrade) isn't complete until you enable automatic sidecarproxy injection (auto-injection). Migrations from OSS Istio and upgrades followthe revision-based upgrade process (referred to as "canary upgrades" in theIstio documentation). With a revision-based upgrade, the new version of thecontrol plane is installed alongside the existing control plane. You then movesome of your workloads to the new version, which lets you monitor the effect ofthe upgrade with a small percentage of the workloads before migrating all of thetraffic to the new version.

The script sets arevision label in theformatistio.io/rev=asm-1236-11 onistiod. To enable auto-injection,add a matching revision label to your namespace(s). The revision label is usedby the sidecar injector webhook to associate injected sidecars with a particularistiod revision. After adding the label, restart the Pods in the namespace forsidecars to be injected.

  1. Get the revision label that is onistiod and theistio-ingressgateway.In the following command, change theINGRESS_NAMESPACEvalue to the namespace where your ingress gateway is running:

    kubectl get pod -nINGRESS_NAMESPACE -L istio.io/rev

    The output from the command is similar to the following if your ingressgateway name isistio-ingressgateway:

    NAME                                                READY   STATUS    RESTARTS   AGE   REVistio-ingressgateway-65d884685d-6hrdk               1/1     Running   0          67mistio-ingressgateway-65d884685d-94wgz               1/1     Running   0          67mistio-ingressgateway-asm-182-2-8b5fc8767-gk6hb      1/1     Running   0          5s    asm-1236-11istio-ingressgateway-asm-182-2-8b5fc8767-hn4w2      1/1     Running   0          20s   asm-1236-11istiod-asm-1236-11-67998f4b55-lrzpz          1/1     Running   0          68m   asm-1228-5istiod-asm-1236-11-67998f4b55-r76kr          1/1     Running   0          68m   asm-1228-5istiod-asm-1228-5-5cd96f88f6-n7tj9 1/1     Running   0          27s   asm-1236-11istiod-asm-1228-5-5cd96f88f6-wm68b 1/1     Running   0          27s   asm-1236-11

    1. In the output, under theREV column, note the value of the revisionlabel for the new version. In this example, the value isasm-1236-11.

    2. Also note the value in the revision label for the oldistiod version.You need this to delete the old version ofistiod when you finishmoving workloads to the new version. In the example output, the value ofthe revision label for the old version isasm-1228-5.

  2. Switch the ingress gateway to the new revision. In thefollowing command, changeREVISION to the value thatmatches the revision label of the new version. Change theINGRESS_NAMESPACEto the namespace where your ingress gateway is running and theINGRESS_NAME to the name of your ingress gateway.

    kubectl patch service -nINGRESS_NAMESPACEINGRESS_NAME --type='json' -p='[{"op": "replace", "path": "/spec/selector/service.istio.io~1canonical-revision", "value": "REVISION"}]'

    Expected output:service/istio-ingressgateway patched

  3. Add the revision label to a namespace and remove theistio-injectionlabel (if it exists). In the following command, changeREVISION to the value that matches the new revision ofistiod.

    kubectllabelnamespaceNAMESPACEistio.io/rev=REVISIONistio-injection---overwrite

    If you see"istio-injection not found" in the output, you canignore it. That means that the namespace didn't previously have theistio-injection label. Because auto-injection behavior isundefined when a namespace has both theistio-injection and therevision label, allkubectl label commands in the Cloud Service Meshdocumentation explicitly ensure that only one is set.

  4. Restart the Pods to trigger re-injection.

    Warning: Make sure to restart all pods in order to trigger the re-injectionof sidecars. Otherwise, the Cloud Service Mesh metric reports may becomeinconsistent between the old and new proxies in the cluster.
    kubectl rollout restart deployment -nNAMESPACE

  5. Test your application to verify that the workloads are working correctly.

  6. If you have workloads in other namespaces, repeat the steps to label thenamespace and restart Pods.

  7. If you are satisfied that your application is working as expected, continuewith the steps to transition to the new version ofistiod. If there's anissue with your application, follow the steps to rollback.

    Complete the transition

    If you are satisfied that your application is working as expected, removethe old control plane to complete the transition to the new version.

    1. Change to the directory where the files from theanthos-service-meshGitHub repository are located.

    2. Configure the validating webhook to use the new control plane.

      kubectl apply -f asm/istio/istiod-service.yaml

    3. Move the default tag.

      <OUTPUT_DIR>/istioctl tag set default --revision <NEW REVISION NAME> --overwrite

    4. Delete the old ingress gateway deployment. The command that yourun depends on whether you are migrating from Istio or upgradingfrom a previous version of Cloud Service Mesh:

    5. Delete the old version ofistiod. The command that you use dependson whether you are migrating from Istio or upgrading from a previousversion of Cloud Service Mesh.

      Migrate

      If you migrated from Istio, the oldistiod doesn'thave a revision label.

      kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod -n istio-system --ignore-not-found=true

      If you have the older control plane, which has theOLD_REVISION revision label, click theupgrade tab and complete the deletion of the istiod control plane withOLD_REVISION.

      Upgrade

      If you upgraded from a previous Cloud Service Mesh version, in thefollowing command, make sure thatOLD_REVISIONmatches the revision label for the previous version ofistiod.

      kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod-OLD_REVISION -n istio-system --ignore-not-found=true

      Delete thevalidatingwebhookconfiguration resource for the old revision:

      kubectl delete validatingwebhookconfiguration istio-validator-OLD_REVISION-istio-system -n istio-system --ignore-not-found=true

    6. Remove the old version of theIstioOperator configuration.

      kubectl delete IstioOperator installed-state-OLD_REVISION -n istio-system --ignore-not-found=true

      The expected output is similar to the following:

      istiooperator.install.istio.io "installed-state-OLD_REVISION" deleted

    Rollback

    If you encountered an issue when testing your application with the newversion ofistiod, follow these steps to rollback to the previousversion:

    1. Relabel your namespace to enable auto-injection with the previousversion ofistiod. The command that you use depends on whether youused a revision label oristio-injection=enabled with the previousversion.

      Expected output:

      namespace/NAMESPACE labeled

    2. Confirm that the revision label on the namespace matches the revisionlabel on the previous version ofistiod:

      kubectl get nsNAMESPACE --show-labels

    3. Restart the Pods to trigger re-injection so the proxies have the previousversion:

      kubectl rollout restart deployment -nNAMESPACE

    4. Remove the newistio-ingressgateway Deployment. Make sure that thevalue ofREVISION in the following command iscorrect.

      kubectl delete deploy -l app=istio-ingressgateway,istio.io/rev=REVISION -n istio-system --ignore-not-found=true

    5. Remove the new version ofistiod. Make sure that the value ofREVISION in the following command is correct.

      kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod-REVISION -n istio-system --ignore-not-found=true

    6. Remove the new version of theIstioOperator configuration.

    Note: if you upgrade to Cloud Service Mesh 1.21 or later, theIstioOperator resource does not exist.
     kubectl delete IstioOperator installed-state-REVISION -n istio-system --ignore-not-found=true

    Expected output is similar to the following:

     istiooperator.install.istio.io "installed-state-REVISION" deleted

    1. If you didn't include the--disable_canonical_service flag,the script enabled the Canonical Service controller. We recommend thatyou leave it enabled, but if you need to disable it, seeEnabling and disabling the Canonical Service controller.

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.