General prerequisites

As you learned in thefleet creation overview, on-premises GKE clusterson VMware andon bare metal, andmulticloud clusters (both on AWS and Azure) are automatically registered to your project fleet at cluster creation time. However, GKE clusters on Google Cloud and third-party Kubernetes clusters (attached clusters) must be manually registered to join your fleet. You can find more details about different registration options in the fleet creation overview.

This page describes the prerequisites and requirements for manually registeringany Kubernetes cluster to a Google Cloud fleet. There are also specific separate requirements for GKE clusters on Google Cloud and attached clusters. Once you have completed this guide, follow the instructions for the cluster type you want to register.

We recommend that you review thegeneral restrictions on cluster registration before you begin.

Install command line tools

Ensure you have the following command line tools installed. If you are using Cloud Shell as your shell environment for interacting with Google Cloud, these tools are installed for you.

Install the Google Cloud CLI

Google Cloud CLI is the command line interface (CLI) to Google Cloud. You can register clusters by using Google Cloud CLI or, depending on your cluster type, by using other tools such as Terraform or the Google Cloud console. However, even if you don't use it for cluster registration,gcloud is required or useful for many of the other setup steps in this guide.

  1. If you don't have it installed already, install the Google Cloud CLI following theinstallation instructions. We recommend using the most recent version of the Google Cloud CLI. You need version version 361.0.0 or higher to register clusters, and version 423.0.0 or higher if you want to use the non-legacy registration commands for GKE, with thealpha or beta component installed.

  2. Run the following command to log in to Google Cloud:

    gcloud auth login

  3. (Optional) Ensure that you have installed thegcloud beta component, if you plan to try alpha or beta features:

     gcloud components install beta

Installkubectl

Whilekubectl is not required to register a cluster, you may need it to grant the necessary role-based access control (RBAC) permissions to the user registering the cluster (if they are not the cluster owner), as well as for other platform-specific setup. You need akubectl version no lower than theminimum supported Kubernetes version of Google Kubernetes Engine (GKE).

We recommend installingkubectl withGoogle Cloud CLI.

To check the version ofkubectl:

kubectl version

The client version is indicated bygitVersion of the output.

To installkubectl:

gcloud components install kubectl

Enable APIs

You need to enable the following APIs in your fleet host project:

  • container.googleapis.com
  • gkeconnect.googleapis.com
  • gkehub.googleapis.com, also known as the Fleet API. This is the Google Cloud service that handles cluster registration and fleet membership.
  • cloudresourcemanager.googleapis.com

Pods in the cluster you want to register must be able to reachgoogleapis.com andgkeconnect.googleapis.com addresses, either directly or by using a configuredproxy server.

If you want toenable fleet Workload Identity for your registration, you must also enable the following:

  • iam.googleapis.com

Non-project owners must be granted theserviceusage.services.enable permissionbefore they can enable APIs.

Note: This permission allows non-project owners to enable any API in the project.If you do not want to grant that level of access, you can enable the list ofAPIs for each registration user in the project.

To list APIs you've already enabled in your projects, follow the instructions inListing Services in the Service Usage documentation.

Grant access permissions

Ensure that you have the appropriate access permissions to register a cluster. Cluster registration requires both permission to register the cluster to a fleet, and admin permissions on the cluster itself.

Grant cluster registration permissions

Registering a cluster requires IAM permissions in your fleet host project to register clusters. If you haveroles/owner in your fleet host project, you have this automatically and have all the access permissions you need to complete all registration tasks.

If you do not haveroles/owner in your project, you need to begranted specific IAM roles before you can connectclusters to Google, as follows:

  • To register a cluster with fleetWorkload Identity for authentication to Google, you just need thefollowing IAM role:

    • roles/gkehub.admin

  • Some registration options outside Google Cloud require you to set up a service account for the cluster to use to authenticate to Google instead of Workload Identity. To register the cluster and manage this service account, you need the following set of roles:

    • roles/gkehub.admin
    • roles/iam.serviceAccountAdmin
    • roles/iam.serviceAccountKeyAdmin
    • roles/resourcemanager.projectIamAdmin

For a list of detailed permissions included in thegkehub roles, seeConnect IAM roles.

gcloud

To grant an IAM role to a user, run the following command:

gcloudprojectsadd-iam-policy-bindingFLEET_HOST_PROJECT_ID\--memberuser:GCP_EMAIL_ADDRESS\--role=ROLE

where:

  • FLEET_HOST_PROJECT_ID is the Google Cloud project ID in which you want to register clusters.Learn how to findthis value.
  • GCP_EMAIL_ADDRESS is the account the user uses to log into Google Cloud.
  • ROLE is the IAM role you want to grant, such asroles/gkehub.admin.

To learn more about how to grant IAM roles, refer toGranting, Changing, and Revoking Access to Resources in theIAM documentation.

Grant cluster admin permissions

In addition to the permissions required to register a cluster, you also need admin permissions on the cluster itself. Depending on your cluster's location you can assign this permission by using IAM roles or Kubernetes role-based access control (RBAC).

Note:cluster-admin provides super-user access to perform any action on anyresource in the cluster. Use caution when you assign this role to other users.

GKE clusters on Google Cloud

For GKE clusters on Google Cloud only, add the following IAM role to getadmin permissions on the cluster, if you don't have it already (your user account islikely to have it if you created the cluster):

  • roles/container.admin

This IAM role includes theKubernetes RBACcluster-admin role. For othercluster environments you need to grant this RBAC role usingkubectl, as described in the next section.You can find out more about the relationship between IAM and RBACroles in GKE in theGKE documentation.

Clusters outside Google Cloud

For attaching third-party clusters outside Google Cloud, ensure the user registering the cluster has theKubernetes RBACcluster-admin role.

kubectl

If you created the cluster, you likely have this role. You can verify by runningthe following command:

kubectl auth can-i '*' '*' --all-namespaces

If you or another user needs the role, create a ClusterRoleBinding resource in the cluster:

kubectlcreateclusterrolebindingBINDING_NAME--clusterrolecluster-admin--userUSER

where:

  • BINDING_NAME is a name that you choose for the ClusterRoleBindingresource.
  • USER is the identity used to authenticate against the cluster.

What's next?

Follow the prerequisites guide for the cluster type you want to register:

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.