This page explains how to run the script to install Anthos Service Mesh version 1.9.8 on a GKE cluster for a mesh containing one or more clusters that are in the same Cloud project.
For installations where the clusters are in different projects, see the GKE multi-project guide.
This guide is for installing Anthos Service Mesh or reinstalling the same version with a different configuration. However, reinstall with different configurations, upgrades, and migration from Istio require additional planning. For more information, see:
Before you begin
Before you begin the installation, make sure that you have:
- Reviewed the requirements
- Chosen a certificate authority (CA)
- Registered your cluster
- Installed the required tools
- Downloaded the script
The script requires that you have the
required permissions, or that you
include either the
to allow the script to enable the permission for you. Similarly, to allow the
script to enable the
and update your cluster,
--enable_all flag or the more granular
Installing Anthos Service Mesh
Set the options and specify the flags to run the script. You always include the following options:
--mode install. If you want to use Istio CA (previously known as Citadel) as the certificate authority, you need to specify the
--caoption and some other options, as described in Installation with Istio CA. For a complete description of the script's arguments, see Option and flags.
To complete setting up Anthos Service Mesh, you need to enable automatic sidecar injection and deploy or redeploy workloads.
The following section provides typical examples for running the script. See the navigation bar on the right for a list of the examples.
This section shows examples of running the script for an installation with some additional arguments that you might find useful. See the navigation bar on the right for a list of the examples.
The following example shows running the script with the
option. With this option, the script doesn't make any changes to your project or
cluster, and it doesn't install Anthos Service Mesh. When you specify
--only_validate,the script fails if you include any of the
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
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 a directory for the downloads with the
--output_dir DIR_PATH option. The
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
Run the following command to validate your configuration and download the
installation file and
asm package to the
./install_asm \ --project_id PROJECT_ID \ --cluster_name CLUSTER_NAME \ --cluster_location CLUSTER_LOCATION \ --mode install \ --output_dir DIR_PATH \ --only_validate
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 https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages 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 run the script with the '--enable_gcp_apis' flag to allow the script to enable them on your behalf.
If you got an error message about needing to run the script with an enablement flag, you have the following options:
Include the specific flag from the error message or the
--enable_allflag when running the script to do the actual installation (that is, without
If you prefer, you can update your project and cluster yourself before running the script as described in Setup for installing Anthos Service Mesh on GKE.
install_asm doesn't allow any enablement flags with
Installation with default features
The following command runs the script for a new installation with default features.
./install_asm \ --project_id PROJECT_ID \ --cluster_name CLUSTER_NAME \ --cluster_location CLUSTER_LOCATION \ --mode install \ --ca mesh_ca \ --output_dir DIR_PATH \ --enable_registration \ --enable_all
--ca mesh_caAlthough Mesh CA is the default CA for new installs,
--ca mesh_cais included in the command line for clarity. If you don't specify
install_asmenables Mesh CA.
--output_dir DIR_PATHInclude this option to specify a directory where the script downloads the
asmpackage and the Anthos Service Mesh installation file, which contains
istioctl, samples, and manifests. Otherwise the script downloads the
asmpackage and installation file to a temp directory.
--enable_registrationThis flag allows the script to register the cluster to the project that the cluster is in. If you don't include this flag, follow the steps in Registering a cluster to manually register your cluster.
--enable_allallows the script to enable the required Google APIs, set Identity and Access Management permissions, and make the required updates to your cluster, which includes enabling GKE Workload Identity. If you prefer not to allow
install_asmto take care of these project and cluster requirements, see Setup for installing Anthos Service Mesh on GKE.
Installation with Istio CA
This section explains how to:
- Generate certificates and keys that Anthos Service Mesh uses to sign your workloads.
- Run the script for an installation and enable Istio CA as the certificate authority.
We recommend that you use Istio CA only when you need a custom CA.
For the best security, we highly recommend maintaining an offline root CA and using the subordinate CAs to issue CAs for each cluster. For more information, see Plug in CA Certificates. In this configuration, all workloads in the service mesh use the same root CA. Each Anthos Service Mesh CA uses an intermediate CA signing key and certificate, signed by the root CA. When multiple CAs exist within a mesh, this establishes a hierarchy of trust among the CAs. You can repeat these steps to provision certificates and keys for any number of certificate authorities.
Create a directory for the certificates and keys:
mkdir -p certs && \ pushd certs
Generate a root certificate and key:
make -f ../tools/certs/Makefile.selfsigned.mk root-ca
This generates these files:
- root-cert.pem: the root certificate
- root-key.pem: the root key
- root-ca.conf: the configuration for openssl to generate the root certificate
- root-cert.csr: the CSR for the root certificate
Generate an intermediate certificate and key:
make -f ../tools/certs/Makefile.selfsigned.mk cluster1-cacerts
This generates these files in a directory named
- ca-cert.pem: the intermediate certificates
- ca-key.pem: the intermediate key
- cert-chain.pem: the certificate chain which istiod uses
- root-cert.pem: the root certificate
If you perform these steps using an offline computer, copy the generated directory to the computer where you are running the script.
Run the script and include the files that you generated previously for the certificates and key.
./install_asm \ --project_id PROJECT_ID \ --cluster_name CLUSTER_NAME \ --cluster_location CLUSTER_LOCATION \ --mode install \ --ca citadel \ --ca_cert FILE_PATH \ --ca_key FILE_PATH \ --root_cert FILE_PATH \ --cert_chain FILE_PATH \ --output_dir DIR_PATH \ --enable_registration \ --enable_all
Installation with an overlay file
An overlay file is a YAML file containing an
IstioOperator custom resource
(CR) that you pass to
install_asm to configure the control plane. You can
override the default control plane configuration and
enable an optional feature by passing
the YAML file to
install_asm. You can layer on more overlays, and each overlay
file overrides the configuration on the previous layers.
If you specify more than one CR in a YAML file,
install_asm splits the file
into multiple temporary YAML files, one for each CR. The script splits the
CRs into separate files because
istioctl install only applies the first CR in
a YAML file containing more than one CR.
The following example does an installation and includes an overlay file to
customize the control plane configuration. 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 \ --ca mesh_ca \ --output_dir DIR_PATH \ --enable_registration \ --enable_all \ --custom_overlay OVERLAY_FILE
Installation with an option
The following example does an installation and includes the
egressgateways.yaml file from the
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
asm package first.
./install_asm \ --project_id PROJECT_ID \ --cluster_name CLUSTER_NAME \ --cluster_location CLUSTER_LOCATION \ --mode install \ --ca mesh_ca \ --output_dir DIR_PATH \ --enable_registration \ --enable_all \ --option egressgateways
You can use
enable an optional feature. If you
need to make modifications to any of the files in the
directory in the
asm package, download the
asm package, make your changes,
and include the file using
To download the
asm package to the current working directory so you can
make modifications to the files:
kpt pkg get \ https://github.com/GoogleCloudPlatformemail@example.com asm
If you ran the Only validate example where you specified
--output_dir option, then the configuration files are in the specified
output directory under
Enable Mesh CA with the fleet workload identity pool
The preview of Mesh CA with the fleet workload identity pool is limited to new installations of Anthos Service Mesh on GKE. Upgrades and migrations aren't supported during the preview.
This example shows you how to enable Mesh CA to use the fleet workload identity pool. Mesh CA with the fleet workload identity pool lets you join clusters in separate Google Cloud projects to a single trust domain.
To enable Mesh CA with the fleet workload identity pool:
If you haven't already
registered your cluster,
be sure to include either the
--enable_registration flag or the
flag to allow the script to register your cluster to the project that the
cluster is in.
./install_asm \ --project_id PROJECT_ID \ --cluster_name CLUSTER_NAME \ --cluster_location CLUSTER_LOCATION \ --mode install \ --enable_all \ --option hub-meshca
This command runs the script for a new installation, configures your project and cluster with the options required by Anthos Service Mesh, registers the cluster to the project that the cluster is in, and configures Mesh CA to use the fleet workload identity pool.
Deploying and redeploying workloads
Anthos Service Mesh uses sidecar proxies to enhance network security, reliability, and observability. With Anthos Service Mesh, these functions are abstracted away from the application's primary container and implemented in a common out-of-process proxy delivered as a separate container in the same Pod.
Your installation isn't complete until you enable automatic sidecar proxy injection (auto-injection) and restart the Pods for any workloads that were running on your cluster before you installed Anthos Service Mesh.
To enable auto-injection, you label your namespaces with the revision label
that was set on
istiod when you installed Anthos Service Mesh. The revision label is
used by the sidecar injector webhook to associate injected sidecars with a
istiod revision. After adding the label, any existing Pods in the
namespace must be restarted for sidecars to be injected.
Before you deploy new workloads in a new namespace, make sure to configure auto-injection so that Anthos Service Mesh can monitor and secure traffic.
To enable auto-injection:
Use the following command to locate the revision label on
kubectl -n istio-system get pods -l app=istiod --show-labels
The output looks similar to the following:
NAME READY STATUS RESTARTS AGE LABELS istiod-asm-198-3-5788d57586-bljj4 1/1 Running 0 23h app=istiod,istio.io/rev=asm-198-3,istio=istiod,pod-template-hash=5788d57586 istiod-asm-198-3-5788d57586-vsklm 1/1 Running 1 23h app=istiod,istio.io/rev=asm-198-3,istio=istiod,pod-template-hash=5788d57586
In the output, under the
LABELScolumn, note the value of the
istiodrevision label, which follows the prefix
istio.io/rev=. In this example, the value is
Apply the revision label and remove the
istio-injectionlabel if it exists. In the following command,
NAMESPACEis the name of the namespace where you want to enable auto-injection, and
REVISIONis the revision label you noted in the previous step.
kubectl label namespace NAMESPACE istio-injection- istio.io/rev=REVISION --overwrite
You can ignore the message
"istio-injection not found"in the output. That means that the namespace didn't previously have the
istio-injectionlabel, which you should expect in new installations of Anthos Service Mesh or new deployments. Because auto-injection fails if a namespace has both the
istio-injectionand the revision label, all
kubectl labelcommands in the Anthos Service Mesh documentation include removing the
If workloads were running on your cluster before you installed Anthos Service Mesh, restart the Pods to trigger re-injection.
How you restart Pods depends on your application and the environment the cluster is in. For example, in your staging environment, you might simply delete all the Pods, which causes them to restart. But in your production environment, you might have a process that implements a blue-green deployment so that you can safely restart Pods to avoid traffic interruption.
You can use
kubectlto perform a rolling restart:
kubectl rollout restart deployment -n NAMESPACE
Verify that your Pods are configured to point to the new version of
kubectl get pods -n NAMESPACE -l istio.io/rev=REVISION
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.
In the Google Cloud Console, go to Anthos Service Mesh.
Select the Cloud project from the drop-down list on the menu bar.
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:
In the Google Cloud Console, go to the Monitoring page:
Select Resources > Metrics Explorer.
For a full list of metrics, see Istio metrics in the Cloud Monitoring documentation.