# Pod stuck in ContainerCreating status: failed to pull image from ACR

- **ID:** `cloud/azure-aks-pod-stuck-containercreating`
- **Domain:** cloud
- **Category:** config_error
- **Error Code:** `ImagePullBackOff`
- **Verification:** ai_generated
- **Fix Rate:** 83%

## Root Cause

Azure Kubernetes Service (AKS) pod cannot pull a container image from Azure Container Registry (ACR) because the AKS cluster's service principal or managed identity lacks AcrPull role assignment on the ACR, or the image tag does not exist.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| AKS 1.28 | active | — | — |
| Azure CLI 2.58.0 | active | — | — |
| ACR Premium | active | — | — |

## Workarounds

1. **Assign the AcrPull role to the AKS cluster's managed identity: `az role assignment create --assignee <aks-cluster-identity-client-id> --role AcrPull --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.ContainerRegistry/registries/<acr-name>`. Get the AKS identity via `az aks show -g <rg> -n <cluster-name> --query identityProfile.kubeletidentity.clientId`.** (90% success)
   ```
   Assign the AcrPull role to the AKS cluster's managed identity: `az role assignment create --assignee <aks-cluster-identity-client-id> --role AcrPull --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.ContainerRegistry/registries/<acr-name>`. Get the AKS identity via `az aks show -g <rg> -n <cluster-name> --query identityProfile.kubeletidentity.clientId`.
   ```
2. **If using a service principal, create a Kubernetes secret with ACR credentials and reference it in the pod spec: `kubectl create secret docker-registry acr-secret --docker-server=<acr-name>.azurecr.io --docker-username=<app-id> --docker-password=<password>`. Then add `imagePullSecrets: - name: acr-secret` to the deployment YAML.** (80% success)
   ```
   If using a service principal, create a Kubernetes secret with ACR credentials and reference it in the pod spec: `kubectl create secret docker-registry acr-secret --docker-server=<acr-name>.azurecr.io --docker-username=<app-id> --docker-password=<password>`. Then add `imagePullSecrets: - name: acr-secret` to the deployment YAML.
   ```

## Dead Ends

- **** — The same image pull configuration is used; the new pod will fail with the same error. (95% fail)
- **** — The kubelet uses the cluster's credential provider (e.g., acr-credential-provider), not the user's Docker config. (85% fail)