How to Use Workload Identity in GCP: Simple Guide

Use Workload Identity in GCP by linking a Kubernetes service account to a Google service account. This lets your workloads access Google Cloud resources securely without storing keys.

Syntax

Workload Identity connects a Kubernetes service account (KSA) with a Google Cloud service account (GSA) using an IAM policy binding. The main commands are:

• gcloud iam service-accounts add-iam-policy-binding: Grants the KSA permission to impersonate the GSA.
• kubectl annotate serviceaccount: Links the KSA to the GSA.

This setup allows pods using the KSA to authenticate as the GSA.

bash

gcloud iam service-accounts add-iam-policy-binding [GSA_EMAIL] \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:[PROJECT_ID].svc.id.goog[[NAMESPACE]/[KSA]]"

kubectl annotate serviceaccount [KSA] \
  --namespace [NAMESPACE] \
  iam.gke.io/gcp-service-account=[GSA_EMAIL]

Example

This example shows how to allow a Kubernetes service account named my-ksa in namespace default to impersonate a Google service account [e-mail]. This enables pods using my-ksa to access Google Cloud APIs securely.

bash

PROJECT_ID="my-project"
NAMESPACE="default"
KSA="my-ksa"
GSA="my-gsa@${PROJECT_ID}.iam.gserviceaccount.com"

# Allow KSA to impersonate GSA

gcloud iam service-accounts add-iam-policy-binding $GSA \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:${PROJECT_ID}.svc.id.goog[${NAMESPACE}/${KSA}]"

# Annotate KSA with GSA email

kubectl annotate serviceaccount $KSA \
  --namespace $NAMESPACE \
  iam.gke.io/gcp-service-account=$GSA

# Now pods using $KSA can access GCP resources as $GSA

Output

Updated IAM policy for service account [[e-mail]].
serviceaccount/my-ksa annotated

Common Pitfalls

• Missing IAM binding: Forgetting to grant roles/iam.workloadIdentityUser to the Kubernetes service account blocks authentication.
• Incorrect annotation: Wrong namespace or service account name in the annotation causes failure.
• Using legacy keys: Workload Identity removes the need for JSON keys; using keys defeats its purpose.
• Namespace mismatch: The namespace in the IAM member and annotation must match the Kubernetes namespace.

bash

### Wrong: Missing IAM binding
kubectl annotate serviceaccount my-ksa --namespace default iam.gke.io/gcp-service-account=[e-mail]

### Right: Add IAM binding first

gcloud iam service-accounts add-iam-policy-binding [e-mail] \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:my-project.svc.id.goog[default/my-ksa]"

kubectl annotate serviceaccount my-ksa --namespace default iam.gke.io/gcp-service-account=[e-mail]

Quick Reference

Remember these key points when using Workload Identity:

• Link Kubernetes service accounts to Google service accounts with IAM bindings and annotations.
• Use roles/iam.workloadIdentityUser role for permission.
• Ensure namespaces and service account names match exactly.
• Do not use JSON keys; Workload Identity handles authentication securely.

Key Takeaways

Workload Identity links Kubernetes and Google service accounts for secure access without keys.

Always grant the IAM role roles/iam.workloadIdentityUser to the Kubernetes service account.

Annotate the Kubernetes service account with the Google service account email correctly.

Ensure namespace and service account names match in both IAM binding and annotation.

Avoid using JSON keys; Workload Identity provides safer authentication.