Create a GKE cluster with Cloud Service Mesh and the gcloud CLI

In this tutorial, you provision managed Cloud Service Mesh using the Google Kubernetes Engine (GKE) Fleet API on a new GKE public cluster. This tutorial walks you through:

  1. Configuring your Google Cloud project.
  2. Creating a GKE cluster with the minimum number of vCPUs required by Cloud Service Mesh.
  3. Registering the GKE cluster to your project's Fleet.
  4. Provisioning managed Cloud Service Mesh on the cluster using the Fleet API.
  5. Deploying an ingress gateway to expose the application.
  6. Deploying a sample application so that you can view telemetry data on the Cloud Service Mesh dashboards in the Google Cloud console.
  7. Exposing and accessing the sample application.

Fleet API

This guide assumes you are familiar with Fleets, which are logical groupings of GKE clusters and other resources that can be managed together. A Fleet is a GKE concept — not a Kubernetes concept. Registering a cluster to a Fleet allows you to provision managed Cloud Service Mesh on that cluster using the gcloud container fleet mesh update command. The use of Fleets is enabled by the Fleet API (gkehub.googleapis.com) which you enable when you begin this tutorial.

Costs

In this document, you use the following billable components of Google Cloud:

To generate a cost estimate based on your projected usage, use the pricing calculator. New Google Cloud users might be eligible for a free trial.

When you finish this quickstart, you can avoid continued billing by deleting the cluster. For more information, see Clean up.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the GKE, Fleet (GKE Hub), and Cloud Service Mesh APIs.

    Enable the APIs

    5.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the GKE, Fleet (GKE Hub), and Cloud Service Mesh APIs.

    Enable the APIs

    8.
  8. Make a note of your project ID.

Install required tools

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

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 gcloud, kubectl, git, and the other 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 at the top of the Cloud Shell window.

    • Emacs, Vim, or Nano, which you access from the command line in Cloud Shell.

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Local computer

  1. Make sure you have the following tools installed:

  2. Authenticate with the Google Cloud CLI:

    gcloud auth login --project PROJECT_ID

  3. Update the components:

    gcloud components update

Create a GKE cluster

  1. Run the following command to create the cluster with the minimum number of vCPUs required by Cloud Service Mesh. In the command, replace the placeholders with the following information:

    • CLUSTER_NAME: the name of your cluster. The name can contain only lowercase alphanumerics and -, must start with a letter and end with an alphanumeric, and must be no longer than 40 characters.
    • PROJECT_ID: the project ID that the cluster will be created in.
    • CLUSTER_LOCATION: the zone for the cluster, such as us-central1-a.
    gcloud container clusters create CLUSTER_NAME \
    --project=PROJECT_ID \
    --zone=CLUSTER_LOCATION \
    --machine-type=e2-standard-4 \
    --num-nodes=2 \
    --workload-pool=PROJECT_ID.svc.id.goog

    It takes several minutes to create the cluster. While the cluster is being created, the gcloud command displays the following:

    Creating cluster CLUSTER_NAME in CLUSTER_LOCATION...working...

    Expected output on successful creation is similar to the following:

    Creating cluster CLUSTER_NAME in CLUSTER_LOCATION...done.
Created [https://container.googleapis.com/v1/projects/PROJECT_ID/zones/CLUSTER_LOCATION/clusters/CLUSTER_NAME].
To inspect the contents of your cluster, go to: https://console.cloud.google.com/kubernetes/workload_/gcloud/CLUSTER_LOCATION/CLUSTER_NAME?project=PROJECT_ID
kubeconfig entry generated for CLUSTER_NAME.
NAME: CLUSTER_NAME
LOCATION: CLUSTER_LOCATION
MASTER_VERSION: 1.20.10-gke.1600
MASTER_IP: 198.51.100.1
MACHINE_TYPE: e2-standard-4
NODE_VERSION: 1.20.10-gke.1600
NUM_NODES: 2
STATUS: RUNNING

  2. Get authentication credentials to interact with the cluster.

    gcloud container clusters get-credentials CLUSTER_NAME \
    --project=PROJECT_ID \
    --zone=CLUSTER_LOCATION

    Expected output:

    Fetching cluster endpoint and auth data.
kubeconfig entry generated for CLUSTER_NAME.

  3. Set the current context for kubectl to the cluster.

    kubectl config set-context CLUSTER_NAME

    Expected output:

    Context "CLUSTER_NAME" created.

Provision Cloud Service Mesh

If you haven't closed this page since you created the cluster, the placeholders have the values that you entered for the gcloud container clusters create command.

  1. Enable Cloud Service Mesh on your project's Fleet.

    gcloud container fleet mesh enable --project PROJECT_ID

    The output is similar to:

    Waiting for Feature Service Mesh to be created...done.

  2. Register the cluster to the project's Fleet:

    gcloud container fleet memberships register CLUSTER_NAME-membership \
  --gke-cluster=CLUSTER_LOCATION/CLUSTER_NAME \
  --enable-workload-identity \
  --project PROJECT_ID

    The output is similar to:

     Waiting for membership to be created...done.
 Finished registering to the Fleet.

  3. Provision managed Cloud Service Mesh on the cluster using the Fleet API:

    gcloud container fleet mesh update \
  --management automatic \
  --memberships CLUSTER_NAME-membership \
  --project PROJECT_ID

    The output is similar to:

    Waiting for Feature Service Mesh to be updated...done.

  4. Verify that managed Cloud Service Mesh has been enabled for the cluster and is ready to be used:

    gcloud container fleet mesh describe --project PROJECT_ID

    It can take about 10 minutes for Cloud Service Mesh to provision and be ready to use on the cluster. If you see controlPlaneManagement.state: DISABLED or controlPlaneManagement.state: PROVISIONING, you will need to re-run the previous command every few minutes until you see controlPlaneManagement.state: ACTIVE.

    The output is similar to:

    createTime: '2022-07-06T01:05:39.110120474Z'
membershipSpecs:
  projects/123456789123/locations/global/memberships/your-cluster-membership:
    mesh:
      management: MANAGEMENT_AUTOMATIC
membershipStates:
  projects/123456789123/locations/global/memberships/your-cluster-membership:
    servicemesh:
      controlPlaneManagement:
        details:
        - code: REVISION_READY
          details: 'Ready: asm-managed'
        state: ACTIVE
      dataPlaneManagement:
        details:
        - code: OK
          details: Service is running.
        state: ACTIVE
    state:
      code: OK
      description: 'Revision(s) ready for use: asm-managed.'
      updateTime: '2022-07-06T01:19:24.243993678Z'
name: projects/your-project-id/locations/global/features/servicemesh
resourceState:
  state: ACTIVE
spec: {}
state:
  state: {}
updateTime: '2022-07-06T01:19:27.475885687Z'

Download the sample code

Clone the git repository that contains the example code used in this tutorial:

   git clone https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages.git

The next sections of this tutorial use a DIR_PATH variable. Set this variable to the path of the anthos-service-mesh-packages repository that you cloned (for example, ./anthos-service-mesh-packages).

Deploy an ingress gateway

Cloud Service Mesh gives you the option to deploy and manage gateways as part of your service mesh. A gateway describes a load balancer operating at the edge of the mesh receiving incoming or outgoing HTTP/TCP connections. Gateways are Envoy proxies that provide you with fine-grained control over traffic entering and leaving the mesh.

  1. Create a namespace for the ingress gateway if you don't already have one. Gateways are user workloads, and as a best practice, they shouldn't be deployed in the control plane namespace. Replace GATEWAY_NAMESPACE with the name of your namespace.

    kubectl create namespace GATEWAY_NAMESPACE

    Expected output:

    namespace/GATEWAY_NAMESPACE created

  2. Enable auto-injection on the gateway. The steps required depend on whether you want to use default injection labels (for example, istio-injection=enabled) or the revision label on the gateway namespace. The default revision tag and revision label are used by the sidecar injector webhook to associate injected proxies with a particular control plane revision.

    Default injection labels

    Apply the default injection labels to the namespace.

    kubectl label namespace GATEWAY_NAMESPACE istio-injection=enabled istio.io/rev-

    Revision label

    1. Use the following command to locate the revision label on istiod:

      kubectl get deploy -n istio-system -l app=istiod -o \
  "jsonpath={.items[*].metadata.labels['istio\.io/rev']}{'\n'}"

      The command outputs the revision label that corresponds to the Cloud Service Mesh version, for example: asm-1187-26

    2. Apply the revision label to the namespace. In the following command, REVISION is the value of the istiod revision label that you noted in the previous step.

      kubectl label namespace GATEWAY_NAMESPACE \
  istio.io/rev=REVISION --overwrite

      Expected output:

      namespace/GATEWAY_NAMESPACE labeled

    You can ignore the message "istio.io/rev" not found in the output. That means that the namespace didn't previously have the istio.io/rev label, which you should expect in new installations of Cloud Service Mesh or new deployments. Because auto-injection fails if a namespace has both the istio.io/rev and the istio-injection label, all kubectl label commands in the Cloud Service Mesh documentation explicitly specify both labels.

    If the gateway namespace is not labelled, the istio-ingressgateway pods will fail with an ImagePullBackOff error when the gateway attempts to pull and the auto image. This image should be replaced by the webhook.

  3. Download the example ingress gateway .yaml configuration file from the anthos-service-mesh-packages repository.

  4. Apply the example ingress gateway .yaml configuration as is, or modify as needed.

    kubectl apply -n GATEWAY_NAMESPACE \
  -f CONFIG_PATH/istio-ingressgateway

    Expected output:

    deployment.apps/istio-ingressgateway created
poddisruptionbudget.policy/istio-ingressgateway created
horizontalpodautoscaler.autoscaling/istio-ingressgateway created
role.rbac.authorization.k8s.io/istio-ingressgateway created
rolebinding.rbac.authorization.k8s.io/istio-ingressgateway created
service/istio-ingressgateway created
serviceaccount/istio-ingressgateway created

Learn more about best practices for gateways.

Deploy the Online Boutique sample

The Online Boutique sample application in the anthos-service-mesh-packages repo is modified from the original set of manifests in the microservices-demo repo. Following best practices, each service is deployed in a separate namespace with a unique service account.

  1. Create the namespaces for the application:

    kubectl apply -f \
  DIR_PATH/samples/online-boutique/kubernetes-manifests/namespaces

    Expected output:

    namespace/ad created
namespace/cart created
namespace/checkout created
namespace/currency created
namespace/email created
namespace/frontend created
namespace/loadgenerator created
namespace/payment created
namespace/product-catalog created
namespace/recommendation created
namespace/shipping created

  2. Enable automatic sidecar injection (auto-injection). The command required depends on whether you want to use default injection labels (for example, istio-injection=enabled) or the same revision label that you used to annotate the ingress gateway namespace

    Default injection labels

    Apply the default injection labels to the namespace. In the following command, GATEWAY_NAMESPACE is the same value that you used to annotate the ingress gateway namespace.

    for ns in ad cart checkout currency email frontend loadgenerator payment product-catalog recommendation shipping; do
  kubectl label namespace $ns istio-injection=enabled istio.io/rev-
done;

    Expected output:

    namespace/ad labeled
namespace/cart labeled
namespace/checkout labeled
namespace/currency labeled
namespace/email labeled
namespace/frontend labeled
namespace/loadgenerator labeled
namespace/payment labeled
namespace/product-catalog labeled
namespace/recommendation labeled
namespace/shipping labeled

    Revision label

    Apply the revision label to the application namespaces. In the following command, REVISION is the same value that you used to annotate the ingress gateway namespace.

    for ns in ad cart checkout currency email frontend loadgenerator payment product-catalog recommendation shipping; do
  kubectl label namespace $ns istio.io/rev=REVISION --overwrite
done;

    Expected output:

    namespace/ad labeled
namespace/cart labeled
namespace/checkout labeled
namespace/currency labeled
namespace/email labeled
namespace/frontend labeled
namespace/loadgenerator labeled
namespace/payment labeled
namespace/product-catalog labeled
namespace/recommendation labeled
namespace/shipping labeled

  3. Deploy the sample application to the cluster.

    1. Create the service accounts and deployments:

      kubectl apply -f \
 DIR_PATH/samples/online-boutique/kubernetes-manifests/deployments

      Expected output:

      serviceaccount/ad created
deployment.apps/adservice created
serviceaccount/cart created
deployment.apps/cartservice created
serviceaccount/checkout created
deployment.apps/checkoutservice created
serviceaccount/currency created
deployment.apps/currencyservice created
serviceaccount/email created
deployment.apps/emailservice created
serviceaccount/frontend created
deployment.apps/frontend created
serviceaccount/loadgenerator created
deployment.apps/loadgenerator created
serviceaccount/payment created
deployment.apps/paymentservice created
serviceaccount/product-catalog created
deployment.apps/productcatalogservice created
serviceaccount/recommendation created
deployment.apps/recommendationservice created
serviceaccount/shipping created
deployment.apps/shippingservice created

    2. Create the services:

      kubectl apply -f \
 DIR_PATH/samples/online-boutique/kubernetes-manifests/services

      Expected output:

      service/adservice created
service/cartservice created
service/checkoutservice created
service/currencyservice created
service/emailservice created
service/frontend created
service/frontend-external created
service/paymentservice created
service/productcatalogservice created
service/recommendationservice created
service/shippingservice created

    3. Create the service entries:

      kubectl apply -f \
 DIR_PATH/samples/online-boutique/istio-manifests/allow-egress-googleapis.yaml

      Expected output:

      serviceentry.networking.istio.io/allow-egress-googleapis created
serviceentry.networking.istio.io/allow-egress-google-metadata created

Exposing and accessing the application

There are multiple ways to expose the application. In this guide, we will use the ingress gateway we deployed above to do that. For other ways to expose the Online Boutique application refer to exposing and accessing the application section in the Deploying the Online Boutique sample application guide.

  1. Deploy a Gateway and VirtualService for the frontend service

    kubectl apply -f \
    DIR_PATH/samples/online-boutique/istio-manifests/frontend-gateway.yaml

    Expected output:

    gateway.networking.istio.io/frontend-gateway created
virtualservice.networking.istio.io/frontend-ingress created

  2. Get the external IP address of the ingress gateway, replace the placeholders with the following information:

    • GATEWAY_SERVICE_NAME: the name of ingress gateway service. If you deployed the sample gateway without modification that would be istio-ingressgateway.
    • GATEWAY_NAMESPACE: the namespace in which you deployed the ingress gateway:
    kubectl get service GATEWAY_SERVICE_NAME \
    -n GATEWAY_NAMESPACE

    The output is similar to:

    NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                      AGE
istio-ingressgateway   LoadBalancer   10.19.247.233   35.239.7.64   80:31380/TCP,443:31390/TCP,31400:31400/TCP   27m

    In this example, the IP address of the ingress gateway is 35.239.7.64.

  3. Visit the application on your browser to confirm installation:

    http://EXTERNAL_IP/

View the Service Mesh dashboards

After you have workloads deployed on your cluster with the sidecar proxies injected, you can explore the Cloud Service Mesh pages in the Google Cloud console to see all of the observability features that Cloud 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 Cloud Service Mesh in the Google Cloud console is controlled by Identity and Access Management (IAM). To access the Cloud 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 Cloud Service Mesh in the Google Cloud console.

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

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

Clean up

Before cleaning up, if you are interested in learning more about mutual TLS, see Cloud Service Mesh by example: mTLS.

  • If you want to keep your cluster and remove the Online Boutique sample:

    1. Delete the application namespaces:

      kubectl delete -f DIR_PATH/samples/online-boutique/kubernetes-manifests/namespaces

      Expected output:

      namespace "ad" deleted
namespace "cart" deleted
namespace "checkout" deleted
namespace "currency" deleted
namespace "email" deleted
namespace "frontend" deleted
namespace "loadgenerator" deleted
namespace "payment" deleted
namespace "product-catalog" deleted
namespace "recommendation" deleted
namespace "shipping" deleted

    2. Delete the service entries:

      kubectl delete -f DIR_PATH/samples/online-boutique/istio-manifests/allow-egress-googleapis.yaml

      Expected output:

      serviceentry.networking.istio.io "allow-egress-googleapis" deleted
serviceentry.networking.istio.io "allow-egress-google-metadata" deleted

  • If you want to prevent additional charges, delete the cluster:

    1. Run the following command:

      gcloud container clusters delete CLUSTER_NAME \
    --project=PROJECT_ID \
    --zone=CLUSTER_LOCATION

    2. At the Do you want to continue (Y/n)? prompt, enter y.

      After a few minutes, you see the following output:

      Deleting cluster CLUSTER_NAME...done.
Deleted [https://container.googleapis.com/v1/projects/PROJECT_ID/zones/CLUSTER_LOCATION/clusters/CLUSTER_NAME].

What's next