Get started

This page shows you how to prepare your environment and cluster to install Anthos Service Mesh

Install required tools

You can run asmcli on Cloud Shell or on your local machine running Linux. Cloud Shell pre-installs all the required tools.

If you are running asmcli locally, make sure you have the following tools installed:

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

Configure gcloud

Do the following steps even if you are using Cloud Shell.

Authenticate with the Google Cloud CLI:
```
gcloud auth login --project PROJECT_ID
```
Update the components:
```
gcloud components update
```
If you are installing Anthos Service Mesh on a GKE cluster, configure kubectl to point to the cluster.

Note: Use --region instead of --zone, if the cluster is a regional cluster.
```
gcloud container clusters get-credentials CLUSTER_NAME \
     --zone CLUSTER_LOCATION \
     --project PROJECT_ID
```

Download asmcli

This section describes how to download the asmcli.

Download the version that installs Anthos Service Mesh 1.10.6 to the current working directory:
```
curl https://storage.googleapis.com/csm-artifacts/asm/asmcli_alpha > asmcli
```
Note: We recommend that you always download the latest version of asmcli when installing Anthos Service Mesh on a new GKE cluster. The command in the previous step downloads the latest version.
Make the script executable:
```
chmod +x asmcli
```

Grant cluster admin permissions

Switch context to your user cluster:
```
kubectl config use-context CLUSTER_NAME
```
Grant cluster admin permissions to your user account (your Google Cloud login email address). You need these permissions to create the necessary role based access control (RBAC) rules for Anthos Service Mesh:
```
kubectl create clusterrolebinding cluster-admin-binding \
  --clusterrole=cluster-admin \
  --user=USER_ACCOUNT
```

Validate project and cluster

You can run asmcli validate to make sure that your project and cluster are setup as required to install Anthos Service Mesh. With this option, asmcli doesn't make any changes to your project or cluster, and it doesn't install Anthos Service Mesh.

The script validates that:

Your environment has the required tools.
The cluster meets the minimum requirements.
You have the required permissions on the specified project.
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. We recommend that you specify a 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.

GKE

./asmcli validate \
  --project_id PROJECT_ID \
  --cluster_name CLUSTER_NAME \
  --cluster_location CLUSTER_LOCATION \
  --output_dir DIR_PATH

--project_id, --cluster_name, and --cluster_location Specify the project ID that the cluster is in, the cluster name, and either the cluster zone or region.
- --output_dir Include this option to specify a directory where asmcli downloads the asm package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp directory. You can specify either a relative path or a full path. The environment variable $PWD doesn't work here.

On-premises

Set the current context to your user cluster:
```
kubectl config use-context CLUSTER_NAME
```
Run the following command to validate your configuration and download the installation file and asm package to the OUTPUT_DIR directory:
```
./asmcli validate \
  --kubeconfig KUBECONFIG_FILE \
  --output_dir DIR_PATH \
  --platform multicloud
```
- --kubeconfig The path to the kubeconfig You can specify either a relative path or a full path. The environment variable $PWD doesn't work here.
- --output_dir Include this option to specify a directory where asmcli downloads the asm package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp directory. You can specify either a relative path or a full path. The environment variable $PWD doesn't work here.
- --platform multicloud Specifies that on-premises is the platform.

On success, the script outputs the following:

asmcli: Setting up necessary files...
asmcli: Using asm_kubeconfig as the kubeconfig...
asmcli: Checking installation tool dependencies...
asmcli: Fetching/writing GCP credentials to kubeconfig file...
asmcli: Verifying connectivity (10s)...
asmcli: kubeconfig set to asm_kubeconfig
asmcli: using context gke_example-project-12345_us-central1_cluster-2
asmcli: Getting account information...
asmcli: Downloading ASM..
asmcli: Downloading ASM kpt package...
fetching package "/asm" from "https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages" to "asm"
asmcli: Checking required APIs...
asmcli: Checking for project example-project-12345...
asmcli: Reading labels for us-central1/cluster-2...
asmcli: Checking for istio-system namespace...
asmcli: Confirming node pool requirements for example-project-12345/us-central1/cluster-2...
asmcli: Checking Istio installations...
asmcli: [WARNING]: There is no way to validate that the meshconfig API has been initialized.
asmcli: [WARNING]: This needs to happen once per GCP project. If the API has not been initialized
asmcli: [WARNING]: for example-project-12345, please re-run this tool with the --enable_gcp_components
asmcli: [WARNING]: flag. Otherwise, installation will succeed but Anthos Service Mesh
asmcli: [WARNING]: will not function correctly.
asmcli: Successfully validated all requirements to install ASM.

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 have the following options:

Include the specific flag from the error message or the --enable_all flag when running the script to do the actual installation (that is, without --only_validate).
If you prefer, you can update your project and cluster yourself before running the script as described in Setup for installing Anthos Service Mesh on GKE.

Note that asmcli doesn't allow any enablement flags with --only_validate.

Inspect cluster install and upgrade requirements

Before upgrading you should check that your configuration is compatible with the new version of Anthos Service Mesh.

Change to the directory that you specified in --output_dir.
Run the following command to inspect the Kubernetes cluster for install and upgrade requirements. Make sure you use the version of istioctl distributed with the new Anthos Service Mesh version.
```
istioctl experimental precheck
```