Use workload identity federation for GKE


This document shows you how to enable and configure workload identity federation for GKE on your Google Kubernetes Engine (GKE) clusters. Workload identity federation for GKE allows workloads in your GKE clusters to impersonate Identity and Access Management (IAM) service accounts to access Google Cloud services. To learn more about how workload identity federation for GKE works, as well as limitations, refer to workload identity federation for GKE.

Before you begin

Before you start, make sure 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 then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running gcloud components update.

Enable workload identity federation for GKE

You can enable workload identity federation for GKE on clusters and node pools using the Google Cloud CLI or the Google Cloud console. Workload identity federation for GKE must be enabled at the cluster level before you can enable workload identity federation for GKE on node pools.

Autopilot clusters enable workload identity federation for GKE by default. To configure Autopilot Pods to use workload identity federation for GKE, skip to Configure applications to use workload identity federation for GKE.

Create a new cluster

You can enable workload identity federation for GKE on a new Standard cluster by using the gcloud CLI or the Google Cloud console.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. To enable workload identity federation for GKE on a new cluster, run the following command:

    gcloud container clusters create CLUSTER_NAME \
        --region=COMPUTE_REGION \
        --workload-pool=PROJECT_ID.svc.id.goog
    

    Replace the following:

    • CLUSTER_NAME: the name of your new cluster.
    • COMPUTE_REGION: the Compute Engine region of your cluster. For zonal clusters, use --zone=COMPUTE_ZONE.
    • PROJECT_ID: your Google Cloud project ID.

Console

To enable workload identity federation for GKE on a new cluster, do the following:

  1. Go to the Google Kubernetes Engine page in the Google Cloud console.

    Go to Google Kubernetes Engine

  2. Click Create.

  3. In the Create cluster dialog, for GKE Standard, click Configure.

  4. In the navigation menu, in the Cluster section, click Security.

  5. Select the Enable Workload Identity checkbox.

  6. Continue configuring the cluster, and then click Create.

Update an existing cluster

You can enable workload identity federation for GKE on an existing Standard cluster by using the gcloud CLI or the Google Cloud console. Existing node pools are unaffected, but any new node pools in the cluster use workload identity federation for GKE.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. To enable workload identity federation for GKE on an existing cluster, run the following command:

    gcloud container clusters update CLUSTER_NAME \
        --region=COMPUTE_REGION \
        --workload-pool=PROJECT_ID.svc.id.goog
    

    Replace the following:

    • CLUSTER_NAME: the name of your existing cluster.
    • COMPUTE_REGION: the Compute Engine region of your cluster. For zonal clusters, use --zone=COMPUTE_ZONE.
    • PROJECT_ID: your Google Cloud project ID.

Console

To enable workload identity federation for GKE on an existing cluster, do the following:

  1. Go to the Google Kubernetes Engine page in Google Cloud console.

    Go to Google Kubernetes Engine

  2. In the cluster list, click the name of the cluster you want to modify.

  3. On the cluster details page, in the Security section, click Edit workload identity federation for GKE.

  4. In the Edit Workload Identity dialog, select the Enable Workload Identity checkbox.

  5. Click Save changes.

Migrate existing workloads to workload identity federation for GKE

After you enable workload identity federation for GKE on an existing cluster, you might want to migrate your running workloads to use workload identity federation for GKE. Select the migration strategy that is ideal for your environment. You can create new node pools with workload identity federation for GKE enabled, or update existing node pools to enable workload identity federation for GKE.

We recommend creating new node pools if you also need to modify your applications to be compatible with workload identity federation for GKE.

All new node pools that you create default to using workload identity federation for GKE if the cluster has workload identity federation for GKE enabled. To create a new node pool with workload identity federation for GKE enabled, run the following command:

gcloud container node-pools create NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --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 has workload identity federation for GKE enabled.

The --workload-metadata=GKE_METADATA flag configures the node pool to use the GKE metadata server. We recommend that you include the flag so that node pool creation fails if workload identity federation for GKE is not enabled on the cluster.

Update an existing node pool

You can manually enable workload identity federation for GKE on existing node pools after you enable workload identity federation for GKE on the cluster.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. To modify an existing node pool to use workload identity federation for GKE, run the following command:

    gcloud container node-pools update NODEPOOL_NAME \
        --cluster=CLUSTER_NAME \
        --region=COMPUTE_REGION \
        --workload-metadata=GKE_METADATA
    

    If a cluster has workload identity federation for GKE enabled, you can selectively disable it on a specific node pool by explicitly specifying --workload-metadata=GCE_METADATA. See Protecting cluster metadata for more information.

Console

To modify an existing node pool to use workload identity federation for GKE, perform the following steps:

  1. Go to the Google Kubernetes Engine page in Google Cloud console.

    Go to Google Kubernetes Engine

  2. In the cluster list, click the name of the cluster that you want to modify.

  3. Click the Nodes tab.

  4. In the Node Pools section, click the name of the node pool that you want to modify.

  5. On the Node pool details page, click Edit.

  6. On the Edit node pool page, in the Security section, select the Enable GKE Metadata Server checkbox.

  7. Click Save.

Configure applications to use workload identity federation for GKE

After enabling workload identity federation for GKE, you should configure your applications to authenticate to Google Cloud using workload identity federation for GKE before you migrate the applications to the new node pools.

You must assign a Kubernetes service account to the application and configure that Kubernetes service account to act as an IAM service account.

The following steps show you how to configure your applications to use workload identity federation for GKE if it is enabled on the cluster.

  1. Get credentials for your cluster:

    gcloud container clusters get-credentials CLUSTER_NAME \
        --region=COMPUTE_REGION
    

    Replace the following:

    • CLUSTER_NAME: the name of your cluster that has workload identity federation for GKE enabled.
    • COMPUTE_REGION: the Compute Engine region of your cluster.
  2. Create a namespace to use for the Kubernetes service account. You can also use the default namespace or any existing namespace.

    kubectl create namespace NAMESPACE
    
  3. Create a Kubernetes service account for your application to use. You can also use any existing Kubernetes service account in any namespace, including the default service account.

    kubectl create serviceaccount KSA_NAME \
        --namespace NAMESPACE
    

    Replace the following:

    • KSA_NAME: the name of your new Kubernetes service account.
    • NAMESPACE: the name of the Kubernetes namespace for the service account.
  4. Create an IAM service account for your application or use an existing IAM service account instead. You can use any IAM service account in any project in your organization. For Config Connector, apply the IAMServiceAccount object for your selected service account.

    gcloud

    1. In the Google Cloud console, activate Cloud Shell.

      Activate Cloud Shell

      At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    2. To create a new IAM service account using the gcloud CLI, run the following command.

      gcloud iam service-accounts create GSA_NAME \
          --project=GSA_PROJECT
      

      Replace the following:

      • GSA_NAME: the name of the new IAM service account.
      • GSA_PROJECT: the project ID of the Google Cloud project for your IAM service account.

    Config Connector

    To use a new or existing IAM service account with Config Connector, apply the following configuration file.

    Note: This step requires Config Connector. Follow the installation instructions to install Config Connector on your cluster.

    apiVersion: iam.cnrm.cloud.google.com/v1beta1
    kind: IAMServiceAccount
    metadata:
      name: [GSA_NAME]
    spec:
      displayName: [DISPLAY_NAME]
    To deploy this manifest, download it to your machine as service-account.yaml.

    Use kubectl to apply the manifest:

    kubectl apply -f service-account.yaml
    

    For information on authorizing IAM service accounts to access Google Cloud APIs, see Understanding service accounts.

  5. Ensure that your IAM service account has the roles you need. You can grant additional roles using the following command:

    gcloud projects add-iam-policy-binding GSA_PROJECT \
        --member "serviceAccount:GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com" \
        --role "ROLE_NAME"
    

    Replace the following:

    • GSA_PROJECT: the project ID of the Google Cloud project of your IAM service account.
    • GSA_NAME: the name of your IAM service account.
    • ROLE_NAME: the IAM role to assign to your service account, like roles/spanner.viewer.
  6. Allow the Kubernetes service account to impersonate the IAM service account by adding an IAM policy binding between the two service accounts. This binding allows the Kubernetes service account to act as the IAM service account.

    gcloud

    1. In the Google Cloud console, activate Cloud Shell.

      Activate Cloud Shell

      At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    2. In your development environment, run the following command:

      gcloud iam service-accounts add-iam-policy-binding GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com \
          --role roles/iam.workloadIdentityUser \
          --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"
      

    Config Connector

    Note: This step requires Config Connector. Follow the installation instructions to install Config Connector on your cluster.

    apiVersion: iam.cnrm.cloud.google.com/v1beta1
    kind: IAMPolicy
    metadata:
      name: iampolicy-workload-identity-sample
    spec:
      resourceRef:
        apiVersion: iam.cnrm.cloud.google.com/v1beta1
        kind: IAMServiceAccount
        name: [GSA_NAME]
      bindings:
        - role: roles/iam.workloadIdentityUser
          members:
            - serviceAccount:[PROJECT_ID].svc.id.goog[[K8S_NAMESPACE]/[KSA_NAME]]
    To deploy this manifest, download it to your machine as policy-binding.yaml. Replace GSA_NAME, PROJECT_ID, NAMESPACE and KSA_NAME the values for your environment. Then, run:

    kubectl apply -f policy-binding.yaml
    
  7. Annotate the Kubernetes service account with the email address of the IAM service account.

    kubectl

    1. In the Google Cloud console, activate Cloud Shell.

      Activate Cloud Shell

      At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    2. In your development environment, run the following command:

      kubectl annotate serviceaccount KSA_NAME \
          --namespace NAMESPACE \
          iam.gke.io/gcp-service-account=GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com
      

    yaml

    apiVersion: v1
    kind: ServiceAccount
    metadata:
      annotations:
        iam.gke.io/gcp-service-account: GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
      name: KSA_NAME
      namespace: NAMESPACE
    
  8. Update your Pod spec to schedule the workloads on nodes that use workload identity federation for GKE and to use the annotated Kubernetes service account.

    spec:
      serviceAccountName: KSA_NAME
      nodeSelector:
        iam.gke.io/gke-metadata-server-enabled: "true"
    
  9. Apply the updated configuration to your cluster:

    kubectl apply -f DEPLOYMENT_FILE
    

    Replace DEPLOYMENT_FILE with the path to the updated Pod spec.

Verify the workload identity federation for GKE setup

Verify the service accounts are configured correctly by creating a Pod with the Kubernetes service account that runs the OS-specific container image, then connect to it with an interactive session.

Linux

Create a Pod that uses the annotated Kubernetes service account and curl the service-accounts endpoint.

  1. Save the following configuration as wi-test.yaml:

    apiVersion: v1
    kind: Pod
    metadata:
      name: workload-identity-test
      namespace: NAMESPACE
    spec:
      containers:
      - image: google/cloud-sdk:slim
        name: workload-identity-test
        command: ["sleep","infinity"]
      serviceAccountName: KSA_NAME
      nodeSelector:
        iam.gke.io/gke-metadata-server-enabled: "true"
    

    The google/cloud-sdk image includes the Google Cloud CLI which is a convenient way to consume Google Cloud APIs. It might take some time to download the image.

  2. Create the Pod:

    kubectl apply -f wi-test.yaml
    
  3. Open an interactive session in the Pod:

    kubectl exec -it workload-identity-test \
      --namespace NAMESPACE \
      -- /bin/bash
    
  4. Run the following command inside the Pod to get the service account email:

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

    If the service accounts are correctly configured, the IAM service account email address is listed as the active (and only) identity. This demonstrates that by default, the Pod acts as the IAM service account's authority when calling Google Cloud APIs.

  5. Run the following command inside the Pod to get a token:

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

    If it returns any error, refer to Troubleshooting

Windows

Create a Pod with the Kubernetes service account that runs the servercore container image.

  1. Save the following manifest:

    apiVersion: v1
    kind: Pod
    metadata:
      name: workload-identity-test
      namespace: NAMESPACE
    spec:
      containers:
      - image: IMAGE_NAME
        name: workload-identity-test
        command: ["powershell.exe", "sleep", "3600"]
      serviceAccountName: KSA_NAME
      nodeSelector:
        kubernetes.io/os: windows
        cloud.google.com/gke-os-distribution: windows_ltsc
        iam.gke.io/gke-metadata-server-enabled: "true"
    

    Replace IMAGE_NAME with one of the following container servercore image values:

    Windows Server node image Container servercore image
    WINDOWS_LTSC,
    WINDOWS_LTSC_CONTAINERD
    mcr.microsoft.com/windows/servercore:ltsc2019
    WINDOWS_SAC,
    WINDOWS_SAC_CONTAINERD

    Check the version mapping between the GKE node version and the Windows SAC version. For Windows Server version 1909, specify mcr.microsoft.com/windows/servercore:1909; otherwise, specify mcr.microsoft.com/windows/servercore:20H2.

  2. Open an interactive session in the Pod:

    kubectl exec -it workload-identity-test \
      --namespace NAMESPACE -- powershell
    
  3. Run the following powershell command inside the Pod to get the service account email:

    Invoke-WebRequest  -Headers @{"Metadata-Flavor"="Google"} -Uri  http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/email  -UseBasicParsing
    

    If the service accounts are correctly configured, the IAM service account email address is listed as the active (and only) identity. This demonstrates that by default, the Pod uses the IAM service account's authority when calling Google Cloud APIs.

  4. Run the following command inside the Pod to get a token:

    Invoke-WebRequest  -Headers @{"Metadata-Flavor"="Google"} -Uri  http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token  -UseBasicParsing
    

    If it returns any error, refer to Troubleshooting

Use workload identity federation for GKE from your code

Authenticating to Google Cloud services from your code is the same process as authenticating using the Compute Engine metadata server. When you use workload identity federation for GKE, your requests to the instance metadata server are routed to the GKE metadata server. Existing code that authenticates using the instance metadata server (like code using the Google 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 quota from a different Google Cloud project when making calls to the GenerateAccessToken and the GenerateIdToken methods in the IAM Service Account Credentials API. This lets you avoid using the entire quota in your main project, and instead use quota from other projects for these services in your cluster.

To configure a quota project with workload identity federation for GKE, do the following:

  1. Grant the serviceusage.services.use permission on the quota project to the Kubernetes service account.

    gcloud projects add-iam-policy-binding \
    --role=roles/serviceusage.serviceUsageConsumer \
    --member=serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME] \
    QUOTA_PROJECT_ID
    

    Replace QUOTA_PROJECT_ID with the project ID of the quota project.

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

    kubectl annotate serviceaccount KSA_NAME \
    --namespace NAMESPACE \
    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 by following the instructions in Verify the workload identity federation for GKE setup.

  2. Make a service account token request:

    curl -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token
    
  3. Go to the IAM Service Accounts Credentials API page in 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 IAM service account and disable workload identity federation for GKE on the cluster.

Revoke access

  1. Revoke access to the IAM service account:

    gcloud

    1. In the Google Cloud console, activate Cloud Shell.

      Activate Cloud Shell

      At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    2. In your development environment, run the following command:

      gcloud iam service-accounts remove-iam-policy-binding GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com \
          --role roles/iam.workloadIdentityUser \
          --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"
      

      Replace the following:

      • PROJECT_ID: the project ID of the GKE cluster.
      • NAMESPACE: the name of the Kubernetes namespace where your Kubernetes service account is located.
      • KSA_NAME: the name of the Kubernetes service account that will have its access revoked.
      • GSA_NAME: the name of the IAM service account.
      • GSA_PROJECT: the project ID of the IAM service account.

    Config Connector

    If you used Config Connector to create the service account, delete the service account with kubectl.

    kubectl delete -f service-account.yaml
    

    It can take up to 30 minutes for cached tokens to expire. You can check whether the cached tokens have expired with this command:

    gcloud auth list
    

    The cached tokens have expired if the output of that command no longer includes GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com.

  2. Remove the annotation from the Kubernetes service account. This step is optional because access has been revoked by IAM.

    kubectl annotate serviceaccount KSA_NAME \
        --namespace NAMESPACE iam.gke.io/gcp-service-account-
    

Disable workload identity federation for GKE

You can only disable workload identity federation for GKE on GKE Standard clusters.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Disable workload identity federation for GKE on each node pool:

    gcloud container node-pools update NODEPOOL_NAME \
        --cluster=CLUSTER_NAME \
        --workload-metadata=GCE_METADATA
    

    Repeat this command for every node pool in the cluster.

  3. Disable workload identity federation for GKE in the cluster:

    gcloud container clusters update CLUSTER_NAME \
        --disable-workload-identity
    

Console

  1. Go to the Google Kubernetes Engine page in Google Cloud console.

    Go to Google Kubernetes Engine

  2. In the cluster list, click the name of the cluster that you want to modify.

  3. Click the Nodes tab.

  4. To disable workload identity federation for GKE on each node pool, do the following for each node pool in the Node Pools section:

    1. Click the name of the node pool that you want to modify.
    2. On the Node pool details page, click Edit.
    3. On the Edit node pool page, in the Security section, clear the Enable GKE Metadata Server checkbox.
    4. Click Save.
  5. To disable workload identity federation for GKE for the cluster, do the following:

    1. Click the Details tab.
    2. In the Security section, next to Workload Identity, click Edit.
    3. In the Edit Workload Identity dialog, clear the Enable Workload Identity checkbox.
    4. Click Save changes.

Disable workload identity federation for GKE in your organization

From a security perspective, workload identity federation for GKE allows GKE to assert Kubernetes service account identities that can be authenticated and authorized to Google Cloud resources. If you are an administrator who has taken actions to isolate workloads from Google Cloud resources, like disabling service account creation or disabling service account key creation, you might also want to disable workload identity federation for GKE for your organization.

See these instructions for disabling workload identity federation for GKE for your organization.

Troubleshooting

For troubleshooting information, refer to Troubleshooting workload identity federation for GKE.

What's next