Using the Anthos CLI to install Anthos Service Mesh

This guide explains how to install Anthos Service Mesh 1.4.7-asm.0 on a new Google Cloud GKE cluster using the Anthos command-line interface (CLI) with the following features enabled:

Note: When you install Anthos Service Mesh, the telemetry pipeline that powers the Anthos Service Mesh dashboard in the Google Cloud Console is installed automatically. However, the Anthos Service Mesh dashboard itself is in beta.

Currently the Anthos CLI doesn't support installations on an existing GKE cluster or on Anthos GKE on-prem.

Before you begin


  • You must have an Anthos trial license and subscription. See the Anthos Pricing guide for details.

  • Your GKE cluster must meet the following requirements:

  • Review Requirements for Pods and Services before you deploy workloads.

  • If you are installing Anthos Service Mesh on a private cluster, you must add a firewall rule to open port 9443 if you want to use automatic sidecar injection. If you don't add the firewall rule and automatic sidecar injection is enabled, you get an error when you deploy workloads. For details on adding a firewall rule, see Adding firewall rules for specific use cases.

  • Your cluster must be registered to an Anthos Environ using Connect for Anthos. Your project's Environ provides a unified way to view and manage your clusters and their workloads as part of Anthos, including clusters outside Google Cloud. Anthos charges apply only to your registered clusters. You can find out how to register a cluster in Registering a cluster.


Only one installation of Anthos Service Mesh per Google Cloud project is supported. Multiple mesh deployments in a single project aren't supported.

Certificate data

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

Setting up your environment

You can follow the installation guides using Cloud Shell, an in-browser command line interface to your Google Cloud resources, or your own computer running Linux or macOS.

Option A: Use 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 the gcloud, kubectl and helm 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 edit 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 Cloud Console.
  2. Select your Cloud project.
  3. Click the Activate Cloud Shell button at the top of the Cloud Console window.

    Google Cloud Platform console

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

    Cloud Shell session

Option B: Use command-line tools locally

On your local machine, install the following tools if you don't already have them:

  1. Install and initialize the Cloud SDK (the gcloud command-line tool).

    If you already have the Cloud SDK installed, make sure to update the components:

    gcloud components update
  2. Install kubectl:

    gcloud components install kubectl

Installing kpt and the Anthos CLI

You use kpt to install the Anthos CLI. You also use kpt to download, manage, and customize the Anthos Service Mesh resource configuration files that are stored in GitHub. The configuration files contain placeholders for your specific Google Cloud project and GKE cluster information. After you customize the configuration files, you can check them in to your own GitHub repo or other source control system.

  1. Authenticate with the Cloud SDK:

    gcloud auth login
  2. Get your Cloud project ID and create an environment variable for it:

  3. Set the default project ID for the gcloud command-line tool:

    gcloud config set project ${PROJECT_ID}
  4. Select a zone and a machine type for the new cluster. The minimum machine type required by Anthos Service Mesh is n1-standard-4.

    1. To get a list of the available GCP zones:

      gcloud compute zones list
    2. To get a list of machine types:

      gcloud compute machine-types list | more
  5. Create the following environment variables:


    The cluster name must contain only lowercase alphanumerics and '-', must start with a letter and end with an alphanumeric, and must be no longer than 40 characters.

  6. Install the Anthos CLI and update components. If you are using Cloud Shell, add sudo to the following commands:

    gcloud components install kpt anthoscli alpha
    gcloud components update
  7. Optional: Create a new directory for the Anthos Service Mesh package and cd to it.

  8. Download the Anthos Service Mesh package to the current working directory:

    kpt pkg get \ .

    By default, the kpt pkg get command populates the compute zone in the package files to match your current configuration.

  9. Set the following values in your configuration files:

    kpt cfg set asm gcloud.core.project ${PROJECT_ID}
    kpt cfg set asm cluster-name ${CLUSTER_NAME}
    kpt cfg set asm ${CLUSTER_ZONE}

Installing Anthos Service Mesh on a new cluster

  1. Run the following command to create a new cluster and install Anthos Service Mesh using the Anthos Service Mesh configuration files that you customized:

    anthoscli apply -f asm
  2. Wait for the deployment to finish:

    kubectl wait --for=condition=available --timeout=600s deployment --all -n istio-system


    deployment.extensions/istio-galley condition met
    deployment.extensions/istio-ingressgateway condition met
    deployment.extensions/istio-pilot condition met
    deployment.extensions/istio-sidecar-injector condition met
    deployment.extensions/promsd condition met

Verifying the installation

Check that the control plane Pods in istio-system are up:

kubectl get pod -n istio-system

Expect to see output similar to the following:

NAME                                      READY   STATUS      RESTARTS   AGE
istio-galley-5c65896ff7-m2pls             2/2     Running     0          18m
istio-ingressgateway-587cd459f-q6hqt      2/2     Running     0          18m
istio-nodeagent-74w69                     1/1     Running     0          18m
istio-nodeagent-7524w                     1/1     Running     0          18m
istio-nodeagent-7652w                     1/1     Running     0          18m
istio-nodeagent-7948w                     1/1     Running     0          18m
istio-pilot-9db77b99f-7wfb6               2/2     Running     0          18m
istio-sidecar-injector-69c4d9f875-dt8rn   1/1     Running     0          18m
promsd-55f464d964-lqs7w                   2/2     Running     0          18m

You should see an instance of the istio-nodeagent for each node in your cluster. Mesh CA, which replaces the Citadel OSS Istio component, creates the node agents to issue mTLS certificates for the workloads running in your service mesh.

Verify that Mesh CA is working:

  kubectl get pods -n istio-system -l app=istio-nodeagent \
  --output=jsonpath={​} -o yaml | grep CA_ADDR -A 1

Expected output:

Enable Pod Security Policies

For the best security on your service mesh, we recommend that you enable Pod Security Policies.

Injecting sidecar proxies

Anthos Service Mesh uses sidecar proxies to enhance network security, reliability, and observability. With Anthos Service Mesh, these functions are abstracted away from the application's primary container and implemented in a common out-of-process proxy delivered as a separate container in the same Pod.

Before you deploy workloads, make sure to configure sidecar proxy injection so that Anthos Service Mesh can monitor and secure traffic. You can enable automatic sidecar injection with one command, for example:

kubectl label namespace NAMESPACE istio-injection=enabled --overwrite

where NAMESPACE is the name of the namespace for your application's services or default if you didn't explicitly create a namespace.

For more information, see Injecting sidecar proxies.

Viewing the Anthos Service Mesh Dashboard

After you have workloads deployed on your cluster with the sidecar proxies injected, you can explore the Anthos Service Mesh Dashboard to see all of the observability features that Anthos Service Mesh offers.

Access to the Anthos Service Mesh Dashboard is controlled by Cloud Identity and Access Management (Cloud IAM). To access the Anthos Service Mesh Dashboard, a Project Owner must grant users the Project Editor or Viewer role, or the more restrictive roles described Controlling access to the Service Mesh Dashboard.

  1. In the Google Cloud Console, go to the Anthos Service Mesh dashboard.

    Go to the Anthos Service Mesh dashboard

  2. Select the 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 the Anthos Service Mesh Dashboard.

In addition to the Anthos Service Mesh Dashboard, 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.

Installing a sample using kpt

Optionally, you can use kpt to install the Hipster sample into the cluster.

  1. Download the sample:

    kpt pkg get \ \
  2. Enable automatic sidecar injection:

    kubectl label namespace default istio-injection=enabled
  3. Deploy the sample to the cluster:

    kubectl apply -f hipster-demo

    Now that you have a sample running, you can explore the Anthos Service Mesh Dashboard. Note that it can take up to 5 minutes for the topology graph to display the services in your mesh.

When you're finished exploring, remove the Hipster sample:

kubectl delete -f hipster-demo

What's next