If you're registering a GKE cluster on Google Cloud, you might need to do one or more of the following before registering the cluster, depending on the registration option that you choose. This guide assumes that you've already completed the general prerequisites for cluster registration.
Enable GKE Workload Identity
We recommend registering your GKE clusters with fleet Workload Identity enabled, which provides a consistent way for applications on the clusters 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.
To use this feature, you must ensure GKE Workload Identity is enabled on the cluster before registration. Registering a GKE cluster with fleet Workload Identity without having GKE Workload Identity enabled on the cluster can lead to inconsistencies on how identity is asserted by workloads in the cluster, and is not a supported configuration.
gcloud
To check if your GKE cluster has Workload Identity enabled, run the following command to list the cluster's Workload Identity pool. If you haven't already specified a default zone or region for gcloud
, you may also need to specify a --region
or --zone
flag when running this command.
gcloud container clusters describe CLUSTER_NAME --format="value(workloadIdentityConfig.workloadPool)"
Replace the following:
- CLUSTER_NAME: the
name
of the GKE cluster.
If you see a result similar to the following then Workload Identity is already enabled on your GKE cluster:
GKE_PROJECT_ID.svc.id.goog
If there are no results, then Workload Identity is not enabled. To enable Workload Identity, follow the instructions in Enabling Workload Identity.
Grant permissions for registering a cluster into a different project
Registering a GKE cluster to the fleet in its own project does not require any special permissions beyond those described in Grant access permissions. However, if you want to register a GKE cluster from its own project (GKE_PROJECT) to a fleet in a different project (FLEET_HOST_PROJECT), the FLEET_HOST_PROJECT service agent account gcp-sa-gkehub
must have the gkehub.serviceAgent
role in the GKE_PROJECT project. This role grants the service account the permissions to manage cluster resources in that project.
You can check if the fleet host project gcp-sa-gkehub
service account has the required role in your cluster's project
using gcloud CLI or the Google Cloud console, as follows.
gcloud
Run the following command:
gcloud projects get-iam-policy GKE_PROJECT_ID
Console
With your cluster's project selected, go to the IAM & Admin page in the Google Cloud console.
Select the Include Google-provided role grants checkbox to view the complete policy, including service agents.
If you see gcp-sa-gkehub
, it should have the form
service-[FLEET_HOST-PROJECT-NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com
. For example:
- members:
- serviceAccount:service-1234567890@gcp-sa-gkehub.iam.gserviceaccount.com
role: roles/gkehub.serviceAgent
If you don't see the service agent listed in the project's IAM policy, do the following to update the necessary permissions:
gcloud
To grant
gcp-sa-gkehub
thegkehub.serviceAgent
role, first ensure that this service account exists. If you have registered clusters in this project before, then this service account should exist already. You can check by looking at the IAM policy for the fleet host project:gcloud projects get-iam-policy FLEET_HOST_PROJECT_ID
If you need to create the
gcp-sa-gkehub
service account, run the following command:gcloud beta services identity create --service=gkehub.googleapis.com --project=FLEET_HOST_PROJECT_ID
This command should output the following:
Service identity created: service-[FLEET_HOST_PROJECT_NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com
Run the following command to grant the service account the
roles/gkehub.serviceAgent
role in both projects:GKE_PROJECT_ID=GKE_PROJECT_ID FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID FLEET_HOST_PROJECT_NUMBER=$(gcloud projects describe "${FLEET_HOST_PROJECT_ID}" --format "value(projectNumber)") gcloud projects add-iam-policy-binding "${FLEET_HOST_PROJECT_ID}" \ --member "serviceAccount:service-${FLEET_HOST_PROJECT_NUMBER}@gcp-sa-gkehub.iam.gserviceaccount.com" \ --role roles/gkehub.serviceAgent gcloud projects add-iam-policy-binding "${GKE_PROJECT_ID}" \ --member "serviceAccount:service-${FLEET_HOST_PROJECT_NUMBER}@gcp-sa-gkehub.iam.gserviceaccount.com" \ --role roles/gkehub.serviceAgent
where:
- GKE_PROJECT_ID is the Google Cloud project ID of the GKE cluster.
- FLEET_HOST_PROJECT_ID is the Google Cloud project ID in which you want to register clusters. Learn how to find this value.
To confirm that the role binding is granted, run the following command again:
gcloud projects get-iam-policy GKE_PROJECT_ID
If you see the service account name along with the
gkehub.serviceAgent
role, the role binding has been granted. For example:- members: - serviceAccount:service-[FLEET_HOST_PROJECT_NUMBER]@gcp-sa-gkehub.iam.gserviceaccount.com role: roles/gkehub.serviceAgent
Set up an identity for use by the Connect Agent
While most registration options for GKE clusters on Google Cloud do not install the Connect Agent on your clusters, you currently need to install the agent to use the Connect gateway. You can choose to do this by registering the cluster using the Google Cloud CLI. The Connect Agent needs an identity to authenticate to Google Cloud, which can be one of the following options:
- Fleet Workload Identity (recommended): Ensure the cluster has GKE Workload Identity enabled before you register the cluster, as described above. The Connect Agent can then use fleet Workload Identity to authenticate to Google Cloud.
- Service account: If you choose to use a Google Cloud service account instead of Workload Identity, follow the instructions in the guide for clusters outside Google Cloud to create a service account and download its JSON key.
Configure a service account for Terraform
If you want to use Terraform to register a Google Kubernetes Engine cluster, you need to create a service account that Terraform can use to access the Fleet API to create a membership.
gcloud
Create a service account as follows:
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME --project=FLEET_HOST_PROJECT_ID
Bind the
gkehub.admin
IAM role to the service account so that Terraform can use it with the Fleet API:FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \ --member="serviceAccount:SERVICE_ACCOUNT_NAME@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \ --role="roles/gkehub.admin"
If you want to create a new cluster with Terraform and then register it, you also need to bind
roles/container.admin
role to the service account so that Terraform can use this service account to access the GKE API to create a cluster.FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \ --member="serviceAccount:SERVICE_ACCOUNT_NAME@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \ --role="roles/container.admin"
Replace the following:
- FLEET_HOST_PROJECT_ID is the Google Cloud project ID in which you want to register clusters. Learn how to find this value.
- SERVICE_ACCOUNT_NAME is the display name that you choose for the [Service Account].
Download the service account's private key JSON file, as described in Create a Google Cloud service account using
gcloud
. You will need this file to create and register clusters using Terraform.
Configure a service account for Config Connector
If you want to use Config Connector to register a GKE cluster, do the following:
gcloud
Ensure that you have installed the Config Connector add-on. You should have a version of Config Connector above 1.47.0.
Follow the Config Connector instructions to create a service account.
Bind the
gkehub.admin
IAM role to this service account so that your Config Connector can use this service account to access the Fleet API:FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \ --member="serviceAccount:SERVICE_ACCOUNT_NAME@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \ --role="roles/gkehub.admin"
If you want to create a new cluster with Config Connector and then register it, you also need to bind
roles/container.admin
role to the service account so that your Config Connector controller can use this service account to access the GKE API to create a cluster.FLEET_HOST_PROJECT_ID=FLEET_HOST_PROJECT_ID gcloud projects add-iam-policy-binding ${FLEET_HOST_PROJECT_ID} \ --member="serviceAccount:SERVICE_ACCOUNT_NAME@${FLEET_HOST_PROJECT_ID}.iam.gserviceaccount.com" \ --role="roles/container.admin"
Replace the following:
- FLEET_HOST_PROJECT_ID is the Google Cloud project ID in which you want to register clusters. Learn how to find this value.
- SERVICE_ACCOUNT_NAME is the display name that you choose for the [Service Account].
Follow the Config Connector instruction to configure your Config Connector with this service account.
What's next?
Follow the instructions to register a cluster.