How to Configure Workload Identity for GKE: Complete Implementation Guide

To configure Workload Identity for GKE, create a Kubernetes Service Account (KSA), bind it to a Google Service Account (GSA) using the roles/iam.workloadIdentityUser role, and annotate the KSA with the iam.gke.io/gcp-service-account annotation to establish a secure, credential-free authentication flow.

Workload Identity allows workloads running on Google Kubernetes Engine to securely access Google Cloud APIs without managing service account keys. According to the google/skills repository, this approach leverages the GKE metadata server to exchange Kubernetes service account tokens for short-lived Google access tokens, eliminating the security risks associated with long-lived JSON keys.

Prerequisites for Workload Identity

Before configuring Workload Identity, verify that your GKE cluster has Workload Identity enabled at the node pool level. This requires GKE version 1.12 or later and specific node metadata configurations. The detailed prerequisite checklist is documented in skills/cloud/gke-workload-security/SKILL.md.

Step 1: Create a Namespace and Kubernetes Service Account

First, isolate your workload by creating a dedicated namespace and Kubernetes Service Account (KSA). This KSA represents the workload identity inside the cluster.

# Create the namespace

kubectl create namespace workload-identity-test-ns

# Create the Kubernetes Service Account

kubectl create serviceaccount my-ksa \
    --namespace workload-identity-test-ns

Step 2: Bind the KSA to a Google Service Account

Establish the trust relationship by granting the KSA permission to impersonate a Google Service Account (GSA). Use gcloud to add an IAM policy binding with the specific serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME] member format.

gcloud iam service-accounts add-iam-policy-binding \
    my-gsa@my-project.iam.gserviceaccount.com \
    --role roles/iam.workloadIdentityUser \
    --member "serviceAccount:my-project.svc.id.goog[workload-identity-test-ns/my-ksa]"

This binding grants the specific KSA the roles/iam.workloadIdentityUser role on the target GSA, allowing token exchange through the GKE metadata server.

Step 3: Annotate the KSA with the GSA Email

Link the KSA to the specific GSA by adding the iam.gke.io/gcp-service-account annotation. This tells the GKE metadata server which Google Service Account to exchange tokens for when pods use this KSA.

kubectl annotate serviceaccount my-ksa \
    --namespace workload-identity-test-ns \
    iam.gke.io/gcp-service-account=my-gsa@my-project.iam.gserviceaccount.com

Deploy a Pod to Verify the Configuration

After completing the three configuration steps, deploy a pod that uses the configured KSA to verify that Workload Identity functions correctly. The google/skills repository provides a reference implementation in skills/cloud/gke-workload-security/assets/workload-identity-pod.yaml.

apiVersion: v1
kind: Pod
metadata:
  name: workload-identity-test
  namespace: workload-identity-test-ns
spec:
  serviceAccountName: my-ksa
  automountServiceAccountToken: false
  containers:
  - name: workload-identity-test
    image: gcr.io/google.com/cloudsdktool/cloud-sdk
    command: ["sleep", "infinity"]
  nodeSelector:
    iam.gke.io/gke-metadata-server-enabled: "true"
  securityContext:
    runAsNonRoot: true
    runAsUser: 65532
    seccompProfile:
      type: RuntimeDefault

The nodeSelector ensures the pod schedules on nodes where the GKE metadata server is enabled, which is required for Workload Identity token exchange. Once running, the pod automatically obtains short-lived access tokens for the associated GSA without embedded credentials.

Summary

• Create isolation: Define a dedicated namespace and Kubernetes Service Account for your workload.
• Establish trust: Bind the KSA to a GSA using the roles/iam.workloadIdentityUser role with the specific member identifier serviceAccount:PROJECT.svc.id.goog[NAMESPACE/SERVICE_ACCOUNT].
• Configure metadata: Apply the iam.gke.io/gcp-service-account annotation to the KSA to map it to the target GSA email.
• Deploy safely: Use node selectors that target metadata-server-enabled nodes and reference the example manifests in skills/cloud/gke-workload-security/assets/ for validation.

Frequently Asked Questions

What is the difference between Workload Identity and downloading service account keys?

Workload Identity eliminates the need to store and manage JSON key files within your cluster. Instead of embedding long-lived credentials in secrets, Workload Identity uses the GKE metadata server to exchange Kubernetes service account tokens for short-lived Google access tokens automatically. This approach follows the principle of using short-lived credentials and removes the security risks associated with key leakage or rotation.

Why does my pod need the iam.gke.io/gke-metadata-server-enabled node selector?

The node selector ensures pods schedule on node pools where Workload Identity is enabled. GKE implements Workload Identity through a metadata server that intercepts token requests. Nodes must have this metadata server running to facilitate the exchange between Kubernetes service account tokens and Google Cloud access tokens. Without this selector, pods may land on incompatible nodes where authentication will fail.

Can multiple KSAs impersonate the same GSA?

Yes, multiple Kubernetes Service Accounts can impersonate a single Google Service Account. Each KSA requires its own IAM binding with the roles/iam.workloadIdentityUser role, specifying the unique member identifier for that specific namespace and service account combination. This pattern is useful when multiple microservices require identical cloud permissions but maintain separate Kubernetes identities for audit and isolation purposes.

What happens if I omit the iam.gke.io/gcp-service-account annotation?

The pod will authenticate using the underlying node's service account instead of the intended GSA. Without this annotation, the GKE metadata server does not know which Google Service Account to exchange tokens for, causing the workload to fall back to the Compute Engine default service account or fail authentication if the node uses a restricted service account. The annotation is the critical link that maps the KSA to the specific GSA.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}