Version 1.7

Installing Anthos Service Mesh on GKE on Google Cloud

This guide explains how to install, migrate, or upgrade to Anthos Service Mesh version 1.7.3 for a mesh containing one or more GKE on Google Cloud clusters that are in the same project. You use a Google-provided script, which configures your project and cluster, and then installs Anthos Service Mesh.

You can use this guide and the script for the following use cases:

  • New installations of Anthos Service Mesh.

  • Upgrading from Anthos Service Mesh 1.6 or a 1.7 patch version. Upgrades from earlier versions aren't supported.

  • Migrating from open source Istio 1.6 or 1.7 to Anthos Service Mesh. Migrating from an earlier version of Istio isn't supported.

  • Migrating from the 1.6 version of the Istio on GKE add-on to Anthos Service Mesh. Before you can migrate to Anthos Service Mesh, you need to Upgrade to Istio 1.6 with Operator. For complete migration steps from the add-on, see Migrating to Anthos Service Mesh in the Istio on GKE documentation.

For a multi-cluster mesh where the clusters are in different projects, see Multi-cluster/multi-project installation and migration for GKE on Google Cloud.

Before you begin

This guide assumes that you have the following:

If you are migrating from Istio, be sure to review Preparing to migrate from Istio.

Anthos and Anthos Service Mesh differences

  • Anthos subscribers, be sure to enable the Anthos API.

    Enable the API

  • If you aren't an Anthos subscriber, you can still install Anthos Service Mesh, but certain UI elements and features in Google Cloud Console are only available to Anthos subscribers. For information about what is available to subscribers and non-subscribers, see Anthos and Anthos Service Mesh UI differences. For information about Anthos Service Mesh pricing for non-subscribers, see Pricing.

The script enables all of the other required Google APIs for you.


  • Your GKE cluster must meet the following requirements:

    • A machine type that has at least four vCPUs, such as e2-standard-4. If the machine type for your cluster doesn't have at least four vCPUs, change the machine type as described in Migrating workloads to different machine types.

    • The minimum number of nodes depends on your machine type. Anthos Service Mesh requires at least eight vCPUs. If the machine type has four vCPUs, your cluster must have at least two nodes. If the machine type has eight vCPUs, the cluster only needs one node. If you need to add nodes, see Resizing a cluster.

    • The script enables Workload Identity on your cluster. Workload Identity is the recommended method of calling Google APIs. Enabling Workload Identity changes the way calls from your workloads to Google APIs are secured, as described in Workload Identity limitations.

    • Optional but recommended, enroll the cluster in a release channel. We recommend that you enroll in the Regular release channel because other channels might be based on a GKE version that isn't supported with Anthos Service Mesh 1.7.3. For more information, see Supported environments. Follow the instructions in Enrolling an existing cluster in a release channel if you have a static GKE version.

  • To be included in the service mesh, service ports must be named, and the name must include the port's protocol in the following syntax: name: protocol[-suffix] where the square brackets indicate an optional suffix that must start with a dash. For more information, see Naming service ports.

  • If you are installing Anthos Service Mesh on a private cluster, you must open port 15017 in the firewall to get the webhook used with automatic sidecar injection to work properly. For more information, see Opening a port on a private cluster.

  • If you have created a service perimeter in your organization, you might need to add the Mesh CA service to the perimeter. See Adding Mesh CA to a service perimeter for more information.

  • For migrations, istiod must be installed in the istio-system namespace, which is typically the case.


A Google Cloud project can only have one mesh associated with it.

Choosing a certificate authority

For both new installations and migrations, you can use Anthos Service Mesh certificate authority (Mesh CA) or Citadel (now incorporated in istiod) as the certificate authority (CA) for issuing mutual TLS (mTLS) certificates.

We generally recommend that you use Mesh CA for the following reasons:

  • Mesh CA is a highly reliable and scalable service that is optimized for dynamically scaled workloads on Google Cloud.
  • With Mesh CA, Google manages the security and availability of the CA backend.
  • Mesh CA lets you rely on a single root of trust across clusters.
For new installations of Anthos Service Mesh, by default, the script enables Mesh CA.

However, there are cases where you might want to consider using Citadel, such as the following:

  • If you have a custom CA.
  • If you're migrating from Istio.

    If you choose Citadel, there's no downtime because mTLS traffic isn't interrupted during the migration. If you choose Mesh CA, you need to schedule downtime for the migration because mTLS traffic fails until you restart all Pods in all namespaces.

Certificates from Mesh CA include the following data about your application's services:

  • The Google Cloud project ID
  • The GKE namespace
  • The GKE service account name

Preparing for a migration or upgrade

If you are migrating from Istio, be sure to review Preparing to migrate from Istio.

If you customized the previous installation, you need the same customizations when you migrate or upgrade to Anthos Service Mesh. If you customized the installation by adding the --set values flag, we recommend that you add those settings to an IstioOperator configuration file. You specify the configuration file by using --custom_overlay with the configuration file when you run the script.

Installing required tools

You can run the script on Cloud Shell or on your local machine running Linux. Cloud Shell pre-installs all the required tools. Note that macOS isn't supported because it comes with an old version of bash.

To run the script locally:

  1. Make sure you have the following tools installed:

    • The Cloud SDK (the gcloud command-line tool)
    • The standard command-line tools: awk, curl, grep, sed, sha256sum, and tr
    • git
    • kpt
    • kubectl
    • jq
  2. Authenticate with the Cloud SDK:

    gcloud auth login
  3. Update the components:

    gcloud components update
  4. Make sure that git is in your path so that kpt can find it.

Running the script

This section describes how to download the script, set the required and optional parameters, and run the script. For a detailed explanation of what the script does, see Understanding the script.

  1. Download the version of the script that installs Anthos Service Mesh 1.7.3 to the current working directory:

    curl > install_asm

    Although you download the script from a secure Cloud Source Repositories location, the script is also available on GitHub in the anthos-service-mesh-packages repository so that you can see what it does before you download it. The version of the install_asm script on the release-1.7-asm branch installs Anthos Service Mesh 1.7.3.

  2. Download the SHA-256 of the file to the current working directory:

    curl > install_asm.sha256
  3. With both files in the same directory, verify the download:

    sha256sum -c --ignore-missing install_asm.sha256

    If the verification is successful, the command outputs: install_asm: OK For compatibility, the preceding command includes the --ignore-missing flag to allow any version of the script to be renamed to install_asm.

  4. Make the script executable:

    chmod +x install_asm
  5. Set the options and specify the flags to run the script. You always include the following options: project_id, cluster_name, cluster_location, and mode. Depending on the mode, you might need to include the ca option.

    • The project_id, cluster_name, and cluster_location options identify the cluster on which to install Anthos Service Mesh.
    • The mode is either install, migrate, or upgrade.
    • The ca specifies the Certificate Authority to either mesh_ca or citadel.

    The following section provides typical examples for running the script. For a complete description of the script's arguments, see Option and flags.

  6. To complete setting up Anthos Service Mesh, you need to enable automatic sidecar injection and deploy or redeploy workloads.


This section shows examples of running the script in each mode and some additional arguments that you might find useful. See the navigation bar on the right for a list of the examples.

Only validate

The following example shows running the script with the --only_validate option. With this option, the script doesn't make any changes to your cluster, and it doesn't install Anthos Service Mesh. The script validates that:

  • Your environment has the required tools.
  • You have the required permission on the specified project.
  • The cluster meets the minimum requirements.
  • The project has all the required Google APIs enabled.

By default, the script downloads and extracts the installation file and downloads the asm configuration package from GitHub to a temp directory. Before exiting, the script outputs a message that provides the name of the temp directory. You can specify an existing directory for the downloads with the --output_dir DIR_PATH option. The --output_dir option makes it convenient for you to use the istioctl command-line tool if you need it. Additionally, the configuration files to enable optional features are included in the asm/istio/options directory.

Run the following command to validate your configuration and download the installation file and asm package to the OUTPUT_DIR directory:

./install_asm \
  --project_id PROJECT_ID \
  --cluster_name CLUSTER_NAME \
  --cluster_location CLUSTER_LOCATION \
  --mode install \
  --output_dir DIR_PATH \

On success, the script outputs the following:

./install_asm \
install_asm: Setting up necessary files...
install_asm: Creating temp directory...
install_asm: Generating a new kubeconfig...
install_asm: Checking installation tool dependencies...
install_asm: Downloading ASM..
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 57.0M  100 57.0M    0     0  30.6M      0  0:00:01  0:00:01 --:--:-- 30.6M
install_asm: Downloading ASM kpt package...
fetching package /asm from to asm
install_asm: Checking for project PROJECT_ID...
install_asm: Confirming cluster information...
install_asm: Confirming node pool requirements...
install_asm: Fetching/writing GCP credentials to kubeconfig file...
Fetching cluster endpoint and auth data.
kubeconfig entry generated for cluster-1.
install_asm: Checking Istio installations...
install_asm: Checking required APIs...
install_asm: Successfully validated all requirements to install ASM from this computer.

If one of the tests fails the validation, the script outputs an error message. For example, if your project doesn't have all of the required Google APIs enabled, you see the following error:

ERROR: One or more APIs are not enabled. Please enable them and retry, or
re-run the script with the '--enable_apis' flag to allow the script to enable
them on your behalf.

New installation

The following command runs the script for a new installation, enables Mesh CA (the default CA for new installs, so you don't need the ca option in this case), and allows the script to enable the required Google APIs.

./install_asm \
  --project_id PROJECT_ID \
  --cluster_name CLUSTER_NAME \
  --cluster_location CLUSTER_LOCATION \
  --mode install \

New installation with an overlay file

The following example does a new installation and includes an IstioOperator YAML file that you have created to customize the installation. In the following command, change OVERLAY_FILE to the name of the YAML file.

./install_asm \
  --project_id PROJECT_ID \
  --cluster_name CLUSTER_NAME \
  --cluster_location CLUSTER_LOCATION \
  --mode install \
  --enable_apis \
  --custom_overlay OVERLAY_FILE

New installation with an option

The following example does a new installation and includes the egressgateways.yaml file from the asm package, which enables an egress gateway. Note that you don't include the .yaml extension. The script fetches the file for you so you don't have to download the asm package first.

./install_asm \
  --project_id PROJECT_ID \
  --cluster_name CLUSTER_NAME \
  --cluster_location CLUSTER_LOCATION \
  --mode install \
  --enable_apis \
  --option egressgateways

You can use --option to enable an optional feature. If you need to make modifications to any of the files in the asm/istio/options directory in the asm package, download the asm package, make your changes, and include the file using --custom_overlay.

To download the asm package to the current working directory so you can make modifications to the files:

kpt pkg get \ asm

If you ran the Only validate example where you specified the --output_dir option, then the configuration files are in the specified output directory under asm/istio/options.

Migration from Istio

If you are migrating from Istio with Citadel as the CA, you can continue to use Citadel after migrating to Anthos Service Mesh. The following command runs the script for a migration and enables Citadel as the CA. This migration only deploys the control plane. It doesn't change the root CA and isn't disruptive to your existing workloads.

./install_asm \
  -m migrate \
  -c citadel \


The following command runs the script to upgrade. The script doesn't allow you to change to another CA, so you don't need to include the ca option.

./install_asm \
  -m upgrade \

Options and flags

This section describes the available arguments to the script.


-p|--project_id CLUSTER_PROJECT_ID
The project ID that the cluster was created in.
-n|--cluster_name CLUSTER_NAME
The name of the cluster.
-l|--cluster_location CLUSTER_LOCATION
Either the zone (for single-zone clusters) or region (for regional clusters) that the cluster was created in.
-m|--mode {install|migrate|upgrade}
Enter install if you are doing a new installation of Anthos Service Mesh. Enter migrate if you are migrating from Istio. Enter upgrade to upgrade an existing Anthos Service Mesh installation to a new version.
-c|--ca {mesh_ca|citadel}
For new installations, if you want to use Mesh CA, you don't have to include this option because the script defaults to Mesh CA. For upgrades, you don't need to include this option because the script doesn't allow you to change the CA. For migrations, you specify citadel or mesh_ca. If you can schedule downtime for the migration, we recommend that you use mesh_ca. For more information about which CA to use, see Choosing a certificate authority. For additional options that you must specify when using Citadel, see Options for a custom certificate for Citadel.
--co|--custom_overlay YAML_FILE
The name of the YAML file to enable a feature that isn't enabled in the asm-gcp profile. The script must be able to locate the YAML file. So the file either needs to be in the same directory as the script, or you can specify a relative path. To add multiple files, specify --co|--custom_overlay and the filename, for example: -co overlay_file1.yaml -co overlay_file2.yaml -co overlay_file3.yaml

-o|--option OPTION_FILE The name of a YAML file in the asm, without the .yaml extension to apply. When including one of these files, you don't need to download the asm package first. If you need to modify any of the files, download the asm package, make your changes, and use the --custom_overlay option. To add multiple files, specify -o|--option and the filename, for example: -o option_file1 -o option_file2 -o option_file3

-s|--service_account ACCOUNT
The name of a service account used to install Anthos Service Mesh. If not specified, the active user account in the current gcloud configuration is used. If you need to change the active user account, run gcloud auth login.
-k|--key_file FILE_PATH
The key file for a service account. Omit this option if you aren't using a service account.
-D|--output_dir DIR_PATH
If not specified, the script creates a temporary directory where it downloads files and configurations necessary for installing Anthos Service Mesh. Specify the --output-dir flag to designate an existing directory to use instead. Upon completion, the specified directory contains the asm and the istio-1.7.3-asm.6 subdirectories. The asm directory contains the configuration for the installation. The istio-1.7.3-asm.6 directory contains the extracted contents of installation file, which contains istioctl, samples, and manifests.


Allow the script to enable the Google APIs that Anthos Service Mesh requires. Without this flag, the script exits if the required APIs aren't already enabled. For a list of the APIs that the script enables, see set_up_project.
Print commands before and after execution.
Print commands, but don't execute them.
Run validation but don't install Anthos Service Mesh.
Instead of installing Anthos Service Mesh, print all of the compiled YAML to standard output (stdout). All other output is written to standard error (stderr), even if it would normally go to stdout. The script skips all validations and setup when you specify this flag.
By default, the script deploys the Canonical Service controller to your cluster. If you don't want the script to deploy the controller, specify --disable_canonical_service. For more information, refer to Enabling and disabling the Canonical Service controller.
Show a help message describing the options and flags and exit.

Options for a custom certificate for Citadel

If you specified citadel and you are using a custom CA, include the following options:

  • --ca_cert FILE_PATH: The intermediate certificate
  • --ca_key FILE_PATH: The key for the intermediate certificate
  • --root_cert FILE_PATH: The root certificate
  • --cert_chain FILE_PATH: The certificate chain

For more information, see Plugging in existing CA Certificates.

Deploying and redeploying workloads

Your installation isn't complete until you enable automatic sidecar proxy injection (auto-injection).

  • For new installations, you need to enable auto-injection and restart the Pods for any workloads that were running on your cluster before you installed Anthos Service Mesh.

  • Migrations and upgrades follow the dual control plane upgrade process (referred to as "canary upgrades" in the Istio documentation). With a dual control plane upgrade, the script installs a new version of istiod alongside the existing istiod. You then move some of your workloads to the new version. This process allows you to monitor the effect of the new version with a small percentage of the workloads before migrating all of your traffic to the new version.

  • Before you deploy new workloads, make sure to enable auto-injection so that Anthos Service Mesh can monitor and secure traffic.

To enable auto-injection, you get the revision label that the script applied to istiod and label your namespaces with the revision label. The following sections provide details.

Get the revision label

The script adds a revision label in the format to istiod. To enable auto-injection, you add a matching revision label to your namespace(s). The revision label is used by the sidecar injector webhook to associate injected sidecars with a particular istiod revision. After adding the label, any existing Pods in the namespace must be restarted for sidecars to be injected.

  1. Set the current context for kubectl:

    gcloud container clusters get-credentials CLUSTER_NAME \
  2. Display the labels on istiod to get the revision label set by the script:

    kubectl -n istio-system get pods -l app=istiod --show-labels

    The output from the command is similar to the following. Note that the output for new installations, migrations, and upgrades are slightly different. The following example output is from a migration.

    NAME                                READY   STATUS    RESTARTS   AGE   LABELS
    istiod-7744bc8dd7-qhlss             1/1     Running   0          49m   app=istiod,,istio=pilot,pod-template-hash=7744bc8dd7
    istiod-asm-173-6-85d86774f7-flrt2   1/1     Running   0          26m   app=istiod,,istio=istiod,pod-template-hash=85d86774f7
    istiod-asm-173-6-85d86774f7-tcwtn   1/1     Running   0          26m   app=istiod,,istio=istiod,pod-template-hash=85d86774f7

    In the output, under the LABELS column, note the value of the istiod revision label, which follows the prefix In this example, the value is asm-173-6, but you might have a different value.

    For upgrades and migrations, also note the value in the revision label for the old istiod version. You need this to delete the old version of istiod when you finish the migration or upgrade. In the example output, the value in the revision label for the old version of istiod is default, but you might have a different value.

Enabling auto-injection

Follow these steps for new installations, migrations, and upgrades to enable auto-injection.

  1. Get the value in the revision label for istiod.

  2. Add the revision label to a namespace and remove the istio-injection label. In the following command, change REVISION to the value that matches the revision on istiod.

    kubectl label namespace NAMESPACE istio-injection- --overwrite
  3. Restart the Pods to trigger re-injection.

    kubectl rollout restart deployment -n NAMESPACE
  4. Verify that your Pods are configured to point to the new version of istiod.

    kubectl get pods -n NAMESPACE -l
  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 the namespace and restart Pods.

For migration and upgrades:

Complete the transition

For migrations and upgrades, you need to remove the old version of istiod. If you are satisfied that your application is working as expected, remove the old control plane to complete the transition to the new version.

  1. Get the value in the revision label for the old version of istiod.

  2. Delete the old version of istiod. In the following command, replace OLD_REVISION with the revision from the previous step.

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

Rollback to the previous version

For migrations and upgrades, if you encountered an issue when testing your application with the new version of istiod, follow these steps to rollback to the previous version:

  1. Update workloads to be injected with the previous version of istiod:

    kubectl label namespace NAMESPACE istio-injection=enabled --overwrite
  2. Restart the Pods to trigger re-injection so the proxies have the previous version:

    kubectl rollout restart deployment -n NAMESPACE
  3. Redeploy the previous version of the istio-ingressgateway:

    kubectl -n istio-system rollout undo deploy istio-ingressgateway
  4. Remove the new istiod:

    kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod-REVISION -n istio-system --ignore-not-found=true
  5. If you didn't include the --disable_canonical_service flag, the script enabled the Canonical Service controller. Follow the steps in Enabling and disabling the Canonical Service controller to disable it.

Reinstalling the same version

The install_asm script doesn't allow you to reinstall the same version of Anthos Service Mesh. If you need to reinstall the same version, use the istioctl command-line tool. You might need to reinstall, for example, if you need to add, remove, or change an overlay file that enables an optional feature.

To reinstall the same version:

  1. Create an output directory where you want the script to download and extract the installation file that contains istioctl.

  2. Run the following command with the --print_config option to get current configuration for the control plane and output it to istio-config.yaml.

    ./install_asm \
      --project_id PROJECT_ID \
      --cluster_name CLUSTER_NAME \
      --cluster_location CLUSTER_LOCATION \
      --mode install \
      --output_dir DIR_PATH \
      --print_config > istio-config.yaml
  3. Add the directory where istioctl is located to your path.

    export PATH=DIR_PATH/bin:$PATH
  4. Get the value in the revision label that the script added to istiod.

  5. Run istioctl install and include the istio-config.yaml file. Include other overlay files as needed with the -f option. In the following command, replace REVISION with the revision from the previous step.

    istioctl install \
     -f istio-config.yaml \
     -f OVERLAY_FILE \
     --set revision=REVISION

    Note that the order of the files matters. Include the base configuration in istio-config.yaml first, and then the overlay files.

Viewing the Anthos Service Mesh dashboards

After you have workloads deployed on your cluster with the sidecar proxies injected, you can explore the Anthos Service Mesh pages in the Cloud Console to see all of the observability features that Anthos Service Mesh offers. Note that it takes about one or two minutes for telemetry data to be displayed in the Cloud Console after you deploy workloads.

Access to Anthos Service Mesh in the Cloud Console is controlled by Identity and Access Management (IAM). To access the Anthos Service Mesh pages, a Project Owner must grant users the Project Editor or Viewer role, or the more restrictive roles described in Controlling access to Anthos Service Mesh in the Cloud Console.

  1. In the Google Cloud Console, go to Anthos Service Mesh.

    Go to Anthos Service Mesh

  2. Select the Cloud project from the drop-down list on the menu bar.

  3. If you have more than one service mesh, select the mesh from the Service Mesh drop-down list.

To learn more, see Exploring Anthos Service Mesh in the Cloud Console.

In addition to the Anthos Service Mesh pages, metrics related to your services (such as the number of requests received by a particular service) are sent to Cloud Monitoring, where they appear in the Metrics Explorer.

To view metrics:

  1. In the Google Cloud Console, go to the Monitoring page:

    Go to Monitoring

  2. Select Resources > Metrics Explorer.

For a full list of metrics, see Istio metrics in the Cloud Monitoring documentation.

Registering your cluster

You must register your cluster with the project's environ to gain access to the unified user interface in the Cloud Console. An environ provides a unified way to view and manage the clusters and their workloads, including clusters outside Google Cloud.

See Registering clusters to the environ for information on registering your cluster.

Understanding the script

Although you download the script from a secure Cloud Source Repositories location, the script is also available on GitHub so that you can see what it does before you download it. The script validates that your cluster meets the requirements, and it automates all the steps that you would do manually in Installing Anthos Service Mesh on GKE on Google Cloud.

With Anthos Service Mesh 1.7.3, you use the version of the install_asm script on the release-1.7-asm branch. For an explanation of the versioning and release process, see Versioning/Release.

validate_args and validate_dependencies

validate_args() {
  if [[ "${MODE}" == "install" && -z "${CA}" ]]; then

  local MISSING_ARGS=0
  while read -r REQUIRED_ARG; do
    if [[ -z "${!REQUIRED_ARG}" ]]; then
      warn "Missing value for ${REQUIRED_ARG}"
    readonly "${REQUIRED_ARG}"
  done <<EOF
validate_dependencies() {
  if [[ "${PRINT_CONFIG}" -eq 1 ]]; then
    return 0

  # configure kubectl does have side effects but we've generated a temprorary
  # kubeconfig so we're not breaking the promise that --only_validate gives

  if [[ "${MODE}" = "migrate" ]]; then
  elif [[ "${MODE}" = "upgrade" ]]; then

  if [[ "${ENABLE_APIS}" -eq 0 || "${ONLY_VALIDATE}" -eq 1 ]]; then

The validate_args and validate_dependencies functions:

  • Check that all the required tools are installed.
  • Verify that the project ID, cluster name, and cluster location that you entered as parameter values are valid.
  • Ensures that the cluster meets the minimum required machine type and number of nodes.


If you included the --enable_apis flag, the set_up_project function enables the required APIS:

required_apis() {
    cat << EOF


  if [[ "${PRINT_CONFIG}" -eq 1 ]]; then
    return 0



The set_up_cluster function does the following updates to your cluster:

  • Enables Workload Identity, which is the recommended way to safely access Google Cloud services from GKE applications.

  • Enables Cloud Monitoring and Cloud Logging on GKE.

  • Sets the mesh_id label on the cluster, which is required for metrics to get displayed on the Anthos Service Mesh pages in the Cloud Console.

  • Sets a label like asmv=asm-173-6 so that you can tell that the cluster was modified by the script.

  • Binds the GCP user or service account running the script to the cluster-admin role on your cluster.


install_asm() {

  local PARAMS
  while read -d ',' -r yaml_file; do
    PARAMS="${PARAMS} -f ${yaml_file}"
  done <<EOF

The install_asm function:

  • Downloads the kpt package to a temp directory.
  • Runs the kpt setters to configure the istio-operator.yaml file.
  • Installs Anthos Service Mesh.

What's next