Installing Anthos Service Mesh on GKE

This guide explains how to install, migrate, or upgrade to Anthos Service Mesh version 1.7.8 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.

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.

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

  • GKE Enterprise subscribers, be sure to enable the GKE Enterprise API.

    Enable the API

  • If you aren't an GKE Enterprise subscriber, you can still install Anthos Service Mesh, but certain UI elements and features in Google Cloud console are only available to GKE Enterprise subscribers. For information about what is available to subscribers and non-subscribers, see GKE Enterprise 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.

Requirements

  • 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.8. 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.

Restrictions

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

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.

To run the script locally:

  1. Make sure you have the following tools installed:

  2. Authenticate with the gcloud CLI:

    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.

  5. Download the required kpt version.

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.8 to the current working directory:

    curl https://storage.googleapis.com/csm-artifacts/asm/install_asm_1.7 > 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.8.

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

    curl https://storage.googleapis.com/csm-artifacts/asm/install_asm_1.7.sha256 > 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 install_asm.sha256 file includes the checksum twice to allow any version of the script to be renamed to install_asm. If you get an error that --ignore-missing does not exist, rerun the previous command without the --ignore-missing flag.

  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.

Examples

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 \
  --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
re-run the script with the '--enable_apis' flag to allow the script to enable
them on your behalf.

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 \
  --enable_apis

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.

  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

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

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 \
  -p PROJECT_ID \
  -n CLUSTER_NAME \
  -l CLUSTER_LOCATION \
  -m migrate \
  -c citadel \
  --enable_apis

Migrating 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 a migration 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 migrate \
  --ca citadel \
  --enable_all \
  --custom_overlay OVERLAY_FILE

Upgrading

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 \
  -p PROJECT_ID \
  -n CLUSTER_NAME \
  -l CLUSTER_LOCATION \
  -m upgrade \
  --enable_apis

Upgrading with an 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 upgrade 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 upgrade \
  --enable_all \
  --custom_overlay OVERLAY_FILE

Options and flags

This section describes the available arguments to the script.

Options

-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 an 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 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 IstioOperator custom resource (CR) YAML file to enable a feature that isn't enabled by default. 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 from the anthos-service-mesh package that contains the IstioOperator CR to enable an optional feature. When including one of these files, you don't need to download the anthos-service-mesh package first, and you don't specify the .yaml extension. If you need to modify any of the files, download the anthos-service-mesh 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.8-asm.10 subdirectories. The asm directory contains the configuration for the installation. The istio-1.7.8-asm.10 directory contains the extracted contents of installation file, which contains istioctl, samples, and manifests.

Flags

-e|--enable_apis
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.
-v|--verbose
Print commands before and after execution.
--dry_run
Print commands, but don't execute them.
--only_validate
Run validation but don't install Anthos Service Mesh.
--print_config
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.
--disable_canonical_service
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.
-h|--help
Show a help message describing the options and flags and exit.
--version
Print the version of install_asm and exit. If the command doesn't output a version, download the most recent version of install_asm_1.7.

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 istio.io/rev=asm-178-10 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 \
    --project=PROJECT_ID

  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.io/rev=default,istio=pilot,pod-template-hash=7744bc8dd7
istiod-asm-178-10-85d86774f7-flrt2   1/1     Running   0          26m   app=istiod,istio.io/rev=asm-178-10,istio=istiod,pod-template-hash=85d86774f7
istiod-asm-178-10-85d86774f7-tcwtn   1/1     Running   0          26m   app=istiod,istio.io/rev=asm-178-10,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 istio.io/rev=. In this example, the value is asm-178-10, 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.io/rev=REVISION 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 istio.io/rev=REVISION

  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. Relabel your namespace to enable auto-injection with the previous version of istiod. The command that you use depends on whether you used a revision label or istio-injection=enabled with the previous version.

    • If you used a revision label for auto-injection:

      kubectl label namespace NAMESPACE istio.io/rev=OLD_REVISION --overwrite

    • If you used istio-injection=enabled:

      kubectl label namespace NAMESPACE istio.io/rev- 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 calls istioctl install to deploy the Anthos Service Mesh control plane components (istiod and istio-ingressgateway) for installations, upgrades, and Istio migrations. Because the script uses istioctl install, if you need to customize Anthos Service Mesh to enable an optional feature, you have to reinstall the control plane with the new configuration.

A change was made to the install_asm script so that you can reinstall the same version of Anthos Service Mesh. When you reinstall the same version to enable an optional feature, the existing control plane configuration is overwritten. Because of this, if you customized the existing installation, you need to include the same --option and/or --custom_overlay options from from the previous installation and the --option and/or --custom_overlay options for the new feature(s) that you want to enable.

Note that if you are enabling Cloud Trace or changing a tracing setting, you also need to redeploy workloads so that the sidecar proxies are re-injected with the updated control plane configuration.

When you reinstall the same version, you specify --mode install just like for installations. For information on installing using the script, see Installing Anthos Service Mesh.

If you specify more than one IstioOperator custom resource (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.

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.

Registering your cluster

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

See Registering clusters to the fleet 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.

With Anthos Service Mesh 1.7.8, 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
    CA="mesh_ca"
  fi

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

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

  if [[ "${MODE}" = "migrate" ]]; then
    validate_istio_version
  elif [[ "${MODE}" = "upgrade" ]]; then
    validate_asm_version
    validate_ca_consistency
  fi

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

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.

set_up_project

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

required_apis() {
    cat << EOF
container.googleapis.com
compute.googleapis.com
monitoring.googleapis.com
logging.googleapis.com
cloudtrace.googleapis.com
meshca.googleapis.com
meshtelemetry.googleapis.com
meshconfig.googleapis.com
iamcredentials.googleapis.com
gkeconnect.googleapis.com
gkehub.googleapis.com
cloudresourcemanager.googleapis.com
stackdriver.googleapis.com
EOF
}

set_up_cluster

set_up_cluster(){
  if [[ "${PRINT_CONFIG}" -eq 1 ]]; then
    return 0
  fi
  add_cluster_labels
  enable_workload_identity

  init_meshconfig

  enable_stackdriver_kubernetes
  bind_user_to_cluster_admin
  ensure_istio_namespace_exists
}

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 Google Cloud console.

  • Sets a label like asmv=asm-178-10 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

install_asm() {

  local PARAMS
  PARAMS="-f ${OPERATOR_MANIFEST} -f ${MULTICLUSTER_MANIFEST}"
  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