# Configuring Workload Identity for Secure GKE Access to Google Cloud Services > Securely access Google Cloud services from GKE using Workload Identity. Learn how to link Kubernetes and Google service accounts for keyless authentication. - Repository: [Google/skills](https://github.com/google/skills) - Tags: how-to-guide - Published: 2026-08-09 --- **Workload Identity is the recommended, key-less authentication method that links a Kubernetes Service Account (KSA) to a Google Service Account (GSA) via IAM bindings, enabling GKE pods to obtain short-lived OIDC tokens without storing service account keys inside the cluster.** Configuring Workload Identity for secure GKE access to Google Cloud services eliminates the operational burden of managing JSON key files while enforcing least-privilege access controls. This implementation guide references the `google/skills` repository—specifically [`skills/cloud/gke-workload-security/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gke-workload-security/SKILL.md) and its associated assets—to demonstrate how to map Kubernetes identities to Google Cloud IAM. The result is a secure, auditable authentication flow where workloads automatically impersonate GSAs through the GKE metadata server. ## How Workload Identity Works Workload Identity operates through a trust delegation chain between Kubernetes and Google Cloud IAM. When enabled, the **GKE metadata server** signs an OIDC token containing the KSA’s identity and exchanges it for a short-lived Google access token scoped to the GSA’s permissions. The architecture relies on four core components: - **Kubernetes Service Account (KSA)** – The identity assigned to a pod, defined within a specific namespace. - **Google Service Account (GSA)** – The IAM identity that holds permissions for Google Cloud APIs (e.g., `roles/storage.objectViewer`). - **Workload Identity Binding** – An IAM policy binding that grants the KSA permission to impersonate the GSA using `roles/iam.workloadIdentityUser`. - **Pod Annotation** – The `iam.gke.io/gcp-service-account` annotation on the KSA tells the GKE runtime which GSA to assume. When a pod starts, the GKE node-level metadata server automatically injects the token exchange mechanism. The pod can then call Cloud Storage, Pub/Sub, or other Google Cloud APIs as if it were the GSA, completely eliminating the risk of credential leakage from stored key files. ## Step-by-Step Configuration The following commands configure Workload Identity for a namespace called `workload-identity-test-ns`, mirroring the workflow documented in the skill definition. ### Create the Namespace and KSA First, create a dedicated namespace and Kubernetes Service Account: ```bash kubectl create namespace workload-identity-test-ns kubectl create serviceaccount my-ksa \ --namespace workload-identity-test-ns ``` ### Configure the IAM Binding Bind the KSA to your GSA using the `roles/iam.workloadIdentityUser` role. The member identifier follows the format `serviceAccount:.svc.id.goog[/]`: ```bash 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]" ``` Replace `my-gsa`, `my-project`, and the namespace values with your specific identifiers. ### Annotate the Service Account Add the `iam.gke.io/gcp-service-account` annotation to link the KSA to the GSA email address: ```bash 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 Test Workload The `google/skills` repository provides a sample pod manifest at [`skills/cloud/gke-workload-security/assets/workload-identity-pod.yaml`](https://github.com/google/skills/blob/main/skills/cloud/gke-workload-security/assets/workload-identity-pod.yaml). Update the placeholder and apply it: ```bash sed -i 's//my-ksa/g' assets/workload-identity-pod.yaml kubectl apply -f assets/workload-identity-pod.yaml -n workload-identity-test-ns ``` This manifest references the annotated KSA, allowing the pod to assume the GSA’s identity upon startup. ### Verify Authentication Inside the Pod Confirm that Workload Identity is functioning by querying the metadata server for the active service account email: ```bash kubectl exec -n workload-identity-test-ns -it my-pod -- curl -H "Metadata-Flavor: Google" \ http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/email ``` The command should return `my-gsa@my-project.iam.gserviceaccount.com`, verifying that the pod is successfully impersonating the GSA. ## Security Benefits Implementing Workload Identity provides four critical security advantages over traditional service account keys: - **Zero-secret authentication** – No JSON key files exist inside the cluster to be leaked or exposed in logs. - **Principle of least privilege** – Each workload receives only the specific IAM roles required for its function. - **Auditability** – All API calls are logged against the GSA in Cloud IAM logs, creating a clear audit trail. - **Automatic token rotation** – The GKE metadata server manages short-lived OIDC tokens and handles rotation without application intervention. ## Repository Resources and Audit Tools The `google/skills` repository contains three essential files for implementing and validating Workload Identity: - **[`skills/cloud/gke-workload-security/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gke-workload-security/SKILL.md)** – The primary skill definition explaining architecture, configuration steps, and best practices. - **[`skills/cloud/gke-workload-security/assets/workload-identity-pod.yaml`](https://github.com/google/skills/blob/main/skills/cloud/gke-workload-security/assets/workload-identity-pod.yaml)** – A minimal pod manifest template used to test Workload Identity bindings. - **[`skills/cloud/gke-workload-security/scripts/audit_cluster.sh`](https://github.com/google/skills/blob/main/skills/cloud/gke-workload-security/scripts/audit_cluster.sh)** – A helper script to audit GKE clusters for Workload Identity configuration and other security controls. These resources provide a complete, repeatable workflow for securing service-to-service authentication on GKE. ## Summary - Workload Identity enables **key-less authentication** by linking KSAs to GSAs through the `roles/iam.workloadIdentityUser` IAM binding. - Configuration requires creating a KSA, establishing an IAM policy binding with the specific member format `serviceAccount:.svc.id.goog[/]`, and annotating the KSA with `iam.gke.io/gcp-service-account`. - Pods receive short-lived OIDC tokens from the GKE metadata server, which are exchanged for Google Cloud credentials automatically. - The `google/skills` repository provides ready-to-use manifests in `skills/cloud/gke-workload-security/assets/` and audit scripts in `skills/cloud/gke-workload-security/scripts/` to streamline implementation. ## Frequently Asked Questions ### What IAM role enables a KSA to impersonate a GSA? The `roles/iam.workloadIdentityUser` role must be granted on the GSA with a member identifier specifying the KSA in the format `serviceAccount:.svc.id.goog[/]`. This binding authorizes the specific Kubernetes service account to obtain tokens for the Google service account. ### How do pods access Google Cloud APIs without service account keys? Pods request an OIDC token from the GKE metadata server at `http://metadata.google.internal`. The metadata server validates the pod’s KSA against the IAM binding and exchanges the OIDC token for a short-lived Google access token. The application receives this token transparently through the standard Google Cloud client libraries. ### Where can I find sample manifests to test this configuration? Sample manifests are located in the `google/skills` repository at [`skills/cloud/gke-workload-security/assets/workload-identity-pod.yaml`](https://github.com/google/skills/blob/main/skills/cloud/gke-workload-security/assets/workload-identity-pod.yaml). This file contains a minimal pod specification that references an annotated KSA, allowing you to validate that Workload Identity is configured correctly before deploying production workloads. ### What annotation is required on the Kubernetes Service Account? You must annotate the KSA with `iam.gke.io/gcp-service-account=` where `` is the full address of the Google Service Account (e.g., `my-gsa@my-project.iam.gserviceaccount.com`). This annotation signals to the GKE runtime which GSA identity the pod should assume.