Articles

Connect AKS to Azure Container Registry (2026)

April 16, 2026 8 min read

AKS can’t pull images from Azure Container Registry because the AKS cluster’s service principal or managed identity lacks the necessary permissions on the ACR.

Here’s the breakdown of what’s happening and how to fix it:

The Core Problem: Identity and Access Management

Your Azure Kubernetes Service (AKS) cluster needs to authenticate with your Azure Container Registry (ACR) to pull container images. This authentication happens using an "identity." In AKS, this identity is typically either a service principal (an older method) or a managed identity (the recommended, more secure approach).

The problem arises when this identity doesn’t have the correct permissions granted on the ACR. The ACR acts like a locked door, and the AKS identity needs a key (a role assignment) to get in and pull images. Without that key, the pull operation fails with an authorization error.

Common Causes and Fixes

  1. Service Principal/Managed Identity Lacks AcrPull Role: This is by far the most common reason. The identity used by AKS simply hasn’t been granted the permission to read images from ACR.

    • Diagnosis:

      • Find your AKS cluster’s identity:
        • Service Principal: Look at your AKS cluster’s properties in the Azure portal. Under "Identity," you’ll see the Service Principal ID. Alternatively, use the Azure CLI:
          az aks show --resource-group <your-aks-rg> --name <your-aks-cluster-name> --query servicePrincipalProfile.clientId -o tsv
        • Managed Identity: If your AKS cluster uses a system-assigned managed identity, it’s automatically created with the cluster. If it uses a user-assigned managed identity, you’ll see it in the AKS cluster’s "Identity" settings. You can also query for it:
          # For system-assigned managed identity (look for the Principal ID)
az aks show --resource-group <your-aks-rg> --name <your-aks-cluster-name> --query identity.principalId -o tsv

# For user-assigned managed identity (look for the Principal ID of the assigned identity)
az aks show --resource-group <your-aks-rg> --name <your-aks-cluster-name> --query identity.userAssignedIdentities --output json
      • Check ACR role assignments: Go to your ACR in the Azure portal. Navigate to "Access control (IAM)" and click "Role assignments." Filter by the identity (Service Principal or Managed Identity) you found. See if it has the "AcrPull" role.
      • Azure CLI check:
        # Replace <your-acr-name>, <identity-id>
az role assignment list --scope /subscriptions/<your-subscription-id>/resourceGroups/<your-acr-rg>/providers/Microsoft.ContainerRegistry/registries/<your-acr-name> --assignee <identity-id> --query "[].{Role:roleDefinitionName, Scope:scope}" -o table

    • Fix: Grant the AcrPull role to the AKS identity on the ACR.

      • Azure Portal: In your ACR’s "Access control (IAM)," click "+ Add" -> "Add role assignment." Select the "AcrPull" role. In "Assign access to," choose "Managed identity" or "Service principal." Select your AKS cluster’s identity. Click "Save."
      • Azure CLI:
        # For Service Principal
az role assignment create --assignee <service-principal-id> --role AcrPull --scope /subscriptions/<your-subscription-id>/resourceGroups/<your-acr-rg>/providers/Microsoft.ContainerRegistry/registries/<your-acr-name>

# For Managed Identity (use the Principal ID)
az role assignment create --assignee <managed-identity-principal-id> --role AcrPull --scope /subscriptions/<your-subscription-id>/resourceGroups/<your-acr-rg>/providers/Microsoft.ContainerRegistry/registries/<your-acr-name>

    • Why it works: The AcrPull role explicitly grants the identity permission to pull images from the specified container registry.

  2. Incorrectly Configured imagePullSecrets in Kubernetes Pod Spec: If you’re manually configuring Kubernetes secrets for ACR authentication (which is less common when using AKS’s built-in integration but possible), the secret might be malformed or referencing the wrong credentials.

    • Diagnosis:

      • Examine your Kubernetes Deployment or Pod YAML. Look for the imagePullSecrets field.
      • Ensure the secret it references exists in the same namespace as your pod.
      • Check the secret’s data:
        kubectl get secret <your-secret-name> -n <your-namespace> -o yaml
        The .dockerconfigjson field should contain valid Base64 encoded Docker credentials for your ACR.

    • Fix:

      • Recommended: Remove imagePullSecrets if your AKS cluster is configured with managed identity or service principal integration for ACR. AKS handles this automatically.
      • Manual Fix: If you must use imagePullSecrets, ensure it’s correctly created. The easiest way is often to use kubectl create secret docker-registry:
        kubectl create secret docker-registry <your-secret-name> \
  --docker-server=<your-acr-login-server> \
  --docker-username=<your-acr-admin-username> \
  --docker-password=<your-acr-admin-password> \
  --namespace=<your-namespace>
        (Note: Using admin credentials is less secure; prefer using a service principal with AcrPull and its secret if manual configuration is unavoidable).

    • Why it works: Kubernetes uses the imagePullSecrets to find credentials for pulling images. A correctly formed secret provides the necessary authentication token to the container runtime.

  3. ACR Network Restrictions (Firewall/Private Endpoint): If your ACR has network restrictions (e.g., firewall rules allowing only specific IPs, or it’s configured with a private endpoint), your AKS nodes might not be able to reach it.

    • Diagnosis:

      • Check your ACR’s "Networking" settings in the Azure portal.
      • If "Public network access" is set to "Enabled from selected virtual networks and IP addresses," verify that your AKS node subnet is listed or that the AKS VNet is linked.
      • If a private endpoint is configured, ensure your AKS cluster’s VNet is peered with the VNet hosting the private endpoint, or that the AKS nodes can resolve the private DNS name.
      • Try to curl the ACR login server from one of your AKS nodes (you might need to kubectl exec into a pod running on a node).

    • Fix:

      • Public Access: If using public access, add your AKS subnet to the ACR’s allowed virtual networks.
      • Private Endpoint: Ensure VNet peering is correctly configured between your AKS VNet and the private endpoint’s VNet, or that DNS resolution is working for the private endpoint.
      • AKS Private Cluster: If your AKS is a private cluster, ensure its private DNS zone is correctly configured to resolve the ACR’s private endpoint.

    • Why it works: Network rules dictate reachability. By allowing traffic from AKS or ensuring proper private network connectivity, you enable the AKS nodes to communicate with the ACR endpoint.

  4. AKS Cluster Identity Not Specified or Incorrectly Set: When creating an AKS cluster, you specify its identity. If this was missed or configured incorrectly, it won’t have an identity to use for ACR authentication.

    • Diagnosis:

      • Check the AKS cluster’s "Identity" settings in the Azure portal. It should show either a system-assigned managed identity or a user-assigned managed identity.
      • If using a service principal, check servicePrincipalProfile.clientId and servicePrincipalProfile.secret (though using secrets is discouraged).

    • Fix:

      • Recreate AKS (if possible): The easiest way to ensure correct identity setup is often to recreate the AKS cluster, explicitly selecting "System assigned managed identity" during creation.
      • Update User-Assigned Identity: If using a user-assigned managed identity, ensure it’s correctly assigned to the AKS cluster. You can update this via Azure CLI:
        # Add a user-assigned identity
az aks update --resource-group <your-aks-rg> --name <your-aks-cluster-name> \
    --assign-identity <user-assigned-identity-resource-id>

# Remove a user-assigned identity (if needed)
az aks update --resource-group <your-aks-rg> --name <your-aks-cluster-name> \
    --remove-assign-identity <user-assigned-identity-resource-id>
      • Service Principal: If using a service principal, ensure it’s correctly created and its details are provided during AKS creation.

    • Why it works: The AKS cluster needs a valid identity to present to Azure services like ACR for authentication.

  5. ACR Admin User Disabled: If you are relying on the ACR admin user credentials (which is generally discouraged for security reasons), ensure the "Admin user" setting is enabled in your ACR’s "Access keys" configuration.

    • Diagnosis:

      • Go to your ACR in the Azure portal. Navigate to "Access keys."
      • Check if "Admin user" is toggled "On." If it’s "Off," the admin username and password will not be available.

    • Fix:

      • Toggle "Admin user" to "On."
      • Strongly Recommended: Reconfigure AKS to use a managed identity or service principal with the AcrPull role instead of relying on admin credentials.

    • Why it works: The admin user credentials are required for direct authentication using username/password, which is what docker login or imagePullSecrets might implicitly use if not properly set up with a service principal.

  6. AKS Cluster Region Mismatch with ACR Region: While Azure services are generally global, sometimes regional configurations can cause subtle issues, especially with networking or identity providers. Ensure your AKS cluster and ACR are in compatible regions, or at least that network routing between them is not problematic.

    • Diagnosis: Check the region of your AKS cluster and your ACR in the Azure portal.
    • Fix: Ideally, place AKS and ACR in the same region for best performance and simplest network configuration. If they must be in different regions, ensure VNet peering or appropriate routing is in place if private endpoints are used, or that public access is allowed.
    • Why it works: Proximity and network path optimization can prevent transient communication errors.

After applying these fixes, you should be able to successfully pull images from your Azure Container Registry to your AKS cluster. The next potential issue you might encounter is related to RBAC within Kubernetes itself, specifically pod creation permissions.

Want structured learning?

Take the full Aks course →