General prerequisites

As you learned in the fleet creation overview, on-premises GKE clusters on VMware and on bare metal, and multicloud 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 registering any 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 the general 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 the installation 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 the alpha 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 the gcloud beta component, if you plan to try alpha or beta features:

     gcloud components install beta

Install kubectl

While kubectl 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 a kubectl version no lower than the minimum supported Kubernetes version of Google Kubernetes Engine (GKE).

We recommend installing kubectl with Google Cloud CLI.

To check the version of kubectl: 

kubectl version

The client version is indicated by gitVersion of the output.

To install kubectl: 

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 reach googleapis.com and gkeconnect.googleapis.com addresses, either directly or by using a configured proxy server.

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

  • iam.googleapis.com

Non-project owners must be granted the serviceusage.services.enable permission before they can enable APIs.

gcloud

To enable these APIs, run the following command:

gcloud services enable \
   --project=FLEET_HOST_PROJECT_ID \
   container.googleapis.com \
   gkeconnect.googleapis.com \
   gkehub.googleapis.com \
   cloudresourcemanager.googleapis.com \
   iam.googleapis.com

where:

If you don't want to enable fleet Workload Identity, you can omit iam.googleapis.com.

To list APIs you've already enabled in your projects, follow the instructions in Listing 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 have roles/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 have roles/owner in your project, you need to be granted specific IAM roles before you can connect clusters to Google, as follows:

  • To register a cluster with fleet Workload Identity for authentication to Google, you just need the following 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 the gkehub roles, see Connect IAM roles.

gcloud

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

gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
   --member user: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 find this value.
  • GCP_EMAIL_ADDRESS is the account the user uses to log in to Google Cloud.
  • ROLE is the IAM role you want to grant, such as roles/gkehub.admin.

To learn more about how to grant IAM roles, refer to Granting, Changing, and Revoking Access to Resources in the IAM 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).

GKE clusters on Google Cloud

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

  • roles/container.admin

This IAM role includes the Kubernetes RBAC cluster-admin role. For other cluster environments you need to grant this RBAC role using kubectl, as described in the next section. You can find out more about the relationship between IAM and RBAC roles in GKE in the GKE documentation.

Clusters outside Google Cloud

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

kubectl

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

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

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

kubectl create clusterrolebinding BINDING_NAME --clusterrole cluster-admin --user USER

where:

  • BINDING_NAME is a name that you choose for the ClusterRoleBinding resource.
  • 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: