This page shows you how to more securely access Google Cloud APIs fromyour workloads that run in Google Kubernetes Engine (GKE) clusters by usingWorkload Identity Federation for GKE.

This page is for Identity and account admins, Operators, andDevelopers who create and manage policies related to userpermissions. To learn more about common roles and example tasks that wereference in Google Cloud content, seeCommon GKE user roles and tasks.

Before reading this page, ensure that you're familiar withWorkload Identity Federation for GKE concepts.

Before you begin

Before you start, make sure that you have performed the following tasks:

• Enable the Google Kubernetes Engine API.
Enable Google Kubernetes Engine API
• If you want to use the Google Cloud CLI for this task,install and theninitialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running thegcloud components update command. Earlier gcloud CLI versions might not support running the commands in this document.Note: For existing gcloud CLI installations, make sure to set thecompute/regionproperty. If you use primarily zonal clusters, set thecompute/zone instead. By setting a default location, you can avoid errors in the gcloud CLI like the following:One of [--zone, --region] must be supplied: Please specify location. You might need to specify the location in certain commands if the location of your cluster differs from the default that you set.

• Ensure that the Google Cloud APIs that you want to access are supportedby Workload Identity Federation for GKE. For a list of supported APIs, seeSupported products and limitations.If the API isn't supported or if your use case is blocked by thelimitations of Workload Identity Federation for that service, seeAlternative: link Kubernetes ServiceAccounts to IAMin this page.

• Ensure that you have enabled the IAM Service Account Credentials API.

  EnableIAM Credentials API

• Ensure that you have the followingIAM roles:

  • roles/container.admin
  • roles/iam.serviceAccountAdmin

• Ensure that you understand thelimitations of Workload Identity Federation for GKE.

• Ensure that you have an existing Autopilot or Standardcluster. To create a new cluster, seeCreate an Autopilot cluster.

Enable Workload Identity Federation for GKE on clusters and node pools

In Autopilot, Workload Identity Federation for GKE is always enabled. Skip to theConfigure applications to use Workload Identity Federation for GKE section.

In Standard, you enable Workload Identity Federation for GKE on clusters and nodepools using the Google Cloud CLI or the Google Cloud console.Workload Identity Federation for GKEmust be enabled at the cluster level before you canenable Workload Identity Federation for GKE on node pools.

You can enable Workload Identity Federation for GKE on an existing Standard cluster byusing the gcloud CLI or the Google Cloud console. Existing node poolsare unaffected, but any new node pools in the cluster use Workload Identity Federation for GKE.

Migrate existing workloads to Workload Identity Federation for GKE

After you enable Workload Identity Federation for GKE on an existing cluster, you might want tomigrate your running workloads to use Workload Identity Federation for GKE. Select themigration strategy that is ideal for your environment. You can create new node pools with Workload Identity Federation for GKEenabled, or update existing node pools to enable Workload Identity Federation for GKE.

You can only enable Workload Identity Federation for GKE on a node pool if Workload Identity Federation for GKEis enabled on the cluster.

Create a new node pool

All new node pools that you create default to using Workload Identity Federation for GKE if thecluster has Workload Identity Federation for GKE enabled. To create a new node pool withWorkload Identity Federation for GKE enabled, run the following command:

gcloudcontainernode-poolscreateNODEPOOL_NAME\--cluster=CLUSTER_NAME\--location=CONTROL_PLANE_LOCATION\--workload-metadata=GKE_METADATA

Replace the following:

• NODEPOOL_NAME: the name of the new node pool.
• CLUSTER_NAME: the name of the existing cluster that hasWorkload Identity Federation for GKE enabled.
• CONTROL_PLANE_LOCATION: the Compute Enginelocation of the control plane of yourcluster. Provide a region for regional clusters, or a zone for zonal clusters.

The--workload-metadata=GKE_METADATA flag configures the node pool to usethe GKE metadata server.

Update an existing node pool

You can manually enable Workload Identity Federation for GKE on existing node pools after youenable Workload Identity Federation for GKE on the cluster.

Configure applications to use Workload Identity Federation for GKE

To let your GKE applications authenticate to Google CloudAPIs using Workload Identity Federation for GKE, you create IAM policies forthe specific APIs. The principal in these policies is an IAMprincipal identifier that corresponds to the workloads, namespaces, orKubernetes ServiceAccounts. This process returns a federated access token thatyour workload can use in API calls.

Alternatively, you can configure Kubernetes ServiceAccounts to impersonateIAM service accounts, which configures GKE to exchange thefederated access token for an access token from the IAMService Account Credentials API. For details, see theAlternative: link Kubernetes ServiceAccounts to IAMsection.

Configure authorization and principals

1. Get credentials for your cluster:

   gcloudcontainerclustersget-credentialsCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION

   Replace the following:

   • CLUSTER_NAME: the name of your clusterthat has Workload Identity Federation for GKE enabled.
   • CONTROL_PLANE_LOCATION: the Compute Enginelocation of the control plane of yourcluster. Provide a region for regional clusters, or a zone for zonal clusters.

2. Create a namespace to use for the Kubernetes service account. You can alsouse thedefault namespace or any existing namespace.

   kubectlcreatenamespaceNAMESPACE

3. Create a Kubernetes ServiceAccount for your application to use. You canalso use any existing Kubernetes ServiceAccount in any namespace. If youdon't assign a ServiceAccount to your workload, Kubernetes assigns thedefault ServiceAccount in the namespace.

   kubectlcreateserviceaccountKSA_NAME\--namespaceNAMESPACE

   Replace the following:

   • KSA_NAME: the name of your new KubernetesServiceAccount.
   • NAMESPACE: the name of the Kubernetes namespacefor the ServiceAccount.

4. Create an IAM allow policy that references the KubernetesServiceAccount. As a good practice, grant permissions to specificGoogle Cloud resources that your application needs to access. You musthave relevant IAM permissions to create allow policies inyour project.

   For example, the following command grants theKubernetes Engine Cluster Viewer(roles/container.clusterViewer) role to the ServiceAccount that youcreated:

   gcloudprojectsadd-iam-policy-bindingprojects/PROJECT_ID\--role=roles/container.clusterViewer\--member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME\--condition=None

   Replace the following:

   • PROJECT_ID: your Google Cloud project ID.
   • PROJECT_NUMBER: your numerical Google Cloudproject number.

   You can grant roles on any Google Cloud resource that supportsIAM allow policies. The syntax of the principal identifierdepends on the Kubernetes resource. For a list of supported identifiers, seePrincipal identifiers for Workload Identity Federation for GKE.

Optional: Configure service mesh options

If you use Istio or Cloud Service Mesh to manage your environment, add the followingannotation to themetadata.annotations field in your Pod specification:

metadata:  annotations:proxy.istio.io/config: '{ "holdApplicationUntilProxyStarts": true }'

This annotation prevents your containers from starting until the service meshproxy is ready to redirect traffic from your applications.

Verify the Workload Identity Federation for GKE setup

In this section, you create a Cloud Storage bucket and grant view access onthe bucket to the Kubernetes ServiceAccount that you created in the previoussection. You then deploy a workload and test that the container can listclusters in the project.

1. Create an empty Cloud Storage bucket:

   gcloudstoragebucketscreategs://BUCKET

   ReplaceBUCKET with a name for your new bucket.

2. Grant theStorage Object Viewer(roles/storage.objectViewer) role to the ServiceAccount that youcreated:

   gcloudstoragebucketsadd-iam-policy-bindinggs://BUCKET\--role=roles/storage.objectViewer\--member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME\--condition=None

   Replace the following:

   • PROJECT_ID: your Google Cloud project ID.
   • PROJECT_NUMBER: your numerical Google Cloudproject number.
   • NAMESPACE: the Kubernetes namespace that containsthe ServiceAccount.
   • KSA_NAME: the name of the ServiceAccount.

3. Save the following manifest astest-app.yaml:

   apiVersion:v1kind:Podmetadata:name:test-podnamespace:NAMESPACEspec:serviceAccountName:KSA_NAMEcontainers:-name:test-podimage:google/cloud-sdk:slimcommand:["sleep","infinity"]resources:requests:cpu:500mmemory:512Miephemeral-storage:10Mi

4. In Standard clusters only, add the following to thetemplate.specfield to place the Pods on node pools that use Workload Identity Federation for GKE.

   Skip this step in Autopilot clusters, which reject this nodeSelectorbecause every node uses Workload Identity Federation for GKE.

   spec:nodeSelector:iam.gke.io/gke-metadata-server-enabled:"true"

5. Apply the configuration to your cluster:

   kubectlapply-ftest-app.yaml

6. Wait for the Pod to become ready. To check the status of the Pod, run thefollowing command:

   kubectlgetpods--namespace=NAMESPACE

   When the Pod is ready, the output is similar to the following:

   NAME       READY   STATUS    RESTARTS   AGEtest-pod   1/1     Running   0          5m27s

7. Open a shell session in the Pod:

   kubectlexec-itpods/test-pod--namespace=NAMESPACE--/bin/bash

8. Get a list of objects in the bucket:

   curl-XGET-H"Authorization: Bearer$(gcloudauthprint-access-token)"\"https://storage.googleapis.com/storage/v1/b/BUCKET/o"

   The output is the following:

   {  "kind": "storage#objects"}

   This output shows that your Pod can access objects in the bucket.

Alternative: link Kubernetes ServiceAccounts to IAM

1. Create a Kubernetes namespace:

   kubectlcreatenamespaceNAMESPACE

2. Create a Kubernetes ServiceAccount:

   kubectlcreateserviceaccountKSA_NAME\--namespace=NAMESPACE

3. Create an IAM service account. You can also use any existingIAM service account in any project in your organization.

   gcloudiamservice-accountscreateIAM_SA_NAME\--project=IAM_SA_PROJECT_ID

   Replace the following:

   • IAM_SA_NAME: a name for your new IAMservice account.
   • IAM_SA_PROJECT_ID: the project ID for yourIAM service account.

   For information on authorizing IAM service accounts to access Google CloudAPIs, seeUnderstanding service accounts.

4. Grant your IAM service account the roles that it needs onspecific Google Cloud APIs:

   gcloudprojectsadd-iam-policy-bindingIAM_SA_PROJECT_ID\--member"serviceAccount:IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com"\--role"ROLE_NAME"

   ReplaceROLE_NAME with the name of the role, likeroles/spanner.viewer.

5. Create an IAM allow policy that gives the KubernetesServiceAccount access to impersonate the IAM service account:

   gcloudiamservice-accountsadd-iam-policy-bindingIAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com\--roleroles/iam.workloadIdentityUser\--member"serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"

   The member name must include the namespace and Kubernetes ServiceAccountname. For example,serviceAccount:example-project.svc.id.goog[example-namespace/example-serviceaccount].

6. Annotate the Kubernetes ServiceAccount so that GKE sees thelink between the service accounts:

   kubectlannotateserviceaccountKSA_NAME\--namespaceNAMESPACE\iam.gke.io/gcp-service-account=IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com

   Both the IAM allow policyand the annotation arerequired when you use this method.

7. Optional: Annotate the Kubernetes ServiceAccount so that your applicationsget the identifier in the IAM principal identifier syntax:

   kubectlannotateserviceaccountKSA_NAME\--namespace=NAMESPACE\iam.gke.io/return-principal-id-as-email="true"

Use Workload Identity Federation for GKE from your code

Authenticating to Google Cloud services from your code is the same processas authenticating using theCompute Engine metadataserver. When you use Workload Identity Federation for GKE, yourrequests to the instance metadata server are routed to theGKE metadata server.Existing code that authenticates using the instance metadata server (like codeusing theGoogle Cloud client libraries)should work without modification.

Use quota from a different project with Workload Identity Federation for GKE

On clusters running GKE version 1.24 or later, you can optionally configure your Kubernetes service account to use quotafrom a different Google Cloud project when making calls totheGenerateAccessToken and theGenerateIdToken methods in theIAM Service Account Credentials API. This lets you avoid using the entire quota inyour main project, and instead use quota from other projects forthese services in your cluster.

To configure aquota project with Workload Identity Federation for GKE, do thefollowing:

1. Grant theserviceusage.services.use permission on the quota projectto the Kubernetes service account.

   gcloudprojectsadd-iam-policy-bindingQUOTA_PROJECT_ID\--role=roles/serviceusage.serviceUsageConsumer\--member='principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME'\

   ReplaceQUOTA_PROJECT_ID with the project IDof the quota project.

2. Annotate the Kubernetes service account with the quota project:

   kubectlannotateserviceaccountKSA_NAME\--namespaceNAMESPACE\iam.gke.io/credential-quota-project=QUOTA_PROJECT_ID

To verify the configuration works correctly, do the following:

1. Create a Pod and start a shell session. See the Kubernetes documentationtoGet a Shell to a Running Container.

2. Make a request to the metadata server:

   curl-H"Metadata-Flavor: Google"http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token

3. Go to theIAM Service Accounts Credentials API pagein the Google Cloud console for your quota project:

   Go to APIs

4. Check for changes in traffic.

Clean up

To stop using Workload Identity Federation for GKE, revoke access to the IAMservice account and disable Workload Identity Federation for GKE on the cluster.

Revoke access

To revoke access to the principal, remove the IAM allow policythat you created in theConfigure applications to use Workload Identity Federation for GKE section.

For example, to revoke access to an Artifact Registry repository, run the followingcommand:

gcloudartifactsrepositoriesremove-iam-policy-bindingREPOSITORY_NAME\--location=REPOSITORY_LOCATION\--member='principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME'\--role='roles/artifactregistry.reader'\--all

Disable Workload Identity Federation for GKE

You can only disable Workload Identity Federation for GKE on Standardclusters.

Disable Workload Identity Federation for GKE in your organization

The steps in thelink Kubernetes ServiceAccounts to IAMsection let Kubernetes ServiceAccounts impersonate the identity of the linkedIAM service account. Long-lived API tokens for the KubernetesServiceAccounts can be exchanged for the corresponding IAMservice account access tokens.

You might want to disable Workload Identity Federation for GKE for clusters in yourorganization, folder, or project when you want to isolate workloads fromIAM service accounts. For example, if you plan todisable service account creationordisable service account key creation,disabling Workload Identity Federation for GKE prevents the exchange of ServiceAccount tokensfor IAM service account access tokens.

For more information, seeDisable workload identity cluster creation.

Troubleshooting

For troubleshooting information, refer toTroubleshooting Workload Identity Federation for GKE.

What's next

• Learn more aboutWorkload Identity Federation for GKE.
• Read theGKE security overview.
• Learn aboutProtecting Cluster Metadata.
• Learn aboutIAM service accounts.