Workload Identity for GKE Explained: Secure Keyless Access to Google Cloud APIs

The simple explanation

Think of Workload Identity as a badge system for pods.

Without it, every pod that needs to call a Google Cloud API must carry a credential — usually a JSON key file that acts like a permanent password. If that file is copied, leaked, or committed to a repo, it works forever and from anywhere on the internet.

With Workload Identity, pods carry no credential at all. Instead, when a pod needs a token, GKE vouches for it. It says: “This pod is running as Kubernetes ServiceAccount my-app-ksa in the production namespace, and I trust it to act as Google service account my-app-gsa@my-project-id.iam.gserviceaccount.com.” Google’s infrastructure checks that trust relationship and issues a short-lived token, valid for one hour, then discards it.

The three pieces involved:

• Kubernetes ServiceAccount (KSA): a namespaced Kubernetes resource that provides an identity to pods. Every pod runs as a KSA. If you do not specify one, it uses the default KSA in its namespace.
• Google service account (GSA): a GCP IAM identity with its own set of permissions. This is the account whose credentials the pod will receive.
• Short-lived token: a Google OAuth access token, valid for one hour, issued automatically by the GKE metadata server via Google’s Security Token Service. The pod never sees or stores a private key.

The pod does not carry a key. It has an identity. GKE and GCP together convert that identity into a usable credential, automatically, every time the pod needs one.

What is Workload Identity for GKE?

Workload Identity for GKE is a GCP feature that creates a trusted, explicit mapping between a Kubernetes ServiceAccount and a Google Cloud IAM service account. Once configured, any pod that runs under the annotated KSA automatically obtains credentials for the linked GSA: no key file, no manual credential rotation, and no changes to application code.

It sits at the intersection of Kubernetes identity and Google Cloud IAM. The KSA is a Kubernetes-native concept; the GSA belongs to GCP’s IAM system. Workload Identity creates a bridge between the two, allowing the cluster to act on behalf of a specific GCP identity in a controlled, auditable way.

Applications running in GKE pods typically access Google Cloud using the official client libraries. These libraries use Application Default Credentials (ADC), which automatically discover credentials from the environment. When running inside a GKE pod with Workload Identity configured, ADC queries the GKE metadata server and receives the token for the linked GSA with zero changes to the application itself.

This is the recommended approach for any GKE workload that needs to call Google Cloud APIs. The securing GKE clusters page covers how Workload Identity fits into the broader GKE security model.

Why Workload Identity matters

The core problem it solves is the service account key file. Understanding why key files are dangerous makes it clear why Workload Identity is the right replacement.

Key files spread silently#

Once you create a key file, it tends to multiply. It lands in a Kubernetes Secret. It gets copied into a CI/CD variable store. It gets embedded in a Docker image during a rushed build. It ends up committed to a repo. Each copy is a separate exposure surface, and most teams cannot reliably track how many copies exist.

Kubernetes Secrets are not encrypted by default#

Storing a key file in a Kubernetes Secret does not encrypt it. It base64-encodes it. Anyone with access to etcd, or with sufficient RBAC permissions, can retrieve the raw value. See managing secrets in Kubernetes for the full picture.

Blast radius is unbounded#

A single leaked key grants all the permissions of that service account to anyone in possession of it, from any network, at any time. There is no automatic expiry and no inherent scope limit.

What Workload Identity gives you instead#

For a deeper look at why key files are risky, read why service account keys are dangerous.

Workload Identity vs service account keys

This is one of the most common decisions teams face when building on GKE. The table below captures the key differences:

If you have existing workloads using key files, replacing them with Workload Identity is one of the highest-value security improvements you can make. The service account keys explained page covers the full lifecycle and risks.

How Workload Identity works

Here is the sequence of events when a pod calls a Google Cloud API using Workload Identity:

1. Pod starts under a Kubernetes ServiceAccount (KSA) that has been annotated with a GSA email.
2. Pod calls the metadata server at 169.254.169.254 (or metadata.google.internal). This happens automatically when the application uses a Google Cloud client library via ADC. No explicit code is needed.
3. GKE metadata server intercepts the request. Each node runs a metadata server DaemonSet (enabled with --workload-metadata=GKE_METADATA on the node pool). It identifies the pod’s KSA from the Kubernetes API.
4. The metadata server calls Google’s Security Token Service (STS). It presents the pod’s KSA identity token and requests a Google OAuth access token for the linked GSA.
5. STS validates the binding. It checks that the KSA has the annotation pointing to the GSA, and that the GSA has an IAM binding granting roles/iam.workloadIdentityUser to the KSA’s workload identity principal. Both must be in place.
6. A short-lived token is returned. Valid for one hour, scoped to the GSA’s permissions. The token is returned to the application via the metadata server response.
7. Application uses the token. The client library uses it to authenticate API calls. The token is refreshed automatically before it expires.

The two required conditions for this to work:

• The KSA must be annotated with iam.gke.io/gcp-service-account: GSA_EMAIL
• The GSA must have an IAM binding granting roles/iam.workloadIdentityUser to serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]

Either condition alone is not enough. Both must be in place before token exchange works.

When to use Workload Identity

Use Workload Identity for any GKE workload that needs to call a Google Cloud API. Some realistic examples:

• A web service reading user files from Cloud Storage. The pod needs roles/storage.objectViewer on the relevant bucket.
• A background worker publishing events to Pub/Sub. The pod needs roles/pubsub.publisher on the specific topic.
• An application reading secrets at startup from Secret Manager. The pod needs roles/secretmanager.secretAccessor on specific secret versions. See managing secrets in Kubernetes.
• A batch job querying BigQuery. The pod needs roles/bigquery.dataViewer and roles/bigquery.jobUser.
• A service writing structured logs to Cloud Logging. The pod needs roles/logging.logWriter.

In all of these cases, the pod needs a Google Cloud identity. Workload Identity is the right way to provide one.

For workloads running outside GKE that need Google Cloud access, such as CI/CD pipelines or external systems, see Workload Identity Federation, which extends the same keyless principle to non-GCP environments.

Step-by-step setup

The following steps configure Workload Identity for a single workload. All values use my-project-id, my-cluster, my-app-gsa, my-app-ksa, and the production namespace as consistent examples throughout.

Step 1: Enable Workload Identity on the cluster#

Pass --workload-pool when creating a new cluster. The workload pool identifier is always PROJECT_ID.svc.id.goog:

gcloud container clusters create my-cluster \
  --region=europe-west2 \
  --workload-pool=my-project-id.svc.id.goog

To enable Workload Identity on an existing cluster:

gcloud container clusters update my-cluster \
  --region=europe-west2 \
  --workload-pool=my-project-id.svc.id.goog

Step 2: Update the node pool metadata mode#

The GKE metadata server must run on every node. On Standard clusters, this requires setting the metadata mode to GKE_METADATA on each node pool:

gcloud container node-pools update default-pool \
  --cluster=my-cluster \
  --region=europe-west2 \
  --workload-metadata=GKE_METADATA

Step 3: Create the Google service account (GSA)#

This is the GCP identity whose permissions the pod will use:

gcloud iam service-accounts create my-app-gsa \
  --display-name="My Application GSA" \
  --project=my-project-id

Step 4: Grant the GSA the required IAM roles#

Grant the narrowest set of permissions the workload actually needs. For example, read access to a specific Cloud Storage bucket:

gcloud storage buckets add-iam-policy-binding gs://my-data-bucket \
  --member="serviceAccount:my-app-gsa@my-project-id.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

Do not grant broad roles like roles/editor or roles/storage.admin unless the workload genuinely requires that scope. See principle of least privilege.

Step 5: Create the Kubernetes ServiceAccount (KSA)#

Create the KSA in the correct namespace. The namespace matters because it is part of the workload identity principal used in the IAM binding:

kubectl create serviceaccount my-app-ksa \
  --namespace=production

Or declare it in YAML for version control:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-app-ksa
  namespace: production

Step 6: Annotate the KSA with the GSA email#

The annotation tells GKE which GSA this KSA should map to:

kubectl annotate serviceaccount my-app-ksa \
  --namespace=production \
  iam.gke.io/gcp-service-account=my-app-gsa@my-project-id.iam.gserviceaccount.com

Or declare this in the YAML manifest:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-app-ksa
  namespace: production
  annotations:
    iam.gke.io/gcp-service-account: my-app-gsa@my-project-id.iam.gserviceaccount.com

The annotation alone is not sufficient. The IAM binding in the next step is also required.

Step 7: Grant roles/iam.workloadIdentityUser on the GSA#

This IAM binding tells GCP to trust the Kubernetes ServiceAccount as an authorised impersonator of the GSA:

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

The --member format is always:

serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]

Every part of this string matters. Getting the project ID, namespace, or KSA name wrong means the binding does not match and token exchange fails. See service account impersonation for how impersonation works more broadly in GCP.

Step 8: Reference the KSA in your Deployment#

Specify serviceAccountName in the pod spec. Without this, the pod runs under the default KSA and Workload Identity does not apply:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: production
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      serviceAccountName: my-app-ksa
      containers:
        - name: app
          image: europe-west2-docker.pkg.dev/my-project-id/my-repo/my-app:latest

See Deployments in Kubernetes for a full reference on Deployment configuration.

Step 9: Verify from inside a pod#

Run a temporary pod under the KSA and confirm the identity is working:

kubectl run -it --rm workload-identity-test \
  --image=google/cloud-sdk:slim \
  --namespace=production \
  --overrides='{"spec": {"serviceAccountName": "my-app-ksa"}}' \
  -- bash

Inside the pod:

# Should show the GSA email as the active identity
gcloud auth list

# Call the metadata server directly to confirm the email
curl -s -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/email"

If configured correctly, both commands return my-app-gsa@my-project-id.iam.gserviceaccount.com.

Common mistakes

Troubleshooting

Workload Identity and OAuth scopes

Node pools created before Workload Identity was common often have restrictive OAuth scopes, for example storage-ro or compute-rw. When using Workload Identity, the node’s OAuth scopes no longer limit what the GSA can do.

Here is why: when a pod uses Workload Identity, the token it receives is issued by Google’s Security Token Service for the GSA specifically. It is not a node token with scoped-down access. It is a service account token. The effective permissions of that token are determined entirely by the IAM roles granted to the GSA, not by the node pool’s OAuth scopes.

This means you can grant a GSA very narrow permissions — say, only roles/pubsub.publisher on a specific topic — and the pod has exactly that capability and nothing else, regardless of what OAuth scopes the node pool was created with. IAM on the GSA is the single authoritative source of truth for what the pod can do.

Best practices

• One KSA per workload or trust boundary. Do not share a KSA across unrelated deployments. If two services have different access requirements, they need different KSAs and different GSAs.
• One narrowly scoped GSA per workload. Create a dedicated GSA for each application with only the IAM roles it genuinely needs. Avoid reusing GSAs across workloads.
• Grant minimal IAM roles. Prefer resource-level bindings (on a specific bucket or topic) over project-level bindings where possible. Review and remove roles that are no longer needed.
• Version-control your KSA manifests. Declare Kubernetes ServiceAccounts in YAML with the annotation included and commit them to your repository. This makes the binding explicit and reviewable.
• Do not annotate the default KSA. Annotating the default KSA in a namespace effectively grants Workload Identity credentials to any pod that does not specify a serviceAccountName, which is the opposite of least privilege.
• Verify Workload Identity in each environment. Run the metadata server verification step in staging before promoting to production. A misconfigured binding fails silently until a pod tries to call an API.
• Do not mix key-based auth and Workload Identity. Once a workload uses Workload Identity, remove any key files from Kubernetes Secrets in that namespace. Mixing the two patterns creates confusion about which credential is actually being used.

For managing service accounts more broadly, including creation, lifecycle, and IAM assignments, see the fundamentals page.