Prerequisites for GKE clusters on Google Cloud

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.

Go to the IAM & Admin page
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 the gkehub.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.