Introduction

A “pull denied” error from Azure Container Registry usually means one of three things: the client is not authenticated, the principal lacks pull permission, or the image reference is wrong. The fastest way to debug it is to verify the exact registry login context, repository name, and RBAC assignment before changing cluster or Docker settings blindly.

Core Sections

Check the image reference first

An incorrect image name can look like an authorization failure because the registry refuses to return a manifest it cannot resolve.

An ACR image reference should look like this:

myregistry.azurecr.io/myapp/backend:1.2.3

Common mistakes include:

• wrong registry hostname
• wrong repository path
• missing tag
• using Docker Hub style names against ACR

Before debugging identity, confirm the image exists.

az acr repository list --name myregistry --output table
az acr repository show-tags --name myregistry --repository myapp/backend --output table

Authenticate the client correctly

For a local Docker pull, log in explicitly through Azure CLI or Docker.

az login
az acr login --name myregistry

That populates Docker credentials for the registry. If you are not using Azure CLI, you can also use a service principal or admin credentials, but managed identity and Azure AD-based access are usually cleaner.

Verify pull permissions

Authentication and authorization are separate. A user or workload can authenticate successfully and still be denied pull access.

For Azure RBAC, the usual role is AcrPull.

1az role assignment create \
2  --assignee <principal-id> \
3  --role AcrPull \
4  --scope $(az acr show --name myregistry --query id --output tsv)

If the pull happens from AKS, the node or cluster identity must have that permission, not just your human account.

AKS-specific case: attach or grant ACR access

When Kubernetes pulls from ACR, the cluster identity needs registry access. If you use AKS, one common approach is attaching the registry.

az aks update --name my-aks --resource-group my-rg --attach-acr myregistry

If that is not possible in your setup, assign AcrPull manually to the identity that actually pulls the images.

This is one of the most common reasons a local docker pull works while Kubernetes still reports image-pull failures.

Check network and registry restrictions

If ACR has private endpoints, firewall rules, or restricted public network access, the client may reach Azure but still fail to access the registry data plane correctly. In that case, the fix is not a new login. It is network reachability.

Useful checks include:

• whether public network access is disabled
• whether the client is on an allowed network path
• whether private DNS resolves the registry hostname correctly
• whether outbound rules from the cluster permit registry access

Docker and secret-based pulls

In Kubernetes without managed identity, an image pull secret may be required.

1kubectl create secret docker-registry acr-secret \
2  --docker-server=myregistry.azurecr.io \
3  --docker-username=<username> \
4  --docker-password=<password>

Then reference it in the pod or service account. If the secret is stale or attached to the wrong namespace, pulls still fail.

Common Pitfalls

• Debugging Azure permissions first when the image name or tag is actually wrong.
• Logging in locally and assuming the same credentials apply to AKS or another remote runtime pulling the image.
• Granting AcrPull to the wrong principal, such as a developer account instead of the cluster or workload identity.
• Forgetting about ACR firewall or private endpoint restrictions and treating the problem as pure authentication.
• Creating image pull secrets in one namespace and expecting pods in another namespace to use them automatically.

Summary

• “Pull denied” from ACR usually comes from a bad image reference, missing authentication, or missing pull permission.
• Confirm the repository and tag exist before chasing identity issues.
• Use az acr login for local Docker access and AcrPull for the actual pulling principal.
• In AKS, make sure the cluster or workload identity can access the registry.
• If ACR uses network restrictions, verify reachability as well as credentials.