This guide explains how to install, migrate, or upgrade to Anthos Service Mesh
version 1.8.6 for a mesh containing one or more
GKE 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 using
You can use this guide and the script for the following onboarding use cases:
New installations of Anthos Service Mesh 1.8.6.
Upgrading from Anthos Service Mesh 1.7.3+ or a 1.8 patch release. Upgrades from earlier versions aren't supported.
Migrating from open source Istio 1.7 or 1.8 to Anthos Service Mesh. Migrating from an earlier version of Istio isn't supported. Be sure to review Preparing to migrate from Istio to plan your migration.
This guide assumes that you have the following:
Anthos and Anthos Service Mesh differences
Anthos subscribers, be sure to enable the Anthos 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 4 vCPUs, such as
e2-standard-4. If the machine type for your cluster doesn't have at least 4 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 8 vCPUs. If the machine type has 4 vCPUs, your cluster must have at least 2 nodes. If the machine type has 8 vCPUs, the cluster only needs 1 node. If you need to add nodes, see Resizing a cluster.
By default, 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.
If you are doing a new installation and plan to use Anthos Service Mesh certificate authority (Mesh CA), you can use the fleet workload identity pool as an alternative to GKE workload identity. To use Mesh CA with the fleet workload identity pool (Preview), you need to either follow the steps in Registering a cluster before running the script or include the
--enable-registrationflag when you run the script to let the script register the cluster to the project that the cluster is in. For an example of running the script, see Enable Mesh CA with the fleet workload identity pool.
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.8.6. 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.
istiodmust be installed in the
istio-systemnamespace, 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
(now incorporated in
istiod) as the certificate authority (CA) for issuing
mutual TLS (mTLS)
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.
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 little downtime because mTLS traffic isn't interrupted during the migration. If you choose Mesh CA, you need to schedule downtime for the migration because the root of trust changes from Citadel to Mesh CA. To complete the migration to the Mesh CA root of trust, you need to restart all Pods in all namespaces. During this process, the old Pods cannot establish mTLS connections with the new Pods.
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
Registering your cluster
You must register your cluster with the fleet to gain access to the unified user interface in the console. A fleet provides a unified way to view and manage the clusters and their workloads, including clusters outside Google Cloud.
You can either follow the steps in
Registering a cluster
or include the
--enable-registration flag when you run the script to let the
script register the cluster to the project that the cluster is in.
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.
Cloud Shell provisions a g1-small Compute Engine virtual machine (VM) running a Debian-based Linux operating system. The advantages to using Cloud Shell are:
Cloud Shell includes
kpt, and the other command-line tools that you need.
Your Cloud Shell $HOME directory has 5GB persistent storage space.
You have your choice of text editors:
Code editor, which you access by clicking at the top of the Cloud Shell window.
Emacs, Vim, or Nano, which you access from the command line in Cloud Shell.
To use Cloud Shell:
- Go to the console.
- Select your Cloud project.
Click the Activate Cloud Shell button at the top of the console window.
A Cloud Shell session opens inside a new frame at the bottom of the console and displays a command-line prompt.
Update the components:
gcloud components update
The command responds with output similar to the following:
ERROR: (gcloud.components.update) You cannot perform this action because the gcloud CLI component manager is disabled for this installation. You can run the following command to achieve the same result for this installation: sudo apt-get update && sudo apt-get --only-upgrade install ...
Copy the long command and paste it to update the components.
Local Linux computer
Make sure you have the following tools installed:
Authenticate with the gcloud CLI:
gcloud auth login
Update the components:
gcloud components update
Make sure that
gitis in your path so that
kptcan find it.
Downloading 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.
Download the version of the script that installs Anthos Service Mesh 1.8.6 to the current working directory:
curl https://storage.googleapis.com/csm-artifacts/asm/install_asm_1.8 > install_asm
Download the SHA-256 of the file to the current working directory:
curl https://storage.googleapis.com/csm-artifacts/asm/install_asm_1.8.sha256 > install_asm.sha256
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:
For compatibility, the
install_asm.sha256file includes the checksum twice to allow any version of the script to be renamed to
install_asm. If you get an error that
--ignore-missingdoes not exist, rerun the previous command without the
Make the script executable:
chmod +x install_asm
- New installations of Anthos Service Mesh
- Upgrading Anthos Service Mesh to the latest version
- Migrating from Istio
- Reinstalling the same version