An application builds successfully, its image is pushed to Azure Container Registry, and the deployment still fails because the runtime cannot pull that image. The build pipeline reports success. The repository and tag are visible to the developer. Yet the production workload receives an authentication error. The failure is often not in the container image at all: the system that writes an image and the system that consumes it can have different identities, permissions, network paths, and policies.
Azure Container Registry (ACR) is a private registry service for storing and distributing container images and compatible artifacts. Operating it safely requires more than creating a registry and copying an image. Administrators need to distinguish registry configuration from repository access, interactive developer sign-in from workload identity, and a successful registry login from authorization to pull a particular artifact.
Understand the boundary between a registry and a running container
ACR stores images and artifacts; it does not make an application run. A deployment service still needs to authenticate, download an allowed image, start the container, and reach any application dependencies. That separation explains why registry administration is part of the Microsoft AZ-104 compute objectives even though the actual runtime may be Azure Container Instances, Azure Container Apps, or another supported platform.
The choice of runtime is a separate decision. Azure Container Instances and Container Apps provide different deployment and scaling models, but either must be able to obtain its image from the configured registry. A team can troubleshoot deployment much faster when it asks, in order, whether the artifact exists, whether the consumer can reach the registry, whether it can authenticate, and whether that identity is authorized for the requested operation.
Design the registry before selecting an authentication method
Start with the registry’s subscription, resource group, region, unique name, pricing tier, network requirements, and operational owner. Its login server is an endpoint ending in azurecr.io in the Azure public cloud. Applications and pipelines must refer to the correct login server and repository path; using the resource name where a fully qualified image reference is required, or the login server where a command expects a resource name, produces avoidable errors.
Microsoft’s current portal quickstart illustrates a Standard registry and offers a role assignment permissions mode choice. Standard is suitable for many common image workflows; capabilities such as private endpoint connectivity require evaluating a tier with the relevant feature support, such as Premium. Do not enable a feature merely because it sounds more secure: first identify the consumer networks, image throughput, cost, and operational requirements.
Registry-level configuration access and repository data access are separate security questions. An administrator may be able to change registry networking or settings yet be unable to pull an image. Conversely, an application identity may need to read one repository without having any reason to modify registry-wide controls. Design both boundaries explicitly rather than relying on a broad Owner or Contributor assignment to solve every problem.
Choose roles according to the registry permission mode
ACR supports two important role assignment permissions models. A registry using RBAC Registry Permissions relies on legacy registry data roles such as AcrPull and AcrPush. A registry using RBAC Registry + ABAC Repository Permissions uses newer repository roles, with optional attribute-based conditions that can restrict access to specific repositories. The role names and their effect are not interchangeable between these modes.
| Required operation | RBAC-only registry | ABAC-enabled registry |
|---|---|---|
| Read and pull an image | AcrPull |
Container Registry Repository Reader |
| Push and update images | AcrPush |
Container Registry Repository Writer |
| Delete repository artifacts | Use an appropriate delete-capable registry role | Container Registry Repository Contributor |
| List the complete repository catalog | Follow the applicable registry role permissions | Container Registry Repository Catalog Lister separately |
The ABAC-enabled reader role does not automatically grant permission to list every repository in the catalog. That is deliberate: seeing or pulling an image in a known repository is different from discovering all repository names. An operator may successfully pull a known image while a broad catalog-list command fails. Grant the catalog-lister role only when the job actually requires registry-wide discovery.
An ABAC-compatible repository role without a repository condition can still apply across all repositories. Adding a condition to limit access to the intended repository is what makes the assignment repository-specific. If an identity only needs one application’s image, grant that access rather than silently giving it access to unrelated images in the same registry.
Keep human, pipeline, and application identities distinct
A developer working interactively can authenticate through Microsoft Entra ID using an approved local Azure CLI session. An unattended build pipeline might use a service principal or a supported workload identity. An Azure-hosted runtime can often use a managed identity, avoiding long-lived registry passwords in deployment configuration. These identities should not be shared merely because they interact with the same image.
A useful least-privilege split gives a build identity only the rights it needs to publish an approved image, a deployment identity only the rights needed to pull that image, and a platform administrator the separate rights required to manage registry settings and assignments. Azure RBAC scope and inheritance matter because roles are effective only at their assignment scope and beneath it; the exact ACR repository permissions still depend on the registry mode.
The ACR administrator account is a broad credential mechanism, not an identity strategy for multiple people or workloads. Leave it disabled unless a documented, narrowly controlled workflow genuinely requires it. If temporary use becomes unavoidable, define who holds the credential, where it is stored, how it is rotated, and when it will be disabled again.
Configure a private image pull with managed identity
Consider a Container App whose image is stored in a private ACR repository. The app’s runtime needs a supported managed identity, registry configuration that points to the intended login server, and a repository read assignment that matches the registry’s permission mode. This is separate from the developer who originally pushed the image.
- Confirm the image exists. Record the registry login server, repository name, and approved tag or digest before changing permissions.
- Identify the consumer. Determine whether the runtime uses a system-assigned or user-assigned managed identity, and record that identity’s principal ID.
- Check the registry’s role assignment permissions mode. Use the corresponding data-plane role: legacy
AcrPullon RBAC-only registries, or the appropriate repository reader role on ABAC-enabled registries. - Limit scope where supported. If using ABAC repository conditions, grant the identity access only to the repository it actually consumes.
- Configure registry authentication on the runtime. Select managed identity rather than adding a registry password to the app’s configuration.
- Deploy and verify an actual pull. Validate a new revision or startup with the intended image. A role assignment appearing in the portal is not proof the workload can download its image.
Microsoft documents both user-assigned and system-assigned managed identity flows for Container Apps. A user-assigned identity can exist independently of the application and be reused when that is operationally appropriate; a system-assigned identity follows the app’s lifecycle. The consuming service and the registry must both support the chosen flow. Account for role-assignment propagation time before deciding a correct change has failed.
Use image tags for release identity and digests for stronger reproducibility
A repository can contain several tagged image versions. A tag is a human-readable reference and can be repointed, depending on permissions and registry policy. A digest identifies specific content. Teams should know whether a deployment points to a mutable tag or to an immutable image digest, because a repeated deployment using the same tag may not reproduce the exact bytes originally tested.
For a controlled release, record the source commit, build result, image repository, tag, digest, promotion decision, and deployed runtime revision. Separate the identity authorized to publish the artifact from the identity allowed to consume it. A healthy application-release record answers not merely which tag was named, but which image actually ran and how that content was approved.
Security scanning, retention, quarantine, signing, and artifact deletion have different operational purposes and may depend on registry configuration and supported features. Avoid implementing automated cleanup without checking deployment references and rollback requirements. A deployment can fail long after a build when a tag or image needed for rollback has already been deleted.
Network reachability is a separate gate from authentication
Even a correctly assigned repository reader role cannot pull an image when the runtime cannot reach the registry endpoints. Public network access rules, proxies, private endpoints, DNS resolution, and egress restrictions can all interrupt the transfer. The registry login endpoint and image data endpoints need to be reachable through a permitted path for the selected network architecture.
Private Link changes how clients reach the registry and how its name resolves, but it does not replace repository permissions. The broader distinction between Azure Private Endpoints and service endpoints matters because the right endpoint policy and the right DNS answer must agree. For a private registry path, verify that the client resolves the intended registry name to the expected private address, and check that the actual container-host network follows the same permitted route.
Do not assume every Azure service supports every restricted-network registry configuration in the same way. Before disabling public access, confirm the documented connectivity model for each actual runtime and any scanning, building, or deployment integration. Otherwise the security change may unintentionally interrupt an image-publishing or image-pulling dependency.
Diagnose failed pulls in the order the operation actually occurs
An image-pull error usually belongs to one of several different stages. Begin by reproducing the failure using the affected identity and environment, then use the error and registry logs to decide which layer to investigate.
| Observed symptom | Likely boundary to test | Useful next check |
|---|---|---|
| Registry name cannot resolve or the request times out | DNS, proxy, firewall, routing, endpoint availability | Inspect resolution and allowed egress from the actual container host |
401 or authentication required |
Credential acquisition, token validity, configured identity | Verify the identity and sign-in method actually used by the runtime |
403 or access denied |
Repository role, ABAC condition, public access policy, proxy | Check both permissions and network rules; the code alone is not a diagnosis |
| Repository listing fails but a known pull succeeds | Catalog-discovery permission | Determine whether the identity really needs a catalog-lister role |
| Image manifest or tag not found | Repository path, tag, digest or image availability | Compare the deployed image reference against the approved published artifact |
From a workstation or suitable diagnostic host, Microsoft supports az acr check-health --name <registry-name> --yes to collect registry health signals. The check can identify local-tool or connectivity problems, but it does not replace validating a pull from the actual workload identity and network. A healthy local workstation is not proof that an isolated production container environment can reach the same endpoint.
The distinction between a configuration check and a real observed outcome is central to Azure Monitor troubleshooting. Pair the failed runtime event with the identity used, a timestamp, network/DNS evidence, the exact image reference, and the permission assignment effective at that point. Without those details, teams often solve the wrong problem by granting additional rights to an identity that could not reach the registry in the first place.
Changing from legacy registry permissions needs a migration plan
An RBAC-only registry can be migrated to ABAC-enabled repository permissions, but changing the mode is not a harmless cosmetic switch. Legacy data-plane roles such as AcrPull and AcrPush are not honored as equivalent repository access roles after the transition. Microsoft also warns that credentials minted under the old permission mode may fail after the switch even if the identity has been given new roles.
Inventory all identities first: developers, build agents, deployment services, running applications, scanners, automation, and any custom integrations. Assign appropriate equivalent repository permissions before switching the mode. Check which workflows need catalog discovery in addition to read/write access, then plan token renewal and staged verification. A test pull from only one developer laptop is insufficient for a change that affects multiple pipelines and production runtimes.
After any such change, validate real pull and push operations with least-privileged test identities and document the result. Rollback planning must address both role assignments and credentials, not merely the registry’s visible setting.
A practical readiness check protects production and the exam scenario
Imagine a production deployment that was working yesterday but now fails to start. The registry is online, a developer can see the image, and the application is using a managed identity. Before enabling the administrator account or assigning Owner, determine the registry permission mode, the application’s actual principal, the repository condition, the image digest, and the network path. Each answer rules out an entire class of failures.
For Azure administrators, the goal is to make registry behavior explainable and auditable. A reliable implementation has a known owner, least-privilege push and pull identities, verified network and name resolution, a reproducible image reference, measured deployment outcome, and a tested recovery path. These controls matter whenever a private image must move from an approved build into a running Azure workload.
