Set up your project and GKE cluster yourself

When you install Anthos Service Mesh using asmcli, it can configure your project and your GKE on Google Cloud cluster for you if you include the --enable_all flag or the more granular enablement flags. If you prefer to do the setup yourself rather than having asmcli make the changes, follow the steps on this page.

If you already have a previous version of Anthos Service Mesh installed, you don't need to make any changes to your project or cluster before using asmcli to upgrade to the latest Anthos Service Mesh version.

By default, asmcli doesn't install the istio-ingressgateway. We recommend that you deploy and manage the control plane and gateways separately. Anthos Service Mesh supports auto-injection for gateway deployments, which makes Anthos Service Mesh upgrades easier. After upgrading Anthos Service Mesh, you restart the gateways just like your services to pick up the new control plane configuration. For more information, see Installing and upgrading gateways.

Before you begin

Set up your project

  1. Get the project ID and project number for the project that the cluster was created in.

    gcloud

    Run the following command:

    gcloud projects list
    

    Console

    1. Go to the Dashboard page in the Google Cloud console.

      Go to the Dashboard page

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

      The project ID and project number are displayed on the project Dashboard Project info card.

  2. Create the following environment variables:

    • Set the workload pool using the project ID:

      export WORKLOAD_POOL=PROJECT_ID.svc.id.goog
      
    • Set the mesh ID using the project number:

      export MESH_ID="proj-PROJECT_NUMBER"
      
  3. Set the required Identity and Access Management (IAM) roles. If you are a Project Owner, you have all the necessary permissions to complete the installation. If you aren't a Project Owner, you need someone who is to grant you the following specific IAM roles. In the following command, replace PROJECT_ID with the project ID from the previous step and GCP_EMAIL_ADDRESS with the account that you use to log in to Google Cloud.

    ROLES=(
    'roles/servicemanagement.admin' \
    'roles/serviceusage.serviceUsageAdmin' \
    'roles/meshconfig.admin' \
    'roles/compute.admin' \
    'roles/container.admin' \
    'roles/resourcemanager.projectIamAdmin' \
    'roles/iam.serviceAccountAdmin' \
    'roles/iam.serviceAccountKeyAdmin' \
    'roles/gkehub.admin')
    for role in "${ROLES[@]}"
    do
      gcloud projects add-iam-policy-binding PROJECT_ID \
        --member "user:GCP_EMAIL_ADDRESS" \
        --role="$role"
    done
    

    If you include the --enable_all or --enable_gcp_iam_roles flag when you run asmcli, it sets the required IAM roles for you.

  4. Enable the required Google APIs:

    gcloud services enable \
        --project=PROJECT_ID \
        mesh.googleapis.com
    

    In addition to mesh.googleapis.com, this command also enables the following APIs:

    API Description
    meshconfig.googleapis.com Relays configuration data from your mesh to Google Cloud. Additionally, allows you to access the Anthos Service Mesh pages in the Google Cloud console and to use the Anthos Service Mesh certificate authority (Mesh CA).
    meshca.googleapis.com Anthos Service Mesh certificate authority API. Allows usage of a managed certificate provider, included with Anthos Service Mesh. This API is enabled even if you are using Certificate Authority Service or Istio CA.
    container.googleapis.com Used for building and managing container based applications, powered by the open source Kubernetes technology.
    monitoring.googleapis.com Manages your Cloud Monitoring data and configurations. Used to store application telemetry displayed in the Google Cloud console.
    gkehub.googleapis.com Used to configure the scope of your mesh. For more information, see Fleet management documentation.
    stackdriver.googleapis.com Used by Google Cloud's operations suite to collect signals across Google Cloud internal and external apps, platforms, and services.
    opsconfigmonitoring.googleapis.com Collects, aggregates, and indexes resources in Google Cloud, which enables the Anthos Service Mesh UI.
    connectgateway.googleapis.com Allows Google infrastructure to securely connect to your registered GKE clusters in multiple clouds and hybrid environments.

    Enabling the APIs can take a minute or more to complete. When the APIs are enabled, you see output similar to the following:

    Operation "operations/acf.601db672-88e6-4f98-8ceb-aa3b5725533c" finished
    successfully.
    

    If you include the --enable_all or --enable_apis flag when you run asmcli, it enables the required APIs for you.

Set up your cluster

If you include the --enable_all flag, or one of the more granular enablement flags, asmcli sets up your cluster for you.

  1. Set the default zone or region for the Google Cloud CLI. If you don't set the default here, be sure to specify either the --zone or --region option in the gcloud container clusters commands on this page.

    • If you have a single-zone cluster, set the default zone:

      gcloud config set compute/zone CLUSTER_LOCATION
      
    • If you have a regional cluster, set the default region:

      gcloud config set compute/region CLUSTER_LOCATION
      
  2. Set the mesh_id label on the cluster. If your cluster has existing labels that you want to keep, you must include those labels when adding the mesh_id label.

    1. To see if your cluster has existing labels:

      gcloud container clusters describe CLUSTER_NAME \
          --project PROJECT_ID
      

      Look for the resourceLabels field in the output. Each label is stored on a separate line under the resourceLabels field, for example:

      resourceLabels:
        csm: ''
        env: dev
        release: stable

      For convenience, you can add the labels to an environment variable. In the following, replace YOUR_EXISTING_LABELS with a comma-separated list of the existing labels on your cluster in the format KEY=VALUE, for example: env=dev,release=stable

      export EXISTING_LABELS="YOUR_EXISTING_LABELS"
      
    2. Set the mesh_id label:

      • If your cluster has existing labels that you want to keep, update the cluster with the mesh_id and the existing labels:

        gcloud container clusters update CLUSTER_NAME \
            --project PROJECT_ID \
            --update-labels=mesh_id=${MESH_ID},${EXISTING_LABELS}
        
      • If you cluster doesn't have any existing labels, update the cluster with only the mesh_id label:

        gcloud container clusters update CLUSTER_NAME \
            --project=PROJECT_ID \
            --update-labels=mesh_id=${MESH_ID}
        
  3. Enable Workload Identity:

    gcloud container clusters update CLUSTER_NAME \
        --project=PROJECT_ID \
        --workload-pool=${WORKLOAD_POOL}
    

    Enabling Workload Identity can take up to 10 to 15 minutes.

  4. Register the cluster to the fleet.

  5. Initialize your project to ready it for installation. Among other things, this command creates a service account to let data plane components, such as the sidecar proxy, securely access your project's data and resources. In the following command replace FLEET_PROJECT_ID with the fleet host project:

    curl --request POST  \
     --header "Authorization: Bearer $(gcloud auth print-access-token)" \
     --header "Content-Type: application/json" \
     --data '{"workloadIdentityPools":["FLEET_PROJECT_ID.hub.id.goog","FLEET_PROJECT_ID.svc.id.goog","PROJECT_ID.svc.id.goog"]}' \
     "https://meshconfig.googleapis.com/v1alpha1/projects/PROJECT_ID:initialize"
    

    The command responds with empty curly braces: {}

  6. Enable Cloud Monitoring and Cloud Logging on GKE:

    gcloud container clusters update CLUSTER_NAME \
        --project=PROJECT_ID \
        --enable-stackdriver-kubernetes
    

Your project and cluster are now ready for a new installation using asmcli.

What's next