Context
AKS workload identity allows a pod's Kubernetes identity to obtain Microsoft Entra tokens without storing a client secret. Before token exchange can work, the pod must receive the expected projected token and Azure configuration. A missing injection is a different failure from Azure rejecting an otherwise valid caller.
Prerequisites are the cluster, workload namespace, deployment and intended Kubernetes service account. Obtain read access to pod specifications and cluster identity settings. Avoid printing token file contents; their presence, mount configuration and nonsecret metadata are sufficient for initial diagnosis.
1. Inspect the running pod, then its template
Read the pod specification and compare it with the deployment's pod template. Confirm the required azure.workload.identity/use: "true" label is on the pod template, not merely the Deployment object's own metadata. The mutation webhook selects pods using this label.
Check serviceAccountName and the service account's client-ID annotation. A service account with the right name in another namespace is a different identity. Confirm that the running pod was created after the reviewed template change; editing a service account does not retroactively rewrite every existing pod specification.
2. Verify cluster and injection state
Inspect whether the cluster provides the OIDC issuer and workload identity capability. AKS offerings differ in which defaults are preconfigured, so read the deployed state rather than assuming a standard installation sequence applies universally.
Look for the expected Azure environment variable names and projected volume in the pod specification without exposing their credential values. If injection is absent, inspect admission events and webhook health through the supported cluster procedures. Do not debug downstream resource roles before establishing that the application received the credential inputs.
3. Validate the application credential path
Confirm that the shipped Azure Identity library supports workload identity and that the application uses the intended credential mechanism. An explicit environment credential or an older library can select another path. Sanitized identity diagnostics should reveal credential selection without revealing token bodies.
Once injection works, review federation using the exact OIDC issuer and system:serviceaccount:namespace:name subject, then review resource authorization separately. A token exchange failure and a forbidden data operation require different corrections. Apply a controlled rollout after template changes and preserve the prior deployment for rollback.
Diagnostic checkpoints
| Observation | Boundary | Next check |
|---|---|---|
| No projected volume | Pod mutation | Required template label |
| Wrong client ID | Service account mapping | Annotation and namespace |
| Token inputs exist, SDK ignores them | Application support | Library and credential chain |
| Exchange succeeds, resource denies | Data authorization | Actual principal and role |
Illustrative scenario
A hypothetical deployment places the workload identity label on Deployment metadata while leaving its pod template unlabeled. The service account annotation is correct, yet no projected Azure token appears in new pods. Inspecting the running specification identifies the missing selection label. This is a fictional configuration example, not an observed customer result.
Verification and deployment SOP
After correction, inspect a newly created pod and perform a narrowly scoped authorized read against the intended Azure resource. Confirm the actual identity through safe diagnostic records. Success from a developer laptop does not validate the pod credential path.
Document namespace, service account, issuer and client mapping in the SOP. Monitor failed token acquisition separately from resource authorization. Review the mapping when moving workloads between namespaces, recreating clusters or updating SDKs. Include injection checks in release review whenever service account or pod-template settings change.
Explore Clouvenix containers kubernetes for implementation and operational handover.