This page explains how to run the script to install Anthos Service Mesh version 1.8.5 on a GKE cluster for a mesh containing one or more clusters that are in the same Cloud project.
For a multi-cluster mesh where the clusters are in different projects, see Multi-cluster/multi-project installation and migration for GKE.
This page is for installations of Anthos Service Mesh: either new installations or reinstalling the same version with another configuration.
Although running the script for new installs is similar for reinstallations of the same version, upgrades and migrations from Istio, those use cases involve additional planning. For information see the following:
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 Citadel as the CA, you need to specify the
--caoption and some other options, as described in Installation with Citadel as the 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 an existing 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
you can include the specific flag from the error message or the
flag when running the script without
--only_validate. If you prefer, you can
update your project and cluster yourself before running the script as described
in the Setting up your project and
Setting up your cluster sections of the
Multi-project installation guide.
The following command runs the script for a new installation, enables
Mesh CA, which is the default CA for installs, so you
don't need the
--ca option in this case. The
allows the script to enable the required Google APIs, set Identity and Access Management
permissions, and make the required updates to your cluster, which includes
GKE Workload Identity.
./install_asm \ --project_id PROJECT_ID \ --cluster_name CLUSTER_NAME \ --cluster_location CLUSTER_LOCATION \ --mode install \ --enable_all
You might also want to include the following:
--output_dir DIR_PATHIf you didn't run the only validate example, include this option to specify an existing 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.
Installation with Citadel as the 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 Citadel as the CA.
We recommend that you use Citadel as the 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 \ --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 \ --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 \ --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 environ
The preview of Mesh CA with environ 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 environ workload identity pool. Mesh CA with environ lets you join clusters in separate Google Cloud projects to a single trust domain corresponding to the environ.
To enable Mesh CA with environ:
If you haven't already
registered your cluster,
be sure to include the
--enable-registration flag as shown in the following
./install_asm \ --project_id PROJECT_ID \ --cluster_name CLUSTER_NAME \ --cluster_location CLUSTER_LOCATION \ --mode install \ --enable_all \ --enable-registration \ --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 environ 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:
Set the current context for
gcloud container clusters get-credentials CLUSTER_NAME \ --project=PROJECT_ID
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-185-2-5788d57586-bljj4 1/1 Running 0 23h app=istiod,istio.io/rev=asm-185-2,istio=istiod,pod-template-hash=5788d57586 istiod-asm-185-2-5788d57586-vsklm 1/1 Running 1 23h app=istiod,istio.io/rev=asm-185-2,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.