Installing Anthos Service Mesh

This page explains how to run the script to install Anthos Service Mesh version 1.8.6 on a GKE cluster for a mesh containing one or more clusters that are in the same Google 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:

• Upgrading Anthos Service Mesh
• Migrating from Istio
• Reinstalling the same version

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 --enable_all or --enable_gcp_iam_roles flags to allow the script to enable the permission for you. Similarly, to allow the script to enable the required APIs and update your cluster, specify the --enable_all flag or the more granular enablement flags.

Installing Anthos Service Mesh

1. 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 install. If you want to use Citadel as the CA, you need to specify the --ca option 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.

2. 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.

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.

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 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 --enable_* flags.

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 \
  --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 can include the specific flag from the error message or the --enable_all 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.

Installation

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 --enable_all flag 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 enabling GKE Workload Identity.

If you plan to use Mesh CA, you can use the fleet workload identity pool as an alternative to GKE workload identity. For an example, see Enable Mesh CA with the fleet workload identity pool.

./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_PATH If you didn't run the only validate example, include this option to specify an existing directory where the script downloads the asm package and the Anthos Service Mesh installation file, which contains istioctl, samples, and manifests. Otherwise the script downloads the asm package and installation file to a temp directory.

• --enable-registration This 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.

Important: These steps create certificates and keys using a make command that we provide for illustrative purposes only. For the best security, use an offline secure computer and production-ready tools, for example using HashiCorp Vault to securely generate and protect the CA signing key.

1. Create a directory for the certificates and keys:

   mkdir -p certs && \
   pushd certs

2. 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

3. Generate an intermediate certificate and key:

   make -f ../tools/certs/Makefile.selfsigned.mk cluster1-cacerts

   This generates these files in a directory named cluster1:

   • 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
   Note: You can replace cluster1 with a different name. For example, make mycluster-certs creates a directory named mycluster.

   If you perform these steps using an offline computer, copy the generated directory to the computer where you are running the script.

4. 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 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_all \
  --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 \
https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages.git/asm@release-1.8-asm 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.

Enable Mesh CA with fleet

Preview — Mesh CA with fleet

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

The preview of Mesh CA with fleet 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 fleet lets you join clusters in separate Google Cloud projects to a single trust domain corresponding to the fleet.

To enable Mesh CA with fleet:

If you haven't already registered your cluster, be sure to include the --enable-registration flag as shown in the following example:

./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 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 particular 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:

1. Use the following command to locate the revision label on istiod:

   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-186-8-5788d57586-bljj4   1/1     Running   0          23h   app=istiod,istio.io/rev=asm-186-8,istio=istiod,pod-template-hash=5788d57586
   istiod-asm-186-8-5788d57586-vsklm   1/1     Running   1          23h   app=istiod,istio.io/rev=asm-186-8,istio=istiod,pod-template-hash=5788d57586

   In the output, under the LABELS column, note the value of the istiod revision label, which follows the prefix istio.io/rev=. In this example, the value is asm-186-8.

2. Apply the revision label and remove the istio-injection label if it exists. In the following command, NAMESPACE is the name of the namespace where you want to enable auto-injection, and REVISION is 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-injection label, 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-injection and the revision label, all kubectl label commands in the Anthos Service Mesh documentation include removing the istio-injection label.

3. 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 kubectl to perform a rolling restart:

   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 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 Google 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 Google Cloud console after you deploy workloads.

Access to Anthos Service Mesh in the Google 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 Google Cloud console.

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

   Go to Anthos Service Mesh

2. Select the Google 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 Google 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.

What's next

• Deploy the Online Boutique sample application
• Add clusters to Anthos Service Mesh