GKE Workload Identity is the recommended way to give a Kubernetes pod access to Google Cloud services without exporting a service account key. The old approach — downloading a JSON key, storing it as a Kubernetes Secret, and mounting it into every pod — creates a long-lived credential that can be copied, leaked, and forgotten. GKE Workload Identity replaces that key with federation: a Kubernetes service account is linked to a Google Cloud service account, and the pod receives short-lived tokens that Google Cloud trusts because GKE vouches for the pod identity.
This guide walks through enabling GKE Workload Identity on a cluster, creating the two service accounts, binding them together, and running a pod that can call Google Cloud APIs with no key file. The examples use the Google Cloud CLI and assume you have a GKE cluster, a project with the required APIs enabled, and permission to manage IAM bindings.
Prerequisites for GKE Workload Identity
You need a GKE cluster running a supported version, the gcloud CLI authenticated to your project, and kubectl configured for the cluster. Workload Identity Federation must be enabled on the cluster; on Autopilot clusters it is enabled by default, while on Standard clusters you enable it when creating the cluster or update an existing cluster to enable it. You also need a Google Cloud service account that will hold the actual permissions, such as read access to a Cloud Storage bucket.
Before you start, decide on the least-privilege permissions the workload needs. Workload Identity does not change IAM best practice; it only changes how the pod proves who it is. Grant the Google service account only the roles the pod needs, and grant the Kubernetes service account binding only to the namespace and service account that should use it. A broad binding defeats the purpose of the federation.
Step 1: Enable GKE Workload Identity on the Cluster
For a new Standard cluster, enable Workload Identity at creation time. For an existing cluster, update it with the gcloud container clusters update command and the workload pool flag, which is derived from your project ID. After the update, node pools are recreated, so plan the change during a maintenance window if the cluster runs production workloads.
gcloud container clusters update my-cluster --zone us-central1-a --workload-pool=PROJECT_ID.svc.id.goog
Verify the setting with gcloud container clusters describe my-cluster --zone us-central1-a and look for the workload identity configuration. If the workload pool is missing, the cluster update did not apply, and pods will fall back to node service account credentials, which is a different and broader identity. Do not proceed to the binding step until the pool is present.
Step 2: Create and Bind the Two Service Accounts
Create a Kubernetes service account in the application namespace and annotate it with the email of the Google service account. The annotation is the link that tells GKE which Google identity this Kubernetes identity should federate to. Create the Google service account separately, grant it the IAM roles the workload needs, and then allow the Kubernetes service account to impersonate it.
kubectl create serviceaccount app-sa --namespace app
kubectl annotate serviceaccount app-sa --namespace app iam.gke.io/gcp-service-account=app-gsa@PROJECT_ID.iam.gserviceaccount.com
gcloud iam service-accounts add-iam-policy-binding app-gsa@PROJECT_ID.iam.gserviceaccount.com --role roles/iam.workloadIdentityUser --member "serviceAccount:PROJECT_ID.svc.id.goog[app/app-sa]"

The member string format matters: it is serviceAccount:PROJECT_ID.svc.id.goog[namespace/kubernetes-service-account]. A typo in the namespace or service account name produces a silent failure where the pod runs but Google Cloud rejects its token, so copy the namespace and name exactly. Replace PROJECT_ID with your real project ID in every command.
Step 3: Run a Pod with GKE Workload Identity
Deploy a pod that uses the Kubernetes service account and does not mount any key file. The pod’s Google Cloud client libraries automatically use the federated token when they run on GKE with Workload Identity enabled. The deployment below is minimal; your real workload would add the container image and command that actually calls a Google Cloud API.
apiVersion: apps/v1
kind: Deployment
metadata:
name: app
namespace: app
spec:
replicas: 1
selector:
matchLabels:
app: app
template:
metadata:
labels:
app: app
spec:
serviceAccountName: app-sa
containers:
- name: app
image: google/cloud-sdk:slim
command: ["sleep", "3600"]
Test the identity from inside the pod with kubectl exec -n app deploy/app -- gcloud auth list or by running a simple Storage command, such as listing a bucket the Google service account can read. If the command succeeds with no key file present, Workload Identity is working. If it fails with a permission error, check the IAM roles on the Google service account first, then the binding, then the cluster workload pool setting.
Troubleshooting GKE Workload Identity
The most common failure is a pod that authenticates as the node service account instead of the workload identity. That happens when the workload pool is not enabled, when the pod does not specify the annotated Kubernetes service account, or when the pod runs in a namespace other than the one in the binding. Check the pod spec for serviceAccountName, check the annotation on that service account, and check that the binding member string matches exactly.
Another common failure is a token that is issued but rejected by the target service. That usually means the Google service account lacks the role for that service, or the role was granted on the wrong project or bucket. Use the IAM policy troubleshooter in the Google Cloud console to test whether the Google service account has the permission, because that separates an IAM problem from a federation problem.
For related Google Cloud topics, see our guides to GKE Autopilot versus Standard mode and Artifact Registry for Docker images. The official reference is the GKE Workload Identity documentation.
Conclusion
GKE Workload Identity removes the most dangerous credential in many Kubernetes setups: the exported service account key. Enable the workload pool, annotate the Kubernetes service account, bind it to a least-privilege Google service account, and test from inside a pod. Once that pattern is standard, no workload should ever need a JSON key mounted as a Secret again.