Installing Anthos Service Mesh using the GKE Enterprise CLI

Note: The GKE Enterprise CLI is no longer supported.

Alpha

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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

• Anthos Service Mesh observability features
• Anthos Service Mesh security features, including Anthos Service Mesh certificate authority (Mesh CA)
• Supported Istio features

Currently the GKE Enterprise CLI doesn't support installations on an existing GKE cluster or on GKE on VMware.

Before you begin

This guide assumes that you already have:

• A Google Cloud project.
• A Cloud Billing account.

Requirements

• You must have an GKE Enterprise trial license or subscription. See the GKE Enterprise Pricing guide for details.

• Your GKE cluster must meet the following requirements:

  • At least four nodes.
  • The minimum machine type is e2-standard-4, which has four vCPUs.
  • Use a release channel rather than a static version of GKE

• 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, Naming service ports.

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

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

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

Important: The certificates issued by Mesh CA should only be used to enable secure service-to-service communication within your service mesh, and not be used for any other purpose. These certificates are sent whenever services attempt to communicate with each other using mutual TLS. Make sure that you don't inadvertently expose confidential information by using these certificates when communicating outside your service mesh.

Installing kpt and the Anthos CLI

You use kpt to install the GKE Enterprise 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 Google Cloud CLI:

   gcloud auth login
   

2. Get your Google Cloud project ID and create an environment variable for it:

   export PROJECT_ID=YOUR_PROJECT_ID

3. Set the default project ID for the Google Cloud CLI:

   gcloud config set project ${PROJECT_ID}
   

4. Select a zone or region and a machine type for the new cluster. The minimum machine type required by Anthos Service Mesh is n1-standard-4. You can use any release channel option.

   • If you will be creating a single-zone cluster, run the following command to get a list of the available GCP zones:

     gcloud compute zones list
     

   • If you will be creating a regional cluster, run the following command to get a list of the available regions:

     gcloud compute regions list
     

   • To get a list of machine types:

     gcloud compute machine-types list | more
     

5. Create the following environment variables:

   • Set the cluster name:

     export CLUSTER_NAME=YOUR_CLUSTER_NAME

     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.

   • Set the CLUSTER_LOCATION to either your cluster zone or cluster region:

     export CLUSTER_LOCATION=YOUR_ZONE_OR_REGION

6. Install the GKE Enterprise 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 --version 292.0.0

7. Optionally, 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 \
   https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages.git/asm@release-1.4-asm .
   

   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:

   • Set the project ID:

     kpt cfg set asm gcloud.core.project ${PROJECT_ID}

   • Set the cluster name:

     kpt cfg set asm cluster-name ${CLUSTER_NAME}

   • Set the default zone or region:

     kpt cfg set asm gcloud.compute.zone ${CLUSTER_LOCATION}

   • Optionally, change the release channel from the default, REGULAR. In the following command, replace YOUR_CHANNEL with either STABLE or RAPID.

     kpt cfg set asm gcloud.container.cluster.releaseChannel YOUR_CHANNEL

     For a description of each channel, see What channels are available.

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
   

   Output:

   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

Caution: Installing Anthos Service Mesh enables the node agent secret discovery service (SDS). If you haven't enforced a Pod security policy, we recommend that you create and enable Pod security policies to secure SDS. For more information, see Enabling Pod Security Policies.

Check the control plane components

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={​.items..metadata.name} -o yaml | grep CA_ADDR -A 1

Expected output: meshca.googleapis.com:443.

Registering your cluster

You must register your cluster with the project's fleet to gain access to the unified user interface in the Google Cloud console. A fleet provides a unified way to view and manage the clusters and their workloads, including clusters outside Google Cloud.

Create a Google Cloud service account and key file

A JSON file containing service account credentials is required to register a cluster. To follow the principle of least privilege, we recommend that you create a distinct service account for each cluster that you register.

To create a service account and key file:

1. Select a name for the service account and create an environment variable for it:

   export SERVICE_ACCOUNT_NAME=SERVICE_ACCOUNT_NAME
   

2. Create the service account:

   gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME}

3. List all of a project's service accounts to confirm the service account was created:

   gcloud iam service-accounts list

4. Bind the gkehub.connect IAM role to the service account:

   gcloud projects add-iam-policy-binding ${PROJECT_ID} \
      --member="serviceAccount:${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
      --role="roles/gkehub.connect"

5. Create an environment variable for the local filepath where you want to save the JSON file. We recommend that you name the file using the service account name and your project ID, such as: /tmp/creds/${SERVICE_ACCOUNT_NAME}-${PROJECT_ID}.json

   export SERVICE_ACCOUNT_KEY_PATH=LOCAL_KEY_PATH

6. Download the service account's private key JSON file:

   gcloud iam service-accounts keys create ${SERVICE_ACCOUNT_KEY_PATH} \
      --iam-account=${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

Register the cluster

In the following command, replace MEMBERSHIP_NAME with a name that uniquely represents the cluster being registered on the Hub.

gcloud container hub memberships register MEMBERSHIP_NAME \
    --gke-cluster=${CLUSTER_LOCATION}/${CLUSTER_NAME} \
    --service-account-key-file=${SERVICE_ACCOUNT_KEY_PATH}

The command responds with output similar to the following:

kubeconfig entry generated for CLUSTER_NAME.
Waiting for membership to be created...done.
Created a new membership [projects/PROJECT_ID/locations/global/memberships/MEMBERSHIP_NAME] for the cluster [MEMBERSHIP_NAME]
Generating the Connect Agent manifest...
Deploying the Connect Agent on cluster [MEMBERSHIP_NAME] in namespace [gke-connect]...
Deployed the Connect Agent on cluster [MEMBERSHIP_NAME] in namespace [gke-connect].
Finished registering the cluster [MEMBERSHIP_NAME] with the Hub.

This service account key is stored as a secret named creds-gcp in the gke-connect namespace.

For more information about cluster registration, see Registering a cluster in the Connect documentation.

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 pages

After you have workloads deployed on your cluster with the sidecar proxies injected, you can explore the Anthos Service Mesh pages in the Google 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 Google Cloud console after you deploy workloads.

Access to Anthos Service Mesh in the Google 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 Google Cloud console.

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

   Go to Anthos Service Mesh

2. Select the Google 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 Google 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.

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 \
   https://github.com/GoogleCloudPlatform/microservices-demo.git/release \
   hipster-demo
   

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

• Enable pod security policies