Set up your project and cluster yourself

When you install Cloud Service Mesh usingasmcli, it canconfigure your project and your cluster foryou if you include the--enable_all flag or the more granularenablement flags.If you prefer to do the setup yourself rather than havingasmcli make thechanges, follow the steps on this page.

If you already have a previous version of Cloud Service Mesh installed, you don'tneed to make any changes to your project or cluster before usingasmcli to upgrade to the latestCloud Service Mesh version.

By default,asmcli doesn't install theistio-ingressgateway. Werecommend that you deploy and manage the control plane and gateways separately.Cloud Service Mesh supports auto-injection for gateway deployments, which makesCloud Service Mesh upgrades easier. After upgrading Cloud Service Mesh, you restart thegateways just like your services to pick up the new control plane configuration.For more information, seeInstalling and upgrading gateways.

Warning: On upgrades,asmcli removes the defaultistio-ingressgateway fromtheistio-system namespace. If you need thedefaultistio-ingressgateway installed with the in-cluster control plane,include the--option legacy-default-ingressgateway argument.

Before you begin

Set up your project

  1. Get the project ID for the project that the cluster wascreated in.

    gcloud

    Run the following command:

    gcloud projects list

    Console

    1. Go to theDashboard page in theGoogle Cloud console.

      Go to the Dashboard page

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

      The project ID is displayed on the project DashboardProject infocard.

  2. Create an environment variable for the workload pool using the project ID:

    export WORKLOAD_POOL=PROJECT_ID.svc.id.goog

  3. Set the required Identity and Access Management (IAM) roles. If you are aProject Owner, you have all the necessary permissions to completethe installation. If you aren't aProject Owner, you need someone who isto grant you the following specific IAM roles. In thefollowing command, replacePROJECT_ID with theproject ID from the previous step andGCP_EMAIL_ADDRESSwith the account that you use to sign 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-bindingPROJECT_ID \    --member "user:GCP_EMAIL_ADDRESS" \    --role="$role"done

    If you include the--enable_all or--enable_gcp_iam_roles flag whenyou runasmcli, 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 tomesh.googleapis.com, this command also enables thefollowing APIs:

    Note: Some required APIs have transitive dependencies on other APIs.

    APIPurposeCan Be Disabled
    meshconfig.googleapis.comCloud Service Mesh uses the Mesh Configuration API to relay configuration data from your mesh to Google Cloud. Additionally, enabling the Mesh Configuration API lets you access the Cloud Service Mesh pages in the Google Cloud console and to use the Cloud Service Mesh certificate authority.No
    meshca.googleapis.comRelated to Cloud Service Mesh certificate authority used by managed Cloud Service Mesh.No
    container.googleapis.comRequired to create Google Kubernetes Engine (GKE) clusters.No
    gkehub.googleapis.comRequired to manage the mesh as afleet.No
    monitoring.googleapis.comRequired to capture telemetry for mesh workloads.No
    stackdriver.googleapis.comRequired to use the Services UI.No
    opsconfigmonitoring.googleapis.comRequired to use the Services UI for off-Google Cloud clusters.No
    connectgateway.googleapis.comRequired so that the managed Cloud Service Mesh control plane can access mesh workloads.Yes*
    trafficdirector.googleapis.comEnables a highly available and scalable managed control plane.Yes*
    networkservices.googleapis.comEnables a highly available and scalable managed control plane.Yes*
    networksecurity.googleapis.comEnables a highly available and scalable managed control plane.Yes*
    Warning: Disablingconnectgateway.googleapis.com,trafficdirector.googleapis.com,networkservices.googleapis.com, and/ornetworksecurity.googleapis.com causes managedCloud Service Mesh control plane to stop working. If the fleet does not usemanaged Cloud Service Mesh on any cluster, then these APIs can be disabled.

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

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

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

Set up your cluster

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

  1. Register the cluster to the fleet.

  2. Initialize your project to ready it for installation. Among other things,this command creates a service account to let data plane components, suchas the sidecar proxy, securely access your project's data and resources.In the following command replaceFLEET_PROJECT_ID withthefleet host project:

    Warning: If yourFLEET_PROJECT_ID is the same as yourPROJECT_ID, thenremove the"FLEET_PROJECT_ID.hub.id.goog", from the following command.Otherwise, you will receive an error code due toINVALID_ARGUMENT.
    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:{}

  3. For GKE on Google Cloud clusters,set the default zone or region for the Google Cloud CLI. Ifyou don't set the default here, be sure to specify either the--zone or--region option in thegcloud container clusters commands on this page.

  4. For GKE on Google Cloud clusters, enableWorkload Identity:

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

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

  5. For GKE on Google Cloud clusters, enableCloud Monitoring and Cloud Logging on GKE:

    gcloud container clusters updateCLUSTER_NAME \    --project=PROJECT_ID \    --enable-stackdriver-kubernetes

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

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.