Setup for installing Anthos Service Mesh on GKE

This page explains the Anthos Service Mesh installation requirements and setup for your Cloud project and Google Kubernetes Engine (GKE) clusters for a mesh consisting of clusters that are in the same project. When you use the Google-provided script, install_asm, the script can configure your project and cluster for you if you include the --enable_all flag or the more granular enablement flags. If you prefer to do the setup yourself rather than having install_asm make the changes, follow the steps on this page. If you already have a previous version of Anthos Service Mesh installed, you don't need to make any changes to your project or cluster before using install_asm to upgrade to the latest Anthos Service Mesh version.

Before you begin

This guide assumes that you already have:

A Cloud project.
A Cloud Billing account.
The required tools installed
A GKE cluster that meets the requirements described in the next section.

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.
- To prepare your cluster before installing Anthos Service Mesh, you enable Workload Identity. 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.
- Optionally, 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.9.3. 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.
A Google Cloud project can only have one mesh associated with it.

When you run install_asm, it validates that your cluster meets the minimum required machine type and number of nodes.

Setting up your project

Get the project ID and project number for the project that the cluster was created in.
gcloud
Run the following command:
```
gcloud projects list
```
Console
1. Go to the Dashboard page in the Cloud Console.
  
  Go to the Dashboard page
2. Click the drop-down list at the top of the page. In the Select from window that appears, select your project.
  
  The project ID and project number are displayed on the project Dashboard Project info card.
Create the following environment variables:
- Set the workload pool using the project ID:
```
export WORKLOAD_POOL=PROJECT_ID.svc.id.goog
```
- Set the mesh ID using the project number:
```
export MESH_ID="proj-PROJECT_NUMBER"
```
Set the required Identity and Access Management (IAM) roles. If you are a Project Owner, you have all the necessary permissions to complete the installation. If you aren't a Project Owner, you need someone who is to grant you the following specific IAM roles. In the following command, replace PROJECT_ID with the project ID from the previous step and GCP_EMAIL_ADDRESS with the account that you use to log in to Google Cloud.
```
ROLES=(
'roles/servicemanagement.admin' \
'roles/serviceusage.serviceUsageAdmin' \
'roles/meshconfig.admin' \
'roles/compute.admin' \
'roles/container.admin' \
'roles/resourcemanager.projectIamAdmin' \
'roles/iam.serviceAccountAdmin' \
'roles/iam.serviceAccountKeyAdmin' \
'roles/gkehub.admin')
for role in "${ROLES[@]}"
do
  gcloud projects add-iam-policy-binding PROJECT_ID \
    --member "user:GCP_EMAIL_ADDRESS" \
    --role="$role"
done
```
If you include the --enable_all or --enable_gcp_iam_roles flag when you run install_asm, it sets the required IAM roles for you.

Enable the following Google APIs:

gcloud services enable \
    --project=PROJECT_ID \
    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</pre>

Enabling the APIs can take a minute or more to complete. When the APIs are enabled, you see output similar to the following:

Operation "operations/acf.601db672-88e6-4f98-8ceb-aa3b5725533c" finished
successfully.

If you include the --enable_all or --enable_apis flag when you run install_asm, it enables the required APIs for you.

Setting up your cluster

If you include the --enable_all flag, or one of the more granular enablement flags, the install_asm script sets up your cluster for you.

Set the default zone or region for the gcloud command-line tool. If you don't set the default here, be sure to specify either the --zone or --region option in the gcloud container clusters commands on this page.
- If you have a single-zone cluster, set the default zone:
```
gcloud config set compute/zone CLUSTER_LOCATION
```
- If you have a regional cluster, set the default region:
```
gcloud config set compute/region CLUSTER_LOCATION
```
Set the mesh_id label on the cluster. If your cluster has existing labels that you want to keep, you must include those labels when adding the mesh_id label.
1. To see if your cluster has existing labels:
```
gcloud container clusters describe CLUSTER_NAME \
    --project PROJECT_ID
```
  Look for the resourceLabels field in the output. Each label is stored on a separate line under the resourceLabels field, for example:
```
resourceLabels:
  csm: ''
  env: dev
  release: stable
```
  For convenience, you can add the labels to an environment variable. In the following, replace YOUR_EXISTING_LABELS with a comma-separated list of the existing labels on your cluster in the format KEY=VALUE, for example: env=dev,release=stable
```
export EXISTING_LABELS="YOUR_EXISTING_LABELS"
```
2. Set the mesh_id label:
  - If your cluster has existing labels that you want to keep, update the cluster with the mesh_id and the existing labels:
```
gcloud container clusters update CLUSTER_NAME \
    --project PROJECT_ID \
    --update-labels=mesh_id${MESH_ID},${EXISTING_LABELS}
```
  - If you cluster doesn't have any existing labels, update the cluster with only the mesh_id label:
```
gcloud container clusters update CLUSTER_NAME \
    --project=PROJECT_ID \
    --update-labels=mesh_id=${MESH_ID}
```

Enable Workload Identity:

gcloud container clusters update CLUSTER_NAME \
    --project=PROJECT_ID \
    --workload-pool=${WORKLOAD_POOL}

Enabling Workload Identity can take up to 10 to 15 minutes.

Enable Cloud Monitoring and Cloud Logging on GKE:

gcloud container clusters update CLUSTER_NAME \
    --project=PROJECT_ID \
    --enable-stackdriver-kubernetes

What's next

Your project and GKE cluster are now ready for a new installation or migration from Istio. When you install Anthos Service Mesh using install_asm, the script validates your project and cluster before calling istioctl install, which prevents installation failures.

Before you begin:

Chose a certificate authority
Prepare IstioOperator configuration files
Review the script's options and flags
Download the script
For new installations, see Installing Anthos Service Mesh
To migrate from Istio to Anthos Service Mesh see Migrating from Istio