Configuring Workload Identity for Secure GKE Access to Google Cloud Services

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 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:

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:<project>.svc.id.goog[<namespace>/<ksa-name>]:

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:

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. Update the placeholder and apply it:

sed -i 's/<ksa-name>/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:

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 – The primary skill definition explaining architecture, configuration steps, and best practices.
• 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 – 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:<project>.svc.id.goog[<namespace>/<ksa-name>], 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:<project>.svc.id.goog[<namespace>/<ksa-name>]. 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. 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=<gsa-email> where <gsa-email> 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.

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