Register a GKE cluster 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.

Before you begin

Ensure that you have followed the general prerequisites for registering a cluster.

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

Register your cluster

As you saw in the prerequisites, we recommend registering your GKE clusters with fleet Workload Identity 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 in Use fleet Workload Identity. All of the following options allow you to enable fleet Workload Identity if required.

  • The simplest and quickest way to register a GKE cluster in a project with the Anthos platform enabled is to register it from the Anthos clusters page in the Google Cloud console. Using this approach immediately lets you view your cluster as part of your fleet in the console, and use fleet-enabled features such as Anthos Config Management.

  • You can create and register a GKE cluster (with or without enabling the entire Anthos platform) by using Terraform or Config Connector.

  • You can register a GKE cluster (with or without enabling the entire Anthos platform) by using the Google Cloud CLI. Registering by using Google Cloud CLI installs the Connect Agent on your cluster, allowing you to use the Connect gateway to standardize authentication across environments with Google IDs.

To register a GKE cluster:

Console

To register a cluster:

  1. (Optional) If you want your registered cluster to use fleet Workload Identity (recommended), ensure that GKE Workload Identity is enabled on the cluster. Clusters with GKE Workload Identity automatically have fleet Workload Identity enabled when you register them from the Google Cloud console.

  2. In the Google Cloud console, go to the Anthos Clusters page. This page shows all your registered clusters.

    Go to the Anthos Clusters page

  3. Click Register existing cluster.

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

Terraform

You can register GKE clusters with Terraform using the google-beta provider. You can find a complete reference for the gke_hub_membership resource used to configure registration 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 a GKE cluster

To register the cluster, use the following blocks in your configuration.

  1. Specify the google-beta provider as a required provider, as in the following snippet. The version should be above 3.62.0.

    terraform {
  required_providers {
    google-beta = {
      source = "hashicorp/google-beta"
      version = "3.67.0"
    }
  }
}

    This provider is required if you want to use gke_hub_membership.

  2. Set the following default values for the provider:

    provider "google-beta" {
  credentials = file("SERVICE_ACCOUNT_KEY_PATH")
  project = "PROJECT_ID"
}

    Replace the following:

    • SERVICE_ACCOUNT_KEY_PATH: the local filepath to the service account's private key JSON file downloaded as part of Prerequisites. This service account key is stored as a secret named creds-gcp in the gke-connect namespace. This service account key enables Terraform to access your Google Cloud account.
    • PROJECT_ID: the default project that you choose to provision your Terraform resources.

  3. Create a GKE cluster (optional)

    If you want to register an existing cluster, skip this step.

    resource "google_container_cluster" "TF_CLUSTER_RESOURCE_NAME" {
  provider = google-beta
  name               = "CLUSTER_NAME"
  location           = "ZONE"
  initial_node_count = 1
}

    Replace the following:

    • TF_CLUSTER_RESOURCE_NAME: the name that you choose to uniquely identify the Terraform google_container_cluster resource created by this block.
    • CLUSTER_NAME: the name that you choose to uniquely represent the cluster you created.
    • ZONE: the default zone that you choose to provision your GKE cluster resource. For example: us-central1-a.

  4. Register a membership for the GKE cluster.

    resource "google_gke_hub_membership" "TF_MEMBERSHIP_RESOURCE_NAME" {
  provider = google-beta
  project_id = "FLEET_PROJECT_ID"
  membership_id = "MEMBERSHIP_NAME"
  endpoint {
    gke_cluster {
     resource_link = "//container.googleapis.com/CLUSTER_RESOURCE_NAME"
    }
  }
}

    Replace the following:

    • TF_MEMBERSHIP_RESOURCE_NAME: the name that you choose to uniquely identify the Terraform google_gke_hub_membership resource created by this block.
    • FLEET_PROJECT_ID: If this is not set, the cluster's membership will be created in the default project you specified earlier (PROJECT_ID). Set this field if you want to register the GKE cluster to a fleet in a different project.
    • MEMBERSHIP_NAME: the membership name that you choose to uniquely represent the cluster in the fleet.
    • 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 is provisioned with Terraform, this is ${google_container_cluster.TF_CLUSTER_RESOURCE_NAME.id}.

Enable Workload Identity on a registered GKE cluster

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

  1. Enable GKE Workload Identity by adding the following in the relevant google_container_cluster resource block. You need to do this for both new and existing clusters.

    workload_identity_config {
  identity_namespace = "PROJECT_ID.svc.id.goog"
}

    Replace the following:

    • PROJECT_ID: the default project that you choose to provision your Terraform resources.

  2. Enable Fleet Workload Identity by adding the following in the relevant google_gke_hub_membership resource block.

    authority {
  issuer = "https://container.googleapis.com/v1/CLUSTER_RESOURCE_NAME"
}

    Replace the following:

    • CLUSTER_RESOURCE_NAME: the Google Cloud resource for the GKE cluster. For example: projects/my-project/zones/us-west1-a/clusters/my-cluster. If the cluster is provisioned with Terraform, this is ${google_container_cluster.TF_CLUSTER_RESOURCE_NAME.id}.

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 have created a service account as described in the prerequisites.

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

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: global
  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.
    • 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 on a registered GKE cluster

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

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

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

    Replace the following:

  2. Enable fleet Workload Identity 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.

gcloud

Registering a cluster with gcloud requires the gcloud CLI version 281.0.0 or higher

Registering the cluster from the command line installs the Connect Agent on the cluster. Depending on the registration option you choose, the agent can either use fleet Workload Identity or a Google Cloud service account for authentication to Google Cloud.

Register a GKE cluster with fleet Workload Identity (recommended)

  1. Ensure that the cluster has GKE Workload Identity enabled, following the instructions in our prerequisites.

  2. Run either of the following commands to register the cluster:

    gcloud container fleet memberships register MEMBERSHIP_NAME \
 --gke-uri=GKE_URI \
 --enable-workload-identity

    or

    gcloud container fleet memberships register MEMBERSHIP_NAME \
 --gke-cluster=GKE_CLUSTER \
 --enable-workload-identity

    Replace the following:

    • MEMBERSHIP_NAME: the membership name that you choose to uniquely represent the cluster being registered to the fleet.
    • GKE_URI: the URI of the GKE cluster, for example: https://container.googleapis.com/v1/projects/my-gke-project/locations/us-central1-a/clusters/my-gke-cluster. You can obtain the URI by running gcloud container clusters list --uri.
    • GKE_CLUSTER: the location/name of the GKE cluster from the current project. The location can be a zone or a region, for example: us-central1-a/my-gke-cluster.

Register a GKE cluster with a Service Account

  1. Ensure that you have created a service account for use by the Connect Agent, as described in our prerequisites.

  2. Run either of the following commands:

    gcloud container fleet memberships register MEMBERSHIP_NAME \
 --gke-uri=GKE_URI \
 --service-account-key-file=SERVICE_ACCOUNT_KEY_PATH

    or

    gcloud container fleet memberships register MEMBERSHIP_NAME \
 --gke-cluster=GKE_CLUSTER \
 --service-account-key-file=SERVICE_ACCOUNT_KEY_PATH

    Replace the following:

    • MEMBERSHIP_NAME: the membership name that you choose to uniquely represent the cluster being registered to the fleet.
    • SERVICE_ACCOUNT_KEY_PATH: the local filepath to the service account's private key JSON file downloaded as part of Prerequisites. This service account key is stored as a secret named creds-gcp in the gke-connect namespace.
    • GKE_URI: the URI of the GKE cluster, for example: https://container.googleapis.com/v1/projects/my-gke-project/locations/us-central1-a/clusters/my-gke-cluster. You can obtain the URI by running gcloud container clusters list --uri.
    • GKE_CLUSTER: the location/name of the GKE cluster from the current project. The location can be a zone or a region, for example: us-central1-a/my-gke-cluster.

Troubleshooting

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

What's next?