This page describes commonMulti-cluster Services (MCS)scenarios. The scenarios presented on this page share the followingcharacteristics:

• Two GKE clusters: The first GKE cluster isregistered to its own project'sfleet. This is thefleet host project. The second GKEcluster is registered to the same fleet, though depending on the scenario may not be in the same project. Both GKEclusters areVPC-native clusters.
• Same VPC network: Both GKE clusters usesubnets in the same Shared VPC network.
• Workload Identity Federation for GKE is enabled in both clusters.

Terminology

The termsShared VPC host project andGKE fleethost project have different meanings.

• The Shared VPC host project is the project which contains theShared VPC network.
• The GKE fleet host project is the project that contains thefleet to which you register the clusters.

Scenarios

The following table describes common MCS scenarios:

Prerequisites

Before setting up a cross-project configuration of MCS, ensure that you're familiar with:

• Shared VPC concepts
• Setting up clusters with Shared VPC
• MCS limitations
• MCS known issues

Clusters in the same Shared VPC service project

This section provides an example MCS configuration involving two existingGKE clusters both in the same Shared VPC service project:

• Both clusters use the same Shared VPC network in theSHARED_VPC_HOST_PROJ.
• The first VPC-native GKE clusterFIRST_CLUSTER_NAME, with Workload Identity Federation for GKEenabled, is created in theFLEET_HOST_PROJ. The fleethost project is a service project connected to theSHARED_VPC_HOST_PROJ in this scenario.
• The second VPC-native GKE clusterSECOND_CLUSTER_NAME, with Workload Identity Federation for GKEenabled, is also created in theFLEET_HOST_PROJ.

Enable required APIs

Enable the required APIs. The output of the Google Cloud CLI shows you if anAPI has already been enabled.

1. Enable the Cloud DNS API:

   gcloudservicesenabledns.googleapis.com\--projectSHARED_VPC_HOST_PROJ

   In this scenario, the fleet host project is a service project connected tothe Shared VPC host project. The Cloud DNS API must be enabled inthe Shared VPC host project because that's where theShared VPC network is located. GKE createsCloud DNS managed private zones in the host project and authorizes themfor the Shared VPC network.

2. Enable GKE Hub (fleet) API. The GKE Hub API must beenabled in only the fleet host project.

   gcloudservicesenablegkehub.googleapis.com\--projectFLEET_HOST_PROJ

   Enabling this API in the fleet host project creates orensures that the following service account exists:service-FLEET_HOST_PROJ_NUMBER@gcp-sa-gkehub.iam.gserviceaccount.com.

3. Enable Cloud Service Mesh, Resource Manager, and Multi-cluster ServiceDiscovery APIs in the fleet host project:

   gcloudservicesenabletrafficdirector.googleapis.com\cloudresourcemanager.googleapis.com\multiclusterservicediscovery.googleapis.com\--projectFLEET_HOST_PROJ

Enable Multi-cluster services in the fleet host project

1. Enable multi-cluster services in the fleet host project:

   gcloudcontainerfleetmulti-cluster-servicesenable\--projectFLEET_HOST_PROJ

   Enabling multi-cluster services in the fleet host project creates or ensuresthat the following service account exists:service-FLEET_HOST_PROJ_NUMBER@gcp-sa-mcsd.iam.gserviceaccount.com.

Create IAM bindings

1. Create IAM binding granting the fleet host project MCSservice account the MCS Service Agent role on the Shared VPC hostproject:

   gcloudprojectsadd-iam-policy-bindingSHARED_VPC_HOST_PROJ\--member"serviceAccount:service-FLEET_HOST_PROJ_NUMBER@gcp-sa-mcsd.iam.gserviceaccount.com"\--roleroles/multiclusterservicediscovery.serviceAgent

2. Create IAM binding granting the fleet host project MCSservice account the Network User role for its own project:

   gcloudprojectsadd-iam-policy-bindingFLEET_HOST_PROJ\--member"serviceAccount:FLEET_HOST_PROJ.svc.id.goog[gke-mcs/gke-mcs-importer]"\--roleroles/compute.networkViewer

   Because this scenario uses Workload Identity Federation for GKE, the fleet host project'sMCS Importer GKE service account needs the Network User rolefor its own project.

   Replace the following:

   • SHARED_VPC_HOST_PROJ: the project ID of theShared VPC host project
   • FLEET_HOST_PROJ_NUMBER: the project number of thefleet host project, which is the Shared VPC service project forthis scenario
   • FLEET_HOST_PROJ: the project ID of the firstcluster's project.

Register the clusters to the fleet

1. Register the first cluster to the fleet. The--gke-clusterflag can be used for this command because the first cluster is located in thesame project as the fleet to which it is beingregistered.

   gcloudcontainerfleetmembershipsregisterMEMBERSHIP_NAME_1\--projectFLEET_HOST_PROJ\--enable-workload-identity\--gke-cluster=LOCATION/FIRST_CLUSTER_NAME

   Replace the following:

   • MEMBERSHIP_NAME_1: a unique identifier for this cluster in this fleet. For example, you can use the name of the first GKEcluster.
   • FLEET_HOST_PROJ: the project ID for the fleet hostproject, identical to the Shared VPC host project in this scenario.
   • LOCATION: for zonal clusters, the Compute Enginezone containing the cluster; for regional clusters, the Compute Engineregion containing the cluster.
   • FIRST_CLUSTER_NAME: the name of the first cluster.

2. Register the second cluster to the fleet host project. The--gke-clusterflag can be used for this command because the second cluster is also located inthe fleet host project.

   gcloudcontainerfleetmembershipsregisterMEMBERSHIP_NAME_2\--projectFLEET_HOST_PROJ\--enable-workload-identity\--gke-cluster=LOCATION/SECOND_CLUSTER_NAME

   Replace the following:

   • MEMBERSHIP_NAME_2: a unique identifier for this cluster in this fleet. For example, you can use the name of the second GKEcluster.
   • FLEET_HOST_PROJ: the project ID for the fleet hostproject, identical to the Shared VPC host project in this scenario.
   • LOCATION: for zonal clusters, the Compute Enginezone containing the cluster; for regional clusters, the Compute Engineregion containing the cluster.
   • SECOND_CLUSTER_NAME: the name of the second cluster.

Create a common namespace for the clusters

1. Ensure that each cluster has a namespace to share Services in. If needed,create a namespace by using the following command in each cluster:

   kubectlcreatensNAMESPACE

   ReplaceNAMESPACE with a name for the namespace.

Shared VPC host project as fleet host project

This section provides an example MCS configuration involving two existingGKE clusters:

• The first VPC-native GKE clusterFIRST_CLUSTER_NAME, with Workload Identity Federation for GKE enabled,has been created in theFLEET_HOST_PROJ. The fleethost project is also the Shared VPC host project in this scenario.
• The second VPC-native GKE clusterSECOND_CLUSTER_NAME, with Workload Identity Federation for GKEenabled, has been created in theSECOND_CLUSTER_PROJ.

Enable required APIs

Enable the required APIs. The output of the Google Cloud CLI shows you if anAPI has already been enabled.

1. Enable the Cloud DNS API:

   gcloudservicesenabledns.googleapis.com\--projectFLEET_HOST_PROJ

   In this scenario, the fleet host project is also the Shared VPC hostproject. The Cloud DNS API must be enabled in the Shared VPC hostproject because that's where the Shared VPC network is located.GKE creates Cloud DNS managed private zones in thehost project and authorizes them for the Shared VPC network.

2. Enable GKE Hub (fleet) API. The GKE Hub API must beenabled in only the fleet host project.

   gcloudservicesenablegkehub.googleapis.com\--projectFLEET_HOST_PROJ

   Enabling the GKE Hub API in the fleet host project creates orensures that the following service account exists:service-FLEET_HOST_PROJ_NUMBER@gcp-sa-gkehub.iam.gserviceaccount.com.

3. Enable Cloud Service Mesh, Resource Manager, and Multi-cluster ServiceDiscovery APIs, in both the fleet host project and in the second cluster'sproject:

   gcloudservicesenabletrafficdirector.googleapis.com\cloudresourcemanager.googleapis.com\multiclusterservicediscovery.googleapis.com\--projectFLEET_HOST_PROJ

   gcloudservicesenabletrafficdirector.googleapis.com\cloudresourcemanager.googleapis.com\multiclusterservicediscovery.googleapis.com\--projectSECOND_CLUSTER_PROJ

Enable Multi-cluster services in the fleet host project

1. Enable multi-cluster services in the fleet host project:

   gcloudcontainerfleetmulti-cluster-servicesenable\--projectFLEET_HOST_PROJ

   Enabling multi-cluster services in the fleet host project creates or ensuresthat the following service account exists:service-FLEET_HOST_PROJ_NUMBER@gcp-sa-mcsd.iam.gserviceaccount.com.

Create IAM bindings

1. Create IAM binding granting the fleet host project'sGKE fleet service account the GKE Service Agentrole on the second cluster's project:

   gcloudprojectsadd-iam-policy-bindingSECOND_CLUSTER_PROJ\--member"serviceAccount:service-FLEET_HOST_PROJ_NUMBER@gcp-sa-gkehub.iam.gserviceaccount.com"\--roleroles/gkehub.serviceAgent

2. Create IAM binding granting the fleet host project's MCSservice account the MCS Service Agent role on the second cluster's project:

   gcloudprojectsadd-iam-policy-bindingSECOND_CLUSTER_PROJ\--member"serviceAccount:service-FLEET_HOST_PROJ_NUMBER@gcp-sa-mcsd.iam.gserviceaccount.com"\--roleroles/multiclusterservicediscovery.serviceAgent

3. Create IAM binding granting each project's MCS service accountthe Network User role for its own project:

   gcloudprojectsadd-iam-policy-bindingFLEET_HOST_PROJ\--member"serviceAccount:FLEET_HOST_PROJ.svc.id.goog[gke-mcs/gke-mcs-importer]"\--roleroles/compute.networkViewer

   gcloudprojectsadd-iam-policy-bindingSECOND_CLUSTER_PROJ\--member"serviceAccount:SECOND_CLUSTER_PROJ.svc.id.goog[gke-mcs/gke-mcs-importer]"\--roleroles/compute.networkViewer

   Because this scenario uses Workload Identity Federation for GKE, each project's MCS ImporterGKE service account needs the Network User role for its ownproject.

   Replace the following:

   • SECOND_CLUSTER_PROJ: the project ID of the secondcluster's project
   • FLEET_HOST_PROJ: the project ID of the firstcluster's project.
   • FLEET_HOST_PROJ_NUMBER: the project number of thefleet host project, which is the same as the Shared VPC hostproject for this scenario

Register the clusters to the fleet

1. Register the first cluster to the fleet. The--gke-cluster flagcan be used for this command because the first cluster is located in the sameproject as the fleet to which it is beingregistered.

   gcloudcontainerfleetmembershipsregisterMEMBERSHIP_NAME_1\--projectFLEET_HOST_PROJ\--enable-workload-identity\--gke-cluster=LOCATION/FIRST_CLUSTER_NAME

   Replace the following:

   • MEMBERSHIP_NAME_1: a unique identifier for this cluster in this fleet. For example, you can use the name of the first GKEcluster.
   • FLEET_HOST_PROJ: the project ID for thefleet host project, identical to the Shared VPC host project in thisscenario.
   • LOCATION: for zonal clusters, the Compute Engine zonecontaining the cluster; for regional clusters, the Compute Engine regioncontaining the cluster.
   • FIRST_CLUSTER_NAME: the name of the firstcluster.

2. Register the second cluster to the fleet. The--gke-uri flagmust be used for this command because the second cluster is not located in thesame project as the fleet. Youcan obtain the full cluster URI by runninggcloud container clusters list --uri.

   gcloudcontainerfleetmembershipsregisterMEMBERSHIP_NAME_2\--projectFLEET_HOST_PROJ\--enable-workload-identity\--gke-urihttps://container.googleapis.com/v1/projects/SECOND_CLUSTER_PROJ/locations/LOCATION/clusters/SECOND_CLUSTER_NAME

   Replace the following:

   • MEMBERSHIP_NAME_2: a unique identifier for this cluster in this fleet. For example, you can use the name of the second GKEcluster.
   • FLEET_HOST_PROJ: the project ID for thefleet host project, identical to the Shared VPC host project inthis scenario.
   • LOCATION: replaceLOCATION with:
     • the cluster's Compute Engine zone if the cluster is a zonal cluster
     • the cluster's Compute Engine region if the cluster is a regional cluster
   • SECOND_CLUSTER_PROJECT: the project containing thesecond cluster.
   • SECOND_CLUSTER_NAME: the name of the second cluster.

Create a common namespace for the clusters

1. Ensure that each cluster has a namespace to share Services in. If needed,create a namespace by using the following command in each cluster:

   kubectlcreatensNAMESPACE

   ReplaceNAMESPACE with a name for the namespace.

Clusters in different Shared VPC service projects

This section provides an example MCS configuration involving two existingGKE clusters each in a different Shared VPC service project.

• Both clusters use the same Shared VPC network in theSHARED_VPC_HOST_PROJ.
• The first VPC-native GKE clusterFIRST_CLUSTER_NAME, with Workload Identity Federation for GKE enabled,has been created in theFLEET_HOST_PROJ. The fleet hostproject is a service project connected to theSHARED_VPC_HOST_PROJ in this scenario.
• The second VPC-native GKE clusterSECOND_CLUSTER_NAME, with Workload Identity Federation for GKE enabled,has been created in theSECOND_CLUSTER_PROJ.TheSECOND_CLUSTER_PROJ is also a service projectconnected to theSHARED_VPC_HOST_PROJ in this scenario.

Enable required APIs

Enable the required APIs. The output of the Google Cloud CLI shows you if anAPI has already been enabled.

1. Enable the Cloud DNS API:

   gcloudservicesenabledns.googleapis.com\--projectSHARED_VPC_HOST_PROJ

   In this scenario, the fleet host project is a service project connected tothe Shared VPC host project. The Cloud DNS API must be enabled inthe Shared VPC host project because that's where theShared VPC network is located. GKE createsCloud DNS managed private zones in the host project and authorizes themfor the Shared VPC network.

2. GKE Hub (fleet) API. The GKE Hub API must be enabled inonly the fleet host projectFLEET_HOST_PROJ.

   gcloudservicesenablegkehub.googleapis.com\--projectFLEET_HOST_PROJ

   Enabling this API in the fleet host project creates orensures that the following service account exists:service-FLEET_HOST_PROJ_NUMBER@gcp-sa-gkehub.iam.gserviceaccount.com.

3. Enable Cloud Service Mesh, Resource Manager, and Multi-cluster ServiceDiscovery APIs, in both the fleet host project and in the second cluster'sproject:

   gcloudservicesenabletrafficdirector.googleapis.com\cloudresourcemanager.googleapis.com\multiclusterservicediscovery.googleapis.com\--project=FLEET_HOST_PROJ

   gcloudservicesenabletrafficdirector.googleapis.com\cloudresourcemanager.googleapis.com\multiclusterservicediscovery.googleapis.com\--projectSECOND_CLUSTER_PROJ

Enable Multi-cluster services in the fleet host project

1. Enable multi-cluster services in the fleet host project:

   gcloudcontainerfleetmulti-cluster-servicesenable\--projectFLEET_HOST_PROJ

   Enabling multi-cluster services in the fleet host project creates or ensuresthat the following service account exists:service-FLEET_HOST_PROJ_NUMBER@gcp-sa-mcsd.iam.gserviceaccount.com.

Create IAM bindings

1. Create IAM binding granting the fleet host project'sGKE Hub service account the GKE Service Agentrole on the second cluster's project:

   gcloudprojectsadd-iam-policy-bindingSECOND_CLUSTER_PROJ\--member"serviceAccount:service-FLEET_HOST_PROJ_NUMBER@gcp-sa-gkehub.iam.gserviceaccount.com"\--roleroles/gkehub.serviceAgent

2. Create IAM binding granting the fleet host project's MCSservice account the MCS Service Agent role on the second cluster's project:

   gcloudprojectsadd-iam-policy-bindingSECOND_CLUSTER_PROJ\--member"serviceAccount:service-FLEET_HOST_PROJ_NUMBER@gcp-sa-mcsd.iam.gserviceaccount.com"\--roleroles/multiclusterservicediscovery.serviceAgent

3. Create IAM binding granting the fleet host project MCSservice account the MCS Service Agent role on the Shared VPC hostproject:

   gcloudprojectsadd-iam-policy-bindingSHARED_VPC_HOST_PROJ\--member"serviceAccount:service-FLEET_HOST_PROJ_NUMBER@gcp-sa-mcsd.iam.gserviceaccount.com"\--roleroles/multiclusterservicediscovery.serviceAgent

4. Create IAM binding granting each project's MCS service accountthe Network User role for its own project:

   gcloudprojectsadd-iam-policy-bindingFLEET_HOST_PROJ\--member"serviceAccount:FLEET_HOST_PROJ.svc.id.goog[gke-mcs/gke-mcs-importer]"\--roleroles/compute.networkViewer

   gcloudprojectsadd-iam-policy-bindingSECOND_CLUSTER_PROJ\--member"serviceAccount:SECOND_CLUSTER_PROJ.svc.id.goog[gke-mcs/gke-mcs-importer]"\--roleroles/compute.networkViewer

   Because this scenario uses Workload Identity Federation for GKE, each project's MCS ImporterGKE service account needs the Network User role for its ownproject.

   Replace the following as needed in the previous commands:

   • SECOND_CLUSTER_PROJ: the project ID of the secondcluster's project.
   • SHARED_VPC_HOST_PROJ: the project ID of theShared VPC host project. In this example, both clusters use thesame Shared VPC network, but neither cluster is located in theShared VPC host project.
   • FLEET_HOST_PROJ: the project ID of the firstcluster's project.
   • FLEET_HOST_PROJ_NUMBER: the project number of thefleet host project.

Register the clusters to the fleet

1. Register the first cluster to the fleet. The--gke-cluster flagcan be used for this command because the first cluster is located in the sameproject as the fleet to which it is beingregistered.

   gcloudcontainerfleetmembershipsregisterMEMBERSHIP_NAME_1\--projectFLEET_HOST_PROJ\--enable-workload-identity\--gke-cluster=LOCATION/FIRST_CLUSTER_NAME

   Replace the following:

   • MEMBERSHIP_NAME_1: a unique identifier for this cluster in this fleet. For example, you can use the name of the first GKEcluster.
   • FLEET_HOST_PROJ: the project ID for the fleet hostproject, identical to the Shared VPC host project in this scenario.
   • LOCATION: for zonal clusters, the Compute Enginezone containing the cluster; for regional clusters, the Compute Engineregion containing the cluster.
   • FIRST_CLUSTER_NAME: the name of the first cluster.

2. Register the second cluster to the fleet. The--gke-uri flagmust be used for this command because the second cluster is not located inthe same project as the fleet.You can obtain the full cluster URI by runninggcloud container clusters list --uri.

   gcloudcontainerfleetmembershipsregisterMEMBERSHIP_NAME_2\--projectFLEET_HOST_PROJ\--enable-workload-identity\--gke-urihttps://container.googleapis.com/v1/projects/SECOND_CLUSTER_PROJ/locations/LOCATION/clusters/SECOND_CLUSTER_NAME

   Replace the following:

   • MEMBERSHIP_NAME_2: a unique identifier for this cluster in this fleet. For example, you can use the name of the second GKEcluster.
   • FLEET_HOST_PROJ: the project ID for the fleet hostproject, identical to the Shared VPC host project in this scenario.
   • LOCATION: replaceLOCATION with:
     • the cluster's Compute Engine zone if the cluster is a zonal cluster
     • the cluster's Compute Engine region if the cluster is a regional cluster
   • SECOND_CLUSTER_PROJECT: the project containing thesecond cluster.
   • SECOND_CLUSTER_NAME: the name of the second cluster.

Create a common namespace for the clusters

1. Ensure that each cluster has a namespace to share Services in. If needed,create a namespace by using the following command in each cluster:

   kubectlcreatensNAMESPACE

   ReplaceNAMESPACE with a name for the namespace.

What's next

• Learn how touse MCS.