highIntermediateSymptom-first#aks#acr#registry#rbac#authentication

AKS pull unauthorized from ACR — AcrPull role missing

Pod events show Failed to pull image: unauthorized

Likely source:connectivitysecurityconfiguration

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Pod events show Failed to pull image: unauthorized
  • az acr login returns unauthorized: authentication required
  • AKS nodes cannot pull from ACR despite ACR attached to the cluster

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • AKS identity profile

    az aks show -g <RG> -n <AKS> --query identityProfile -o json

  • ACR role assignments

    az role assignment list --scope <ACR-SCOPE> --query "[].{principal:principalId,role:roleDefinitionName}" -o table

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • Pod events: unauthorized: authentication required
  • az role assignment list shows no AcrPull for the kubelet identity

Confirm before fixing

az role assignment list --scope <ACR-SCOPE> --query "[?roleDefinitionName=='AcrPull']" -o table
READ

Confirm AcrPull assignment

Fix

az aks update -g <RG> -n <AKS> --attach-acr <ACR>
CHANGE

Attach ACR to AKS (auto-assigns AcrPull)

Expected: Managed cluster '<AKS>' is updated

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
az aks show -g <RG> -n <AKS> --query identityProfile -o json
READ

Get the kubelet identity principal ID

2
az role assignment list --scope <ACR-SCOPE> --query "[?roleDefinitionName=='AcrPull']" -o table
READ

Check for AcrPull role

3
az aks update -g <RG> -n <AKS> --attach-acr <ACR>
CHANGE

Attach ACR to grant AcrPull automatically

4
kubectl get pods -n <NAMESPACE> --field-selector=status.phase!=Running
READ

Confirm pods can now pull images

Prevention

  • Always use az aks update --attach-acr rather than manual role assignments.
  • Use ACR admin accounts only for dev/test, never for production AKS clusters.
  • Enable ACR quarantine to scan images before pulling.
  • Monitor ACR pull metrics and alert on authentication failures.

Related runbooks

Same stack, same failure family — worth a skim.

ImagePullBackOff / ErrImagePull — pod can't fetch its imagehigh

Pod stuck in ImagePullBackOff or ErrImagePull

KubernetesFoundation3 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.