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.
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.
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.
Run the following command to log in to Google Cloud:
gcloud auth login
(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:
- FLEET_HOST_PROJECT_ID is the Google Cloud project ID in which you want to register clusters. Learn how to find this value.
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:
- Prerequisites for GKE clusters on Google Cloud
- Prerequisites for EKS clusters
- Prerequisites for AKS clusters
- Prerequisites for other attached cluster types