Register a cluster on Google Cloud to your fleet

Console

1. In the Google Cloud console, go to the relevant cluster creation page.

   • To create an Autopilot cluster, go to the Create an Autopilot cluster page.

     Create an Autopilot cluster

   • To create a Standard regional or Standard zonal cluster, go to the Create a Kubernetes cluster page.

     Create a Kubernetes cluster

2. Follow the instructions in the GKE documentation to complete the sections for creating an Autopilot, Standard regional, or Standard zonal cluster from the Google Cloud console.

3. In the Fleet registration section, select the Register to a fleet checkbox. By default, the fleet name is based on your project ID.

4. Fill out the remaining sections.

5. If you have chosen to create a Standard cluster and want the registered cluster to use fleet Workload Identity Federation (recommended), click Security in the navigation pane and ensure that Enable Workload Identity Federation for GKE is selected. Autopilot clusters have this feature enabled by default.

6. When you have finished reviewing cluster details, click Create to create and register the cluster to a fleet.

gcloud

These commands require the gcloud CLI version 450.0.0 or higher.

Registering a cluster by using the Google Cloud CLI gives your cluster a regional membership location by default.

• To create and register a new GKE Autopilot cluster, run the following command:

  gcloud container clusters create-auto CLUSTER_NAME --enable-fleet
  

  Replace CLUSTER_NAME with a unique name for the cluster you are creating. This will also become the cluster's membership name. If there is already a cluster with this name in your chosen fleet, the command will return an error.

• To create and register a new GKE Standard cluster with Workload Identity Federation for GKE enabled, run the following command:

  gcloud container clusters create CLUSTER_NAME --enable-fleet \
  --workload-pool=PROJECT_ID.svc.id.goog
  

  Replace the following:

  • CLUSTER_NAME: a unique name for the cluster you are creating. This will also become the cluster's membership name. If there is already a cluster with this name in your chosen fleet, the command will return an error.
  • PROJECT_ID: the Google Cloud project ID for the project that will own your new cluster.

  If you are creating a Standard cluster, we recommend creating the cluster with Workload Identity Federation for GKE enabled, as this enables fleet Workload Identity Federation for your registered cluster. However, you can omit the --workload-pool flag if you don't want to use this feature. Autopilot clusters have Workload Identity Federation for GKE enabled by default.

Depending on the cluster you want to create, you can also specify any of the other options for creating a Standard zonal, Standard regional, or Autopilot cluster. You may also need to specify a Compute Engine zone if you haven't configured a default zone for the Google Cloud CLI, and a Google Cloud project to own the cluster if you have not configured a default project.

Learn more about creating different types of GKE cluster in the GKE documentation.

Terraform

You can create and register GKE clusters with Terraform using the google provider. You can find a complete reference for the google_container_cluster resource used to manage a GKE cluster in the Terraform registry.

Ensure that you have created a service account for Terraform to use as described in the prerequisites before following these instructions.

To create and register a new cluster, add the following blocks in your Terraform configuration.

1. Specify the google provider as a required provider:

   terraform {
     required_providers {
       google = {
         source = "hashicorp/google"
         version = "VERSION"
       }
     }
   }
   

   Replace VERSION with 5.6.0 or later.

2. Create and register a new cluster:

   resource "google_container_cluster" "TF_CLUSTER_RESOURCE_NAME" {
     provider = google
     name               = "CLUSTER_NAME"
     location           = "ZONE"
     initial_node_count = 1
     fleet {
       project = "FLEET_HOST_PROJECT"
     }
   }
   

   Replace the following:

   • TF_CLUSTER_RESOURCE_NAME: a unique name for the new google_container_cluster resource that you are creating.
   • CLUSTER_NAME: a unique name for the new GKE cluster that you want to create and register.
   • ZONE: the zone for your GKE cluster resource. For example: us-central1-a.
   • FLEET_HOST_PROJECT: the Google Cloud project ID in which you are creating and registering the cluster. If this is not set, the cluster won't be registered to a fleet. Specify a different project ID if you want to register the cluster to a fleet in a different project.

Console

If you want your cluster to use fleet Workload Identity Federation (recommended), ensure that Workload Identity Federation for GKE is enabled on the cluster before following these instructions. Autopilot clusters have Workload Identity Federation for GKE enabled by default. Clusters with Workload Identity Federation for GKE automatically have fleet Workload Identity Federation enabled when you register them from the Google Cloud console.

1. In the Google Cloud console, go to the GKE Clusters page.

   Go to the GKE Clusters page

2. Click Register next to the unregistered cluster that you want to add to your fleet.

3. Click Register again on the confirmation dialog that appears.

gcloud

These commands require the gcloud CLI version 450.0.0 or higher.

Registering a cluster by using the Google Cloud CLI gives your cluster a regional membership location by default.

Both of these commands enable fleet Workload Identity Federation for the cluster if the cluster already has Workload Identity Federation for GKE enabled.

• To register an existing GKE cluster on Google Cloud to its project's fleet, run the following command:

  gcloud container clusters update CLUSTER_NAME --enable-fleet
  

  Replace CLUSTER_NAME with the name of the cluster you are registering. This will also become the cluster's membership name.

• To register the cluster to a fleet in a different project, use the --fleet-project flag, as shown below. Ensure you have set up the necessary permissions for cross-project registration before running this command.

  gcloud container clusters update CLUSTER_NAME --fleet-project=PROJECT_ID_OR_NUMBER
  

  • Replace CLUSTER_NAME with the name of the cluster you are registering. This will also become the cluster's membership name.
  • Replace PROJECT_ID_OR_NUMBER with the project ID or number of your chosen fleet host project.

Terraform

You can register GKE clusters with Terraform using the google provider. You can find a complete reference for the google_container_cluster resource used to manage a GKE cluster in the Terraform registry.

Ensure that you have created a service account for Terraform to use as described in the prerequisites before following these instructions.

Register an existing cluster

To register an existing cluster, add the following block to the google_container_cluster resource configuration of your cluster:

fleet {
        project = "FLEET_HOST_PROJECT"
      }

Replace FLEET_HOST_PROJECT with the Google Cloud project ID to which your cluster belongs, or a different project ID if you want to register the cluster to a fleet in a different project.

Enable Workload Identity Federation for GKE on a registered cluster

You can use Terraform to enable Workload Identity Federation for GKE for a cluster.

To enable Workload Identity Federation for GKE for your new or existing cluster, add the following block in the relevant cluster's google_container_cluster resource configuration:

  workload_identity_config {
    workload_pool = "PROJECT_ID.svc.id.goog"
  }
  ```

 Replace <code><var>PROJECT_ID</var></code> with the Google Cloud project ID for your Terraform resources.

Config Connector

If you have the Config Connector add-on installed, you can use Config Connector to register GKE clusters. Ensure that you have a version of Config Connector above 1.47.0 and that you've created a service account as described in the prerequisites.

You can find a complete reference for the GKEHubMembership resource in the Config Connector reference documentation.

Register a GKE cluster

To register the cluster, first specify where you want to create your resources, following the instructions in the Config Connector guide. Then create a YAML file to register and (optionally) create a cluster, as follows:

Create and register a GKE cluster

1. Create a GKE cluster, as in the following simple example:

   apiVersion: container.cnrm.cloud.google.com/v1beta1
   kind: ContainerCluster
   metadata:
     name: CLUSTER_NAME
   spec:
     location: LOCATION
     initialNodeCount: 1
   

   Replace the following:

   • CLUSTER_NAME: the name that you chose to uniquely represent the cluster you created with Config Connector.
   • LOCATION: the zone or region that you chose to provision your GKE cluster resource. For example: us-central1-a.

   For a complete list of options when creating a GKE cluster with Config Connector, see the Config Connector documentation.

2. Register a membership for the GKE cluster.

   apiVersion: gkehub.cnrm.cloud.google.com/v1beta1
   kind: GKEHubMembership
   metadata:
     name: MEMBERSHIP_NAME
   spec:
     location: MEMBERSHIP_LOCATION
     endpoint:
       gkeCluster:
         resourceRef:
           name: CLUSTER_NAME
   

   Replace the following:

   • MEMBERSHIP_NAME: the membership name that you chose to uniquely represent the cluster being registered to the fleet.
   • MEMBERSHIP_LOCATION: the location of the Fleet service you want to manage your cluster's membership. This can be the cluster's own location (recommended) or global. Learn more in Fleet membership location. You cannot specify a location that's different from the cluster's location: if you do this, registration fails.
   • CLUSTER_NAME: the name that you chose to uniquely represent the cluster you created with Config Connector.

Register the cluster in a different project

Add the following to the metadata field of the GKEHubMembership resource to register a cluster to a fleet in another project.

   metadata:
     annotations:
       cnrm.cloud.google.com/project-id: FLEET_PROJECT_ID

Replace the following:

• FLEET_PROJECT_ID: the fleet host project you chose to register the GKE cluster.

Register an existing cluster

Use the following configuration if you want to register any existing cluster, regardless of how it was created. In this case you need to specify the full resource name of the cluster so that Config Connector can find it. Replace the resourceRef field of the GKEHubMembership resource with:

   resourceRef:
     external: //container.googleapis.com/CLUSTER_RESOURCE_NAME

Replace the following:

• CLUSTER_RESOURCE_NAME: the Google Cloud resource name for the GKE cluster. For example: projects/my-project/zones/us-west1-a/clusters/my-cluster.

If the cluster was created with Config Connector you don't need to specify the fully qualified cluster name.

Enable Workload Identity Federation for GKE on a registered cluster

Enabling Workload Identity Federation for GKE uses the same configuration as registering a cluster, with the following additional steps.

1. Enable Workload Identity Federation for GKE by adding the following in the spec field of ContainerCluster resource. You need to do this for both new and existing clusters.

   spec:
     workloadIdentityConfig:
       workloadPool: PROJECT_ID.svc.id.goog
   

   Replace the following:

   • PROJECT_ID: the default project you chose through namespace annotation to create your GKE cluster resource.

2. Enable fleet Workload Identity Federation by adding the following in the spec field of GKEHubMembership resource block.

   spec:
     authority:
       issuer: https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME
   }
   

   Replace the following:

   • PROJECT_ID: the default project you chose through namespace annotation to create your GKE cluster resource.
   • LOCATION: the zone or region that you chose to provision your GKE cluster resource. For example: us-central1-a.
   • CLUSTER_NAME: the name that you chose to uniquely represent the cluster you created.