Start with the Pod's identity
Workload Identity Federation for GKE lets a Kubernetes workload obtain short-lived credentials for Google Cloud APIs. The important starting point is the Kubernetes ServiceAccount assigned to the Pod. That identity includes its namespace and project workload pool context; it is not simply the IAM service account attached to the underlying node.
GKE supports granting a workload principal access directly where the target service supports it. An alternative links the Kubernetes identity to an IAM service account for impersonation. Choose the supported pattern for the target API and document it. Mixing instructions from both patterns can create a configuration that looks plausible but never produces the intended principal.
Prepare a test namespace, a minimally privileged test resource, and read access to cluster, node pool, Kubernetes ServiceAccount, and resource IAM configuration. Confirm whether the cluster mode enables the required metadata path automatically or needs node-pool configuration. Use Application Default Credentials in the workload rather than distributing a downloaded service-account key.
Follow the identity chain
- Read the running Pod with
kubectl get pod POD -n NAMESPACE -o yaml. CheckserviceAccountName, namespace, node placement, andhostNetwork. Compare these with the deployment manifest. A correctly configured ServiceAccount does nothing for a Pod that still uses another account. - Inspect the cluster with
gcloud container clusters describe CLUSTER --project=PROJECT_ID --location=LOCATION. For Standard clusters, check the relevant node pool's workload metadata configuration. Confirm that the Pod is on a node providing the intended GKE metadata service. - Match the resource IAM binding to the exact workload principal. Direct principal identifiers include the project number and workload pool, namespace, and ServiceAccount name. For an impersonation pattern, verify both the Kubernetes-to-IAM linkage and the IAM service account's resource permissions.
- Make a harmless API read from a test Pod using the same workload identity and supported client library. Inspect the audit evidence at the resource when available. If a NetworkPolicy blocks the metadata path, use the documented address and port for the actual dataplane rather than allowing broad egress.
Illustrative scenario
A fictional reconciliation Deployment is moved into a new namespace. The Kubernetes ServiceAccount has the same short name, but the resource IAM binding still names the old namespace. Token acquisition can succeed while resource access fails because the resulting principal is different. The operator updates the narrowly scoped binding after confirming the namespace migration, instead of granting the node broad access.
| Symptom | Boundary to inspect | Corrective direction |
|---|---|---|
| Application gets resource permission denied | Exact workload principal and target IAM | Bind the intended namespace identity |
| Metadata requests fail | Node configuration and NetworkPolicy | Restore the supported metadata path |
| Container image cannot be pulled | Node pool IAM service account | Fix registry access for the node identity |
| Host-network Pod behaves differently | Host-network metadata behavior | Review that workload's supported identity path |
Verify isolation as well as success
Confirm the intended Pod can read the test resource. Then verify that a different test ServiceAccount does not inherit that access. Restart the workload and repeat a safe call to exercise fresh credential acquisition. Ensure there is no static credential file overriding Application Default Credentials. A successful API call using a mounted key would not prove federation works.
Operating procedure
Record namespace, Kubernetes ServiceAccount, direct or impersonated principal, resource scope, and owner. Review identity bindings when renaming namespaces or reusing ServiceAccount names. Monitor authorization failures and token-exchange errors separately. Keep image-pull permissions in the node identity inventory and workload API permissions in the application identity inventory.
Explore Clouvenix containers kubernetes for implementation and operational handover.