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 or the Google Cloud console (available with GKE Enterprise).
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:
- If you want your registered cluster to have fleet Workload Identity enabled (recommended), ensure GKE Workload Identity is enabled on the cluster. Autopilot clusters have Workload Identity enabled by default.
- If you are registering a cluster to a fleet in a different project (also known as cross-project registration), ensure you have set up the necessary permissions.
- If you are registering a cluster by using Terraform or Config Connector, ensure that you have set up a Google Cloud service account for the tool and configured it so that the tool can authenticate to Google Cloud:
- If you want to install the Connect Agent on your registered cluster (which is still required for a small number of use cases), ensure that you have an identity for the agent to use when authenticating to Google Cloud. This can be Workload Identity, as described above, or you can choose to create a Google service account.
Register your GKE 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.
If the entire Anthos platform is enabled (which you do by enabling the Anthos API in your project), you can register an existing cluster in the same project from the Google Cloud console. This is the simplest and quickest way to register a GKE cluster. 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.
If you have upgraded to GKE Enterprise, you can register a cluster at creation time in the Google Cloud console. You can also choose to register some or all of your existing clusters while upgrading to GKE Enterprise. Learn more about GKE Enterprise.
You can register a new or existing GKE cluster (with or without enabling the entire Anthos platform) by using the Google Cloud CLI.
You can create and register a GKE cluster (with or without enabling the entire Anthos platform) by using Terraform or Config Connector.
To register a GKE cluster:
Console
Create and register a new cluster
Follow the instructions in the GKE documentation to create your choice of Autopilot, Standard regional, or Standard zonal cluster from the Google Cloud console.
Before you finish creating the cluster, click Fleet in the navigation pane.
Select the Register to a fleet checkbox.
(Optional) If this is the first cluster that you have registered in this project, you can specify a descriptive name for your fleet in the Fleet name field. Otherwise, a default fleet name based on your project ID is used.
If you want the registered cluster to use fleet Workload Identity (recommended), click Security in the navigation pane and ensure that Enable Workload Identity is selected.
When you have finished reviewing cluster details, click Create to create and register the cluster to a fleet.
Register an existing cluster
- (Optional) If you want your fleet-registered Standard 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.
In the Google Cloud console, go to the Anthos Clusters page. This page shows all your registered clusters.
Click Register GKE cluster at the top of the page, which opens a new page with a list of unregistered clusters.
Click Register next to the unregistered cluster that you want to add to your fleet.
gcloud
You can use the Google Cloud CLI to register a new or an existing cluster. Note that the non-legacy commands require the gcloud CLI version 423.0.0 or higher, with the alpha or beta component installed.
Registering a cluster by using the Google Cloud CLI gives your cluster a regional membership location by default.
Create and register a cluster
To create a new GKE cluster and register it to a fleet in a single step, run one of the following commands, depending on whether you want to create a standard or Autopilot cluster:
gcloud beta container clusters create CLUSTER_NAME \ --fleet-project=FLEET_HOST_PROJECT \ --workload-pool=PROJECT_ID.svc.id.goog
or
gcloud beta container clusters create-auto CLUSTER_NAME \ --fleet-project=FLEET_HOST_PROJECT
where:
- CLUSTER_NAME is the name you have chosen for your cluster. 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.
- FLEET_HOST_PROJECT is the fleet host project for the fleet you want your cluster to join.
- PROJECT_ID is the Google Cloud project ID for the project that owns the new cluster.
If you are creating a standard cluster, we recommend creating the cluster with GKE Workload Identity enabled, as in the example, as this enables fleet Workload Identity for your registered cluster. Omit the --workload-pool
flag if you do not want to use this feature. Autopilot clusters have Workload Identity 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.
Register an existing cluster
To register an existing GKE cluster, run the following command:
gcloud beta container clusters update CLUSTER_NAME --fleet-project=FLEET_HOST_PROJECT
where:
- CLUSTER_NAME is the cluster's name. 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.
- FLEET_HOST_PROJECT is the fleet host project for the fleet you want your cluster to join.
This command enables fleet Workload Identity for the cluster if the cluster already has GKE Workload Identity enabled.
Register an existing cluster (legacy command)
This older command is still supported, although for most use cases we recommend registering existing clusters by using the update
command described in the previous section. Using this command lets you choose to install the Connect Agent on the cluster, which you may need for integration with some fleet services such as Cloud Deploy. You can choose for the agent to use fleet Workload Identity (recommended) or a Google Cloud service account when authenticating to Google Cloud.
Register a GKE cluster with fleet Workload Identity
Ensure that the cluster has GKE Workload Identity enabled, following the instructions in our prerequisites.
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 runninggcloud 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
.
If you want to install the Connect Agent on the cluster, add the optional
--install-connect-agent
flag to either command, as in the following example. By default (without this flag) the agent is not installed.gcloud container fleet memberships register MEMBERSHIP_NAME \ --gke-cluster=GKE_CLUSTER \ --enable-workload-identity \
--install-connect-agent
Register a GKE cluster with a service account
To register a cluster with the Connect Agent, specifying a service account:
Ensure that you have created a service account for use by the Connect Agent, as described in our prerequisites.
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 \ --install-connect-agent
or
gcloud container fleet memberships register MEMBERSHIP_NAME \ --gke-cluster=GKE_CLUSTER \ --service-account-key-file=SERVICE_ACCOUNT_KEY_PATH \ --install-connect-agent
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 thegke-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 runninggcloud 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
.
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.
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.
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 thegke-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.
- 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
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
.
- TF_CLUSTER_RESOURCE_NAME: the name that you choose to uniquely identify
the Terraform
Register a membership for the GKE cluster.
resource "google_gke_hub_membership" "TF_MEMBERSHIP_RESOURCE_NAME" { provider = google-beta project = "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}
.
- TF_MEMBERSHIP_RESOURCE_NAME: the name that you choose to uniquely identify the Terraform
Enable Workload Identity on a registered GKE cluster
Enabling Workload Identity uses the same configuration as registering a cluster, with the following additional steps.
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 { workload_pool = "PROJECT_ID.svc.id.goog" }
Replace the following:
- PROJECT_ID: the default project that you choose to provision your Terraform resources.
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}
.
- CLUSTER_RESOURCE_NAME: the Google Cloud resource for the GKE cluster. For example:
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
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.
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 on a registered GKE cluster
Enabling Workload Identity uses the same configuration as registering a cluster, with the following additional steps.
Enable GKE Workload Identity by adding the following in the
spec
field ofContainerCluster
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.
Enable fleet Workload Identity by adding the following in the
spec
field ofGKEHubMembership
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?
- Validate successful cluster registration and get other fleet membership details, as described in Get fleet membership status
- Set up authentication to registered clusters:
- Log in to a cluster from the Google Cloud console