How to fix Kubelet identity assignment failed in Kubernetes

Check which managed identity is assigned to your AKS cluster:

az aks show --resource-group <resource-group-name> --name <cluster-name> --query "identityProfile.kubeletidentity"

This will return the resource ID of the currently assigned kubelet identity. Note this for the next steps.

Verify that the kubelet identity has the AcrPull role on your Azure Container Registry:

az role assignment list --assignee <kubelet-identity-id> --scope <acr-resource-id>

Look for an assignment with the role "AcrPull" or "Contributor". If none exists, proceed to the next step.

If the kubelet identity lacks ACR permissions, assign the AcrPull role:

az role assignment create --assignee <kubelet-identity-id> --role AcrPull --scope <acr-resource-id>

Replace placeholders:
- <kubelet-identity-id>: The client ID or principal ID from step 1
- <acr-resource-id>: The full resource ID of your ACR (e.g., /subscriptions/.../registries/myregistry)

Wait 60-120 seconds for the role assignment to propagate through Azure RBAC.

After granting permissions, restart the nodes to refresh the managed identity token cache:

az aks nodepool upgrade --resource-group <resource-group-name> --cluster-name <cluster-name> --name <nodepool-name> --kubernetes-version <version>

Alternatively, manually restart nodes:

kubectl cordon -l agentpool=<nodepool-name>
kubectl drain -l agentpool=<nodepool-name> --ignore-daemonsets --delete-emptydir-data
# After nodes restart, uncordon them:
kubectl uncordon -l agentpool=<nodepool-name>

Or use Azure CLI to reimage nodes:

az aks nodepool reimage --resource-group <resource-group-name> --cluster-name <cluster-name> --nodepool-name <nodepool-name>

If you need to assign a custom user-assigned managed identity as the kubelet identity, ensure the identity has the "Microsoft.ManagedIdentity/userAssignedIdentities/assign/action" permission.

Create a custom role with this action:

cat > custom-role.json << EOF
{
  "Name": "Kubelet Identity Assigner",
  "Description": "Allow assigning user identities as kubelet identity",
  "Actions": [
    "Microsoft.ManagedIdentity/userAssignedIdentities/assign/action"
  ],
  "AssignableScopes": [
    "/subscriptions/<subscription-id>"
  ]
}
EOF

az role definition create --role-definition @custom-role.json

Then assign this custom role to your user/service principal at the identity resource level (not just resource group level).

After upgrading your AKS cluster, if you used --attach-acr during cluster creation, re-run the attach command to ensure the new kubelet identity gets ACR permissions:

az aks update --resource-group <resource-group-name> --name <cluster-name> --attach-acr <acr-name>

This automatically grants the AcrPull role to the kubelet identity for that ACR.

Create a test pod to verify the kubelet can now pull images from ACR:

kubectl run test-pull --image=<acr-name>.azurecr.io/test-image:latest --image-pull-policy=Always
kubectl describe pod test-pull
kubectl logs test-pull

If the pod runs successfully, the kubelet identity permissions are restored. Delete the test pod:

kubectl delete pod test-pull