Setting up multi-cluster Services with Shared VPC

This page shows you how to set up a cross-project configuration of Multi-cluster Services (MCS) for GKE clusters that belong to a VPC network service project and are not currently registered to a fleet.

Prerequisites

Before setting up a cross-project configuration of MCS, complete the following steps:

  • Ensure you have multiple VPC-native GKE clusters already deployed in the service project(s) of a VPC network host project. For more information, see Setting up clusters with Shared VPC.
  • Complete the Prerequisites for registering a cluster in your hub project.
  • Enable MCS in the project where you intend to register GKE clusters to a fleet (hub project).
  • Ensure that each cluster has a namespace to share Services in. You cannot export Services in the default and kube-system namespaces across clusters.

Shared VPC setup with two projects and two clusters

This section provides an example configuration of a Shared VPC setup with two projects and two clusters, where:

  • The hub project is the Shared VPC host project.
  • The registered member project is a Shared VPC service project.

Configuring your projects

  1. In the registered member project, create a GKE fleet service account by completing the steps in Registering a GKE cluster into a different project.

  2. In your registered member project, enable the Cloud DNS, Traffic Director, Resource Manager, and MCS APIs:

    gcloud services enable dns.googleapis.com \
      trafficdirector.googleapis.com \
      cloudresourcemanager.googleapis.com \
      multiclusterservicediscovery.googleapis.com \
      --project GKE_PROJECT_ID
    

    Replace GKE_PROJECT_ID with the project ID of the registered member project.

Registering your clusters

To register your clusters, complete the following steps:

  1. Create IAM binding allowing the hub project's GKE service account access to the registered member project:

    gcloud projects add-iam-policy-binding "GKE_PROJECT_ID" \
        --member "serviceAccount:service-HUB_PROJECT_NUMBER@gcp-sa-gkehub.iam.gserviceaccount.com" \
        --role roles/gkehub.serviceAgent
    

    Replace the following:

    • GKE_PROJECT_ID: the project ID of the registered member project.
    • HUB_PROJECT_NUMBER: the project number of the hub project.
  2. Create IAM binding allowing the hub project's MCS service account access to the registered member project:

    gcloud projects add-iam-policy-binding "GKE_PROJECT_ID" \
        --member "serviceAccount:service-HUB_PROJECT_NUMBER@gcp-sa-mcsd.iam.gserviceaccount.com" \
        --role roles/multiclusterservicediscovery.serviceAgent
    

    Replace the following:

    • GKE_PROJECT_ID: the project ID of the registered member project.
    • HUB_PROJECT_NUMBER: the project number of the hub project.
  3. Register the registered member project GKE cluster to the hub project:

    gcloud container hub memberships register MEMBERSHIP_NAME \
        --gke-uri https://container.googleapis.com/v1/projects/GKE_PROJECT_ID/zones/ZONE/clusters/CLUSTER_NAME \
        --enable-workload-identity \
        --project HUB_PROJECT_ID
    

    Replace the following:

    • MEMBERSHIP_NAME: this value represents the relationship between the registered member cluster and the registered hub project. It must be unique. You can use the name of your GKE cluster in your registered member project.
    • GKE_PROJECT_ID: the project ID of the registered member project.
    • ZONE: the zone of the cluster inside of the registered member project.
    • CLUSTER_NAME: the name of the registered member project GKE cluster.
    • HUB_PROJECT_ID: the project ID of the hub project.
  4. Grant the required IAM permissions for MCS importer in the following projects:

    Hub project:

    gcloud projects add-iam-policy-binding HUB_PROJECT_ID \
        --member "serviceAccount:HUB_PROJECT_ID.svc.id.goog[gke-mcs/gke-mcs-importer]" \
        --role "roles/compute.networkViewer"
    

    Registered member project:

    gcloud projects add-iam-policy-binding GKE_PROJECT_ID \
        --member "serviceAccount:GKE_PROJECT_ID.svc.id.goog[gke-mcs/gke-mcs-importer]" \
        --role "roles/compute.networkViewer"
    

    Replace the following:

    • HUB_PROJECT_ID: the project ID of the hub project.
    • GKE_PROJECT_ID: the project ID of the registered member project.

Shared VPC setup with three projects and two clusters

This section provides steps for an example configuration of a Shared VPC setup with three projects and two clusters, where:

  • The hub project is a Shared VPC service project.
  • The registered member project is a different Shared VPC service project than the hub project.

Configuring your projects

To configure your projects, complete the following steps:

  1. In your Shared VPC host project, enable the Cloud DNS API:

    gcloud services enable dns.googleapis.com \
        --project HOST_PROJECT_ID
    

    Replace HOST_PROJECT_ID with the project ID of the VPC Network host project.

  2. In the registered member project, create a GKE fleet service account by completing the steps in Registering a GKE cluster into a different project.

  3. In your registered member project, enable the Cloud DNS, Traffic Director, Resource Manager, and MCS APIs:

    gcloud services enable dns.googleapis.com \
      trafficdirector.googleapis.com \
      cloudresourcemanager.googleapis.com \
      multiclusterservicediscovery.googleapis.com \
      --project GKE_PROJECT_ID
    

    Replace GKE_PROJECT_ID with the project ID of the registered member project.

Registering your clusters

To register your clusters, complete the following steps:

  1. Create IAM binding allowing the hub project's GKE Hub service account access to the registered member project:

    gcloud projects add-iam-policy-binding "GKE_PROJECT_ID" \
        --member "serviceAccount:service-HUB_PROJECT_NUMBER@gcp-sa-gkehub.iam.gserviceaccount.com" \
        --role roles/gkehub.serviceAgent
    

    Replace the following:

    • GKE_PROJECT_ID: the project ID of the registered member project.
    • HUB_PROJECT_NUMBER: the project number of the hub project.
  2. Create IAM binding allowing the hub project's MCS service account access to the registered member project:

    gcloud projects add-iam-policy-binding "GKE_PROJECT_ID" \
        --member "serviceAccount:service-HUB_PROJECT_NUMBER@gcp-sa-mcsd.iam.gserviceaccount.com" \
        --role roles/multiclusterservicediscovery.serviceAgent
    

    Replace the following:

    • GKE_PROJECT_ID: the project ID of the registered member project.
    • HUB_PROJECT_NUMBER: the project number of the hub project.
  3. Create IAM binding allowing the hub and registered member project's MCS service account access to the VPC Network host project:

    gcloud projects add-iam-policy-binding "HOST_PROJECT_ID" \
        --member "serviceAccount:service-HUB_PROJECT_NUMBER@gcp-sa-mcsd.iam.gserviceaccount.com" \
        --role roles/multiclusterservicediscovery.serviceAgent
    

    Replace the following:

    • HOST_PROJECT_ID: the project ID of the VPC Network host project.
    • HUB_PROJECT_NUMBER: the project number of the hub project.
  4. Register the registered member project GKE cluster to the hub project:

    gcloud container hub memberships register MEMBERSHIP_NAME \
        --gke-uri https://container.googleapis.com/v1/projects/GKE_PROJECT_ID/zones/ZONE/clusters/CLUSTER_NAME \
        --enable-workload-identity \
        --project HUB_PROJECT_ID
    

    Replace the following:

    • MEMBERSHIP_NAME: represents the relationship between the registered member project GKE cluster and the hub project. It must be unique. You can use the name of your GKE cluster in your registered member project.
    • GKE_PROJECT_ID: the project ID of the registered member project.
    • ZONE: the zone of the registered member project GKE cluster to be registered.
    • CLUSTER_NAME: the name of the registered member project GKE cluster.
    • HUB_PROJECT_ID: the project ID of the hub project.
  5. Grant the required IAM permissions for MCS importer in the following projects:

    Hub project:

    gcloud projects add-iam-policy-binding HUB_PROJECT_ID \
        --member "serviceAccount:HUB_PROJECT_ID.svc.id.goog[gke-mcs/gke-mcs-importer]" \
        --role "roles/compute.networkViewer"
    

    Registered member project:

    gcloud projects add-iam-policy-binding GKE_PROJECT_ID \
        --member "serviceAccount:GKE_PROJECT_ID.svc.id.goog[gke-mcs/gke-mcs-importer]" \
        --role "roles/compute.networkViewer"
    

    Replace the following:

    • HUB_PROJECT_ID: the project ID of the hub project.
    • GKE_PROJECT_ID: the project ID of the registered member project.

What's next