Programmatic rollout of Workload Identity

Problem

AKS Workload Identity replaces the deprecated AAD Pod Identity and removes static secrets from pods. A rollout touches the control plane, depends on SDK versions in every workload, and can fail in ways that only show up under load or after a token refresh. Without a plan, the first sign of a problem is an application that cannot reach its database.

Options and trade-offs

• Enable the OIDC issuer and Workload Identity on the cluster: a one-time change with a short control-plane impact. Announce a window for it.
• Parallel migration: run Workload Identity next to Pod Identity, move one workload at a time, verify each, then remove Pod Identity. It is slower, and it is the only approach with a clean rollback.
• Sidecar proxy for older SDKs: a temporary bridge that intercepts calls to the instance metadata endpoint for workloads that cannot upgrade yet. Treat it as a deadline, not a destination.

My recommendation

Migrate per namespace, starting with a low-risk internal workload. Define rollback criteria before the first change: error rate on token acquisition, authentication failures to the target service, and pod restarts. Do not remove Pod Identity until every workload has run on Workload Identity through at least one full token-renewal cycle.

Minimal working example

Enable the cluster features and look up the issuer:

az aks update --resource-group <rg> --name <aks> \
  --enable-oidc-issuer --enable-workload-identity

OIDC_ISSUER=$(az aks show -g <rg> -n <aks> --query "oidcIssuerProfile.issuerUrl" -o tsv)

Create a managed identity and federate it with one service account:

az identity create --name app-identity --resource-group <rg>
CLIENT_ID=$(az identity show -n app-identity -g <rg> --query clientId -o tsv)

az identity federated-credential create \
  --name app-fic \
  --identity-name app-identity \
  --resource-group <rg> \
  --issuer "$OIDC_ISSUER" \
  --subject system:serviceaccount:<namespace>:app-sa \
  --audience api://AzureADTokenExchange

Annotate the service account and label the pod:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: app-sa
  namespace: <namespace>
  annotations:
    azure.workload.identity/client-id: "<client-id>"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
  namespace: <namespace>
spec:
  replicas: 2
  selector:
    matchLabels: { app: app }
  template:
    metadata:
      labels:
        app: app
        azure.workload.identity/use: "true"
    spec:
      serviceAccountName: app-sa
      containers:
        - name: app
          image: <registry>/app:<tag>

Test it: deploy one workload, confirm it acquires a token and reaches its Azure dependency, then restart it and confirm it still does after the token refreshes.

Checklist

• Inventory workloads that still call the instance metadata endpoint or use older SDKs, and decide per workload whether to upgrade or bridge.
• Use one service account and one federated credential per workload identity, and keep least-privilege Azure RBAC on the identity.
• Write down rollback criteria and who decides, before the change window.
• Migrate one namespace at a time, and watch token errors and pod restarts after each.
• Remove Pod Identity only after every workload has been stable on Workload Identity, and confirm the add-on's end-of-support dates.
• Keep a record of every federated credential so stale ones can be cleaned up.

Where this doesn't apply

Kubernetes clusters outside Azure. They need the equivalent OIDC issuer configuration and federation, if the platform offers it.

Sources

• Workload Identity overview — https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview
• Migrate from Pod Identity — https://learn.microsoft.com/en-us/azure/aks/workload-identity-migrate-from-pod-identity
• Use AAD Pod Identity (deprecation notice) — https://learn.microsoft.com/en-us/azure/aks/use-azure-ad-pod-identity

---