Anthos Service Mesh 1.6

Installing Anthos Service Mesh on an existing cluster using the Anthos CLI

This guide explains how to do a clean installation of Anthos Service Mesh version 1.6.8-asm.9 on an existing GKE on Google Cloud cluster using the Anthos command-line interface (CLI). If you have a previous version of Anthos Service Mesh installed, refer to Upgrading Anthos Service Mesh on GKE.

The Anthos CLI provides a simple and declarative way to configure your Google Cloud project and update an existing GKE on Google Cloud cluster that meets all requirements, and then installs Anthos Service Mesh on the cluster. The Anthos CLI supports installations only on GKE on Google Cloud. To install Anthos Service Mesh on other environments, refer to the following guides:

To install Anthos Service Mesh on Google Cloud with the asm-gcp-multiproject configuration profile or with Citadel as the certificate authority instead of Anthos Service Mesh certificate authority (Mesh CA), refer to Installing Anthos Service Mesh on Google Cloud.

The installation enables the following features:

This guide also explains how to register your cluster in your project's environ. An environ lets you organize clusters to make multi-cluster management easier. By registering your clusters in an environ, you can group services and other infrastructure as needed to apply consistent policies.

Before you begin

Before you start the installation:

Requirements

  • Your GKE cluster must meet the following requirements:

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

Restrictions

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 environment variables

  1. Get the project ID that the cluster was created in.

    gcloud

    gcloud projects list
    

    Console

    1. Go to the Dashboard page in the Cloud Console.

      Go to the Dashboard page

    2. Click the Select from drop-down list at the top of the page. In the Select from window that appears, select your project.

      The project ID is displayed on the project Dashboard Project info card.

  2. Create an environment variable for the project ID:

    export PROJECT_ID=YOUR_PROJECT_ID

  3. Create an environment variable for the project number:

    export ENVIRON_PROJECT_NUMBER=$(gcloud projects describe ${PROJECT_ID} --format="value(projectNumber)")

    Although this is the same project number that the cluster was created in, this project number is used for the Mesh ID that is set on the cluster and in Anthos Service Mesh. You also use this project number when you register your cluster with the environ.

  4. Create an environment variable for the cluster name:

    export CLUSTER_NAME=YOUR_CLUSTER_NAME
  5. Create an environment variable for either your cluster zone or region:

    export CLUSTER_LOCATION=YOUR_ZONE_OR_REGION

Preparing resource configuration files

You use the Anthos CLI and kustomize to export and patch Config Connector resource files that you will use to update an existing cluster with the options required by Anthos Service Mesh. The Config Connector resource is the Kubernetes representation of Google Cloud resources.

Export resource configuration files

You use the gcloud beta anthos export command to output resource configuration files for an existing cluster.

  1. Download the asm-patch package to the current working directory:

    kpt pkg get \
    https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages.git/asm-patch@release-1.6-asm .
    

    The command creates a subdirectory called asm-patch/.

  2. Add a directory name in an environment variable called BASE_DIR. We recommend that you use the cluster name as the directory name.

    export BASE_DIR=YOUR_BASE_DIR

    Note the following:

    • You can specify a relative path forBASE_DIR instead of a directory name, for example: export BASE_DIR=../example-resources/example-cluster

    • Don't specify an absolute path such as /usr/example-resources/example-cluster because the step to patch the resource configuration file fails.

    • You don't need to create the directory because the gcloud beta anthos export command creates the directory automatically. If a directory exists, the export command creates a directory called $BASE_DIR.bak.<number>, moves the contents of $BASE_DIR to the backup directory, and then exports the resource configuration file to $BASE_DIR.

  3. Export the cluster settings to a Config Connector resource configuration file:

    gcloud beta anthos export ${CLUSTER_NAME} \
        --output-directory ${BASE_DIR} \
        --project ${PROJECT_ID} \
        --location ${CLUSTER_LOCATION}

    By default, the export command populates the project ID and your cluster zone/region in the configuration file to match the current gcloud config settings, unless you specify the --project and --location options on the command line. Check gcloud beta anthos export --help for more information about command-line options.

Patch the resource configuration files

You use the Anthos kpt setters and kustomize to update the resource configuration files.

To set the required values and apply the patches:

  1. Set the relative path between the ${BASE_DIR} and the asm-patch directories:

    kpt cfg set asm-patch/ base-dir ../${BASE_DIR}
    
  2. Set the project ID:

    kpt cfg set asm-patch/ gcloud.core.project ${PROJECT_ID}
    
  3. Set the project number:

    kpt cfg set asm-patch gcloud.project.environProjectNumber ${ENVIRON_PROJECT_NUMBER}
    
  4. Set the cluster name:

    kpt cfg set asm-patch/ gcloud.container.cluster ${CLUSTER_NAME}
    
  5. Set the cluster location:

    kpt cfg set asm-patch/ gcloud.compute.location ${CLUSTER_LOCATION}
    
  6. Apply the Anthos Service Mesh patches to the cluster resource configuration files:

    pushd ${BASE_DIR} && kustomize create --autodetect \
    --namespace ${PROJECT_ID} && popd
    pushd asm-patch && kustomize build -o ../${BASE_DIR}/all.yaml && popd

Validate the final resource configurations

Before you update your clusters and install Anthos Service Mesh, you must validate the resource configuration files:

kpt fn source ${BASE_DIR} | kpt fn run --image gcr.io/kustomize-functions/validate-asm:v0.1.0

Following are some errors that you might encounter:

error - unsupported spec.releaseChannel.channel value in ContainerCluster
cluster_name< (all.yaml [7]), expected: REGULAR, RAPID,STABLE, actual:
UNSPECIFIED

This error indicates that you haven't enrolled your 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.6.8. For more information, see Supported environments. After enrolling your cluster in a release channel:

  1. Delete the $BASE_DIR directory.

  2. Repeat the steps to export and patch the resource configuration files.

  2 error(s) occurred:
    * Error - spec.workloadIdentity.identityNamespace missing in ContainerCluster cluster_name (all.yaml [0])
    * Error - spec.labels.mesh_id missing in ContainerCluster cluster_name (all.yaml [0])

These errors indicate that applying the patches to the resource configuration failed. This failure can happen when $BASE_DIR is set to an absolute path. To fix this failure:

  1. Set the $BASE_DIR environment variable to a directory name. We recommend that you use the cluster name.

  2. Repeat the steps to export and patch the resource configuration files.

Updating your cluster and installing Anthos Service Mesh

The Anthos CLI updates your cluster with the following options, which are required by Anthos Service Mesh:

  • Adds a mesh_id label to the cluster in the format proj-${ENVIRON_PROJECT_NUMBER}, where ${ENVIRON_PROJECT_NUMBER} is the project number of the project that the cluster was created in. The mesh_id label is required for metrics to get displayed on the Anthos Service Mesh dashboard in the Cloud Console. If your cluster has existing labels, the Anthos CLI preserves them.

  • Enables Workload Identity.

  • Enables Kubernetes Engine Monitoring.

Run the following command to update the cluster and install Anthos Service Mesh:

gcloud beta anthos apply ${BASE_DIR}

The command updates your cluster with the required options and then deploys Anthos Service Mesh. This process takes about 30 minutes to complete.

Checking the control plane components

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

kubectl get pod -n istio-system

Expected output is similar to the following:

NAME                                   READY   STATUS      RESTARTS   AGE
istio-ingressgateway-cff9f5c7d-qg4ls   1/1     Running   0          7m5s
istio-ingressgateway-cff9f5c7d-vlkzb   1/1     Running   0          7m20s
istiod-66b587859c-886gx                1/1     Running   0          7m33s
istiod-66b587859c-dfs2j                1/1     Running   0          7m33s

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.

Any workloads that were running on your cluster before you installed Anthos Service Mesh need to have the sidecar proxy injected or updated so they have the current Anthos Service Mesh version. Before you deploy new 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 pages

This section is applicable only if you installed Anthos Service Mesh with the asm-gcp configuration profile. If you used the asm-gcp-multiproject profile to install Anthos Service Mesh, telemetry data won't be available on the Anthos Service Mesh dashboards in the Cloud Console.

After you have workloads deployed on your cluster with the sidecar proxies injected, you can explore the Anthos Service Mesh pages in the Cloud Console to see all of the observability features that Anthos Service Mesh offers. Note that it takes about one or two minutes for telemetry data to be displayed in the Cloud Console after you deploy workloads.

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

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

    Go to Anthos Service Mesh

  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 Anthos Service Mesh in the Cloud Console.

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

What's next