Use Azure Container Registry as an Upstream Source for Artifact Cache

In collaboration with:
Luis Dieguez, Principal Software Engineering Manager, Azure Container Registry
Akash Singhal, Senior Software Engineer, Azure Container Registry
Kiran Challa, Senior Software Engineer, Azure Container Registry
Nathan Anderson, Senior Software Engineer, Azure Container Registry
Tony Vargas, Senior Software Engineer, Azure Container Registry
Caroline Barker, Software Engineer II, Azure Container Registry
Mabel Egba, Software Engineer, Azure Container Registry

Introduction

ACR’s artifact cache feature has helped teams reduce upstream dependency on public registries like Docker Hub, GitHub Container Registry, and Microsoft Artifact Registry by serving cached copies of publicly available images from a local ACR instance. Until now, the main benefit of this feature has been to remove the dependency on a central public registry.

In the months after the feature release, we received a lot of requests from customers to enable ACR registries as an upstream source and we are glad to announce that this is now available.

In this post, we'll walk through:

• The new scenarios this capability enables.
• The supported authentication and networking matrix.
• A step-by-step walkthrough using the Azure CLI to set up an ACR-to-ACR cache rule with a user-assigned managed identity.

A Quick Refresher on Artifact Cache

Artifact cache is a pull-through proxy built into ACR. You define a cache rule that maps an upstream repository to a local repository in your ACR. When a client requests an image that hasn't been cached yet:

1. A client pulls from your ACR (e.g., docker pull myregistry.azurecr.io/team-a/api:1.0).
2. ACR proxies the pull to the upstream registry and streams content back to the client.
3. In parallel, ACR kicks off an asynchronous copy to store the image in your ACR.
4. Once the async copy finishes, all subsequent pulls are served directly from your ACR.

New Scenarios ACR-to-ACR Enables

This new capability unlocks the following scenarios:

• Quarantining and image promotion across environments. You can promote images between environments — for example, from a Dev registry to a Prod registry — by creating a cache rule on the target (Prod) registry that points at the source (Dev) registry as its upstream. The same pattern works for quarantining and scanning images pulled from public registries before they reach production. This increases security and reduces the risk of vulnerabilities in your environments.
• Hub-and-spoke or hierarchy registry topologies. You can use the feature to implement a hierarchy of registries (up to three levels) to serve subset of images to targeted runtime clusters. This increases the performance and pull throughput for individual clusters and reduces the load on a single registry with golden images.
• Eliminating credential sprawl. Existing cache rules require a credential set backed by Key Vault. With Managed Identity support, you can wire up ACR-to-ACR sync with zero secrets to rotate, store, or leak.

Authentication Model

A cache rule's authentication can now take one of these forms:

• Credentials — username/password, service principal, or ACR token stored in Key Vault. This is the already existing behavior.
• User-Assigned Managed Identity (UAMI) — a UAMI assigned to the target ACR is used to authenticate to the source ACR.

Design note: Managed identities are attached directly to the cache rule, not to a credential set. This is intentional and prevents a managed identity that's been granted pull permissions on a sensitive source registry from being silently reused by an unrelated cache rule pointing at a different upstream. Each cache rule gets its own explicit identity assignment.

Authentication & Networking Support Matrix

Two important callouts:

• Cross-tenant Managed Identity is not supported. Federated identity for cross-tenant scenarios is on the roadmap, and the cache-rule authentication model already includes the property shape (AuthenticationType: FederatedIdentity, TenantId, FederatedClientId) so the API is forward-compatible.
• Trusted Services must be enabled on the source ACR any time the source is on a non-public network and the target ACR uses an MI. This is what allows the platform to bypass the network ACL using a trusted Microsoft control-plane path.

RBAC Required on the Source ACR

The identity (whether UAMI, or credentials) needs read access to the source registry's repositories:

• RBAC and ABAC-enabled registries: assign the more granular roles Container Registry Repository Catalog Lister and Container Registry Repository Reader (optionally scoped to specific repositories).

On the target ACR, the user creating the rule needs Container Registry Cache Rule Administrator (and Container Registry Credential Set Administrator if creating a credential set).

Walkthrough: Promoting Images from Dev ACR to Prod ACR with a User-Assigned Managed Identity

Let's walk through the most common new scenario end-to-end: a Prod registry pulling images from a Dev registry, using a UAMI for authentication. Both registries are in the same tenant.

Setup

• Source registry (Dev): devregistry.azurecr.io, repository team-a/api
• Target registry (Prod): prodregistry.azurecr.io, repository promoted/team-a/api
• A User-Assigned Managed Identity acr-promotion-uami already exists in a resource group you own.

Step 1: Attach the UAMI to the Target ACR

az acr identity assign \ 
  --name prodregistry \ 
  --identities /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/acr-promotion-uami

You can verify which identities are assigned to the registry with:

az acr identity show -n prodregistry

You'll need two values from the UAMI in the next steps:

• The principal ID (object ID) — used in Step 2 for the role assignment on the source ACR.
• The resource ID (the full /subscriptions/.../providers/Microsoft.ManagedIdentity/userAssignedIdentities/<name> ARM ID) — used in Step 3 to attach the identity to the cache rule.

You can grab them with:

az identity show \ 
  --name acr-promotion-uami \ 
  --resource-group <rg> \ 
  --query '{principalId:principalId, resourceId:id}' -o tsv

Step 2: Grant the UAMI Read Access on the Source ACR

For an RBAC-only source registry:

az role assignment create \ 
  --assignee <uami-principal-id> \ 
  --role "Container Registry Repository Reader" \ 
  --scope /subscriptions/<sub-id>/resourceGroups/<dev-rg>/providers/Microsoft.ContainerRegistry/registries/devregistry 

az role assignment create \ 
  --assignee <uami-principal-id> \ 
  --role "Container Registry Repository Catalog Lister" \ 
  --scope /subscriptions/<sub-id>/resourceGroups/<dev-rg>/providers/Microsoft.ContainerRegistry/registries/devregistry

Note: We recommend enabling ABAC on your source registry and defining granular permissions for access to the upstream source registry and leveraging the —scope option for the above command to only limit the scope to the repositories the cache rule will read from.

Step 3: Create the Cache Rule with --identity

The new --identity (-i) parameter on az acr cache create accepts the resource ID (ARM ID) of the user-assigned managed identity you want the cache rule to use. It is mutually exclusive with --cred-set.

az acr cache create \ 
  --registry prodregistry \ 
  --name promote-team-a-api \ 
  --source-repo devregistry.azurecr.io/team-a/api \ 
  --target-repo promoted/team-a/api \ 
  --identity /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/acr-promotion-uami

If the identity you pass isn't actually assigned to the target ACR, you'll get a clear error indicating that the specified identity does not exist or is not associated with this registry.

Step 4: Pull Through the Cache

From any client that can authenticate to the target Prod registry:

az acr login --name prodregistry 
docker pull prodregistry.azurecr.io/promoted/team-a/api:1.4.0

Behind the scenes, the same artifact cache flow runs:

1. Prod ACR proxies the pull to Dev ACR, authenticating using the UAMI you attached to the rule.
2. The client receives the image immediately.
3. Prod ACR asynchronously copies the manifest(s) and layers into promoted/team-a/api.
4. When the async copy completes, ACR fires push webhook events on the target — exactly as it would for any other cache rule. (See the multi-arch webhook post for the event shape and timing.)

Step 5 (Optional): Update the Identity on an Existing Rule

You can swap the identity used by a cache rule at any time:

az acr cache update \ 
  --registry prodregistry \ 
  --name promote-team-a-api \ 
  --identity /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<new-uami-name>

This is useful when rotating identities or migrating a rule from a credential set to a managed identity.

Image Promotion as a First-Class Pattern

The most advanced use of this feature is image promotion — and it's worth calling out one nuance: a cache rule hydrates the target on demand, not on a schedule. The image lands in the target ACR the first time something pulls it through. Here are the steps for promoting an image:

1. A producer pushes a candidate image to the Dev registry (e.g., devregistry.azurecr.io/team-a/api:1.4.0).
2. A gating step (test pipeline, security scan, approval workflow) decides the image is fit for Prod.
3. The gating step does a docker pull prodregistry.azurecr.io/promoted/team-a/api:1.4.0 (or the equivalent in your CD system). That single pull triggers the cache rule and seeds Prod with the image.
4. On every subsequent pull, ACR performs a lightweight HEAD check against the upstream (Dev) registry to see whether the tag's manifest digest has changed. If the upstream tag was re-pushed (e.g., :1.4.0now points at a new digest), ACR re-pulls the updated content into Prod; otherwise, the pull is served directly from Prod without re-copying any layers.
5. From that point on, all Prod consumers serve the image from Prod — no further upstream traffic until the tag changes upstream again.

This collapses the typical "import job" into the first pull from Prod, which is both auditable (via webhooks and AAD logs on the source) and secured by a managed identity rather than a long-lived secret.

Limitations

A few things are explicitly out of scope for the initial private preview — file these under "coming soon" or "by design":

• Cross-tenant Managed Identity is not supported. Use a credential set for cross-tenant scenarios.
• Cross-tenant + Private VNet on the source ACR is not supported.
• Anonymous pull from the source ACR is not supported. Authentication is always required for ACR-to-ACR rules.
• Custom domains on the source ACR are not supported as an upstream value.
• Delete propagation is not part of this feature. Deletes on the source do not propagate to the target. (This matches existing Artifact Cache behavior.)
• The CLI does not provision identities or grant source-side RBAC for you. The identity must already exist, be attached to the target ACR, and have the right role on the source.
• Portal experience is in development and will be available later this Summer.

Summary

Here are the key takeaways from this new capability:

• ACR is now a supported upstream source for Artifact Cache. The data plane behavior — pull-through caching, async copy, webhook events, lifecycle — is identical to existing Artifact Cache behavior.
• User Assigned Managed Identity is now a first-class auth option for cache rules. The identity is attached directly to the cache rule rather than to a credential set, which is an explicit security decision to prevent token reuse outside the ACR-to-ACR scope.
• Same-tenant scenarios get the most flexibility: credentials, UAMI, public networking, selected networks, and Private Link are all supported. Cross-tenant scenarios are limited to credential-based auth on public networks.
• Common use cases unlocked: secure image promotion (Dev → Test → Prod registries), org-wide "golden image" distribution to regional registries, and replacing brittle az acr import scripts with a managed, declarative cache rule.

Q&A

For more details, check out the official Enable artifact cache to cache artifacts from another Azure Container Registry documentation.

If you have feedback, reach out to us on the Azure Container Registry GitHub repository or contact your Microsoft account team.