Install dependent tools and verify cluster

This page shows you how to prepare your environment and cluster to install in-cluster Cloud Service Mesh for Kubernetes workloads off Google Cloud.

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
(Optional, in order to test connectivity) netcat (nc)

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

Set the current context to your user cluster:

Set your kubectl context to point to your off-Google Cloud cluster, according to platform-specific instructions.

Download asmcli

This section describes how to download the asmcli.

Download the version that installs Cloud Service Mesh 1.21.5 to the current working directory:

curl https://storage.googleapis.com/csm-artifacts/asm/asmcli_1.21 > asmcli

Expected output:

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                             Dload  Upload   Total   Spent    Left  Speed
100  167k  100  167k    0     0   701k      0 --:--:-- --:--:-- --:--:--  701k

Make the script executable:
```
chmod +x asmcli
```

Grant cluster admin permissions

Ensure you have set the context to your user cluster:

Note: To check existing contexts, run kubectl config get-contexts.
```
kubectl config use-context CONTEXT
```
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 Cloud 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 Cloud Service Mesh. With this option, asmcli doesn't make any changes to your project or cluster, and it doesn't install Cloud Service Mesh.

asmcli 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, asmcli downloads and extracts the installation file and downloads the asm configuration package from GitHub to a temp directory. Before exiting, asmcli 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. You might need istioctl for troubleshooting configuration issues. Additionally, the configuration files to enable optional features using asmcli 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.

Use the following command to run asmcli validate on the following platforms: Google Distributed Cloud (software only) for VMware, Google Distributed Cloud (software only) for bare metal, GKE on AWS, GKE on Azure, Amazon EKS, and Microsoft AKS.

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 \
   --fleet_id FLEET_PROJECT_ID \
   --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.
- --fleet_id The project ID of the fleet host project. asmcli validate checks that the cluster is registered to the specified fleet.
- --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 the platform is something other than Google Cloud, such as on-premises or multi-cloud.

On success, asmcli 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, asmcli 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
`asmcli` with the '--enable_gcp_apis' flag to allow `asmcli` to enable them
on your behalf.

If you got an error message about needing to run asmcli with an enablement flag, you have the following options:

Include the specific flag from the error message or the --enable_all flag when running asmcli to do the actual installation.
If you prefer, you can update your project and cluster yourself before running asmcli as described in Set up your project and GKE cluster yourself.

Note that asmcli validate doesn't allow any enablement flags because it only validates that your project and cluster are ready for installation.

Inspect cluster install and upgrade requirements

Before upgrading you should check that your configuration is compatible with the new version of Cloud 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 Cloud Service Mesh version.
```
istioctl experimental precheck
```