Single project installation on GKE

Warning: install_asm and istioctl install commands are deprecated with the release of Anthos Service Mesh 1.11 and will be unsupported with the 1.12 release. Please update your scripts and tools to use asmcli. For more information, see Transitioning to asmcli.

This guide explains how to install, migrate, or upgrade to Anthos Service Mesh version 1.11.8 for a mesh containing one or more GKE clusters that are in the same project. You use a Google-provided script, install_asm which configures your project and cluster, and then installs Anthos Service Mesh using istioctl install.

You can use this guide and the script for the following onboarding use cases:

• New installations of Anthos Service Mesh 1.11.8.

• Upgrading from any version and patch release 1.7 or higher to Anthos Service Mesh 1.11.8. Upgrades from earlier versions aren't supported.

• Migrating from open source Istio to Anthos Service Mesh. If you have Istio 1.6 or earlier, you must upgrade first before migrating to Anthos Service Mesh. If you have Istio 1.7 or later, you might be able to use Migrating from Istio 1.7 or later to Anthos Service Mesh and Mesh CA. If you need to upgrade, go to the Upgrade Istio page in the applicable version of Istio. Note that Upgrading Istio across more than one minor version (for example, 1.6.x to 1.8.x) in one step is not officially tested or recommended. Be sure to review Preparing to migrate from Istio to plan your migration.

Note:

For information about other Anthos Service Mesh onboarding use cases, see the following:

• For installation instructions where the clusters are in different projects, see the GKE multi-project guide.
• After you have installed Anthos Service Mesh, if you need to configure a multi-cluster service mesh, see Setting up a multi-cluster mesh.

Prerequisites

This guide assumes that you have the following:

• A Google Cloud project
• A Cloud Billing account
• A GKE cluster that meets the requirements.

Anthos and Anthos Service Mesh differences

Anthos Service Mesh is available with GKE Enterprise or as a standalone service. Google APIs are used to determine how you are billed. To use Anthos Service Mesh as a standalone service, don't enable the GKE Enterprise API in your project. The script enables all of the other required Google APIs for you. For information about Anthos Service Mesh pricing, see Pricing.

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

• If you enabled the GKE Enterprise API, but you want to use Anthos Service Mesh as a standalone service, disable the GKE Enterprise API.

Requirements

• Your GKE cluster must meet the following requirements:

  • The GKE cluster must be Standard, because Autopilot clusters have Webhooks limitations that don't allow the MutatingWebhookConfiguration for the istio-sidecar-injector.

  • 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_registration flag 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.11.8. For more information, see Supported platforms. 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 webhooks used for automatic sidecar injection and configuration validation to work. 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.

• A Google Cloud project can only have one mesh associated with it.

• If you want to change the default resource limits for the istio-proxy sidecar container, the new values must be greater than the default values to avoid out-of-memory (OOM) events.

• For Windows Server workloads, Istio is not supported. If your cluster has both Linux and Windows Server node pools, you can still install Anthos Service Mesh and use it on your Linux workloads.

Customizing the control plane

The features that Anthos Service Mesh supports differ between platforms. We recommend that you review the Supported features to learn which features are supported on GKE on Google Cloud. Some features are enabled by default, and others you can optionally enable by creating an IstioOperator overlay file. When you run the install_asm script, you can specify the --custom_overlay option with the overlay file.

Choosing a certificate authority

For both new installations and migrations from Istio, you can use Anthos Service Mesh certificate authority (Mesh CA) or Istio's Citadel as the certificate authority (CA) for issuing mutual TLS (mTLS) certificates.

Unless you require a custom CA, such as HashiCorp Vault, we 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.

If you're migrating from Istio, you can choose to migrate to Mesh CA or continue using the Istio CA. Migrating to Mesh CA from the Istio CA requires migrating the root of trust. You have the following options when migrating to Mesh CA:

• Schedule downtime for the migration. Operationally, this is the easiest option, but because mTLS traffic is interrupted during the migration, you need to schedule downtime. For an example of using the script in this case, see Migrating to Mesh CA with downtime.

• Distribute the new root of trust and then migrate to Mesh CA. With this approach, mTLS traffic isn't interrupted so you don't have to schedule downtime, but the migration process has many more steps. For more information, see Migrating to Mesh CA.

If you choose to continue using the Istio CA when you migrate to Anthos Service Mesh, mTLS traffic isn't interrupted because the root CA isn't changed. Although this migration path isn't disruptive to your existing workloads, you are limited to using the in-cluster control plane. The Google managed control plane requires Mesh CA.

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

Important: The certificates issued by Mesh CA should only be used to enable secure service-to-service communication within your service mesh, and not be used for any other purpose. These certificates are sent whenever services attempt to communicate with each other using mutual TLS. Make sure that you don't inadvertently expose confidential information by using these certificates when communicating outside your service mesh.

Registering your cluster

You must register your cluster with the 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.

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: The installation script only supports Linux operating systems.

Cloud Shell

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 gcloud, kubectl, 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:

1. Go to the Google Cloud console.
2. Select your Google Cloud project.

3. Click the Activate Cloud Shell button at the top of the Google Cloud console window.

   

   A Cloud Shell session opens inside a new frame at the bottom of the Google Cloud console and displays a command-line prompt.

   

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

5. Copy the long command and paste it to update the components.

Local Linux computer

1. Make sure you have the following tools installed:

   • The Google Cloud CLI
   • The standard command-line tools: awk, curl, grep, sed, and tr
   • git
   • kpt
   • kubectl
   • jq

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.

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.

1. Download the version of the script that installs Anthos Service Mesh 1.11.8 to the current working directory:

   curl https://storage.googleapis.com/csm-artifacts/asm/install_asm_1.11 > install_asm
   

   Note: We recommend that you always download the latest version of the install_asm script when you install Anthos Service Mesh on a new GKE cluster. The command in the previous step downloads the latest version.

2. Make the script executable:

   chmod +x install_asm
   

What's next

• New installations of Anthos Service Mesh
• Upgrading Anthos Service Mesh to the latest version
• Migrating from Istio
• Reinstalling the same version
• Reference