Register a cluster on Google Cloud to your fleet

This page shows you how to add a GKE cluster on Google Cloud to your fleet. Depending on your project and use case, you can use the Google Cloud console, Terraform, Config Connector, or the Google Cloud CLI for registration. You can also create and register a new cluster in a single step using the Google Cloud CLI, the Google Cloud console, or Terraform.

Before you begin

Ensure that you have followed the general prerequisites for registering a cluster. We also recommend reviewing the general restrictions on cluster registration in Plan fleet resources.

Depending on your use case, GKE cluster on Google Cloud registrations may also require the following:

Register your GKE cluster on Google Cloud

As you saw in the prerequisites, we recommend registering your GKE clusters with fleet Workload Identity Federation for GKE enabled, which provides a consistent way for applications to authenticate to Google Cloud APIs and services. You can find out more about the advantages of enabling fleet Workload Identity Federation for GKE in Use fleet Workload Identity Federation for GKE. Registering clusters using any of the following options lets you enable fleet Workload Identity Federation for GKE if required.

You can choose between registering a new cluster during cluster creation, or registering an existing cluster.

Register a new cluster

If you have enabled GKE Enterprise, we strongly recommend registering new enterprise-tier clusters to a fleet during cluster creation. This is because these "born in the fleet" GKE Enterprise clusters are created with your chosen fleet-level default settings for a number of enterprise features, and with recommended logs and metrics already enabled. You can learn more about these in the following guides:

You can also register standard tier clusters during cluster creation using these instructions, but the clusters won't get any fleet-level default configuration.

Console

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

  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.

Register an existing cluster

Use any of the following options to register existing clusters, either to their own project's fleet or to a fleet in a different project (all options except the Google Cloud console). You can also choose to register some or all of your existing clusters while upgrading to GKE Enterprise.

To register an existing GKE cluster:

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:

  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.

Troubleshooting

If you run into any problems during this setup, see our troubleshooting guide.

What's next?