Enable artifact cache to cache artifacts from another Azure Container Registry

Create a user-assigned managed identity

ACR-to-ACR caching authenticates to the upstream registry using a user-assigned managed identity instead of username and password credentials stored in Key Vault. You need to create a managed identity and grant it pull access to the upstream registry.

1. Create a user-assigned managed identity:

   az identity create \
     --name MyACRCacheIdentity \
     --resource-group MyResourceGroup
   

2. Get the principal ID and resource ID of the managed identity:

   IDENTITY_PRINCIPAL_ID=$(az identity show \
     --name MyACRCacheIdentity \
     --resource-group MyResourceGroup \
     --query 'principalId' \
     -o tsv)
   
   IDENTITY_RESOURCE_ID=$(az identity show \
     --name MyACRCacheIdentity \
     --resource-group MyResourceGroup \
     --query 'id' \
     -o tsv)
   

Assign pull permissions on the upstream registry

The upstream registry must have ABAC (Attribute-Based Access Control) enabled so you can assign fine-grained repository permissions. The managed identity needs the Container Registry Repository Reader role on the upstream registry, scoped to the specific repository you want to cache.

1. Get the resource ID of the upstream registry:

   UPSTREAM_ID=$(az acr show \
     --name UpstreamRegistry \
     --query 'id' \
     -o tsv)
   

2. Assign the Container Registry Repository Reader role to the managed identity on the upstream registry:

   az role assignment create \
     --role "Container Registry Repository Reader" \
     --assignee "$IDENTITY_PRINCIPAL_ID" \
     --scope "$UPSTREAM_ID/repositories/myapp"
   

Create a cache rule

Create a cache rule that pulls artifacts from the upstream registry into your downstream registry.

1. Run az acr cache create to create a cache rule. Use the --identity parameter to specify the user-assigned managed identity for authentication with the upstream registry:

   az acr cache create \
     -r MyRegistry \
     -n MyRule \
     -s upstreamregistry.azurecr.cn/myapp \
     -t myapp \
     --identity "$IDENTITY_RESOURCE_ID"
   

2. Run az acr cache show to verify the cache rule:

   az acr cache show -r MyRegistry -n MyRule
   

Define the Bicep template

Create a Bicep file that defines a user-assigned managed identity and cache rule for ACR-to-ACR caching.

@description('Name of the downstream (cache) registry.')
param registryName string

@description('Login server of the upstream registry (for example, upstreamregistry.azurecr.cn).')
param upstreamLoginServer string

@description('Repository path on the upstream registry to cache (for example, myapp).')
param sourceRepository string

@description('Repository name in the downstream registry for cached artifacts.')
param targetRepository string

@description('Name of the user-assigned managed identity.')
param identityName string = 'acrCacheIdentity'

@description('Name of the cache rule.')
param cacheRuleName string = 'cacheRule'

@description('Location for resources.')
param location string = resourceGroup().location

resource registry 'Microsoft.ContainerRegistry/registries@2025-11-01' existing = {
  name: registryName
}

resource managedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: identityName
  location: location
}

resource cacheRule 'Microsoft.ContainerRegistry/registries/cacheRules@2026-01-01-preview' = {
  name: '${registry.name}/${cacheRuleName}'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${managedIdentity.id}': {}
    }
  }
  properties: {
    sourceRepository: '${upstreamLoginServer}/${sourceRepository}'
    targetRepository: targetRepository
  }
}

@description('Principal ID of the managed identity. Grant this identity Container Registry Repository Reader on the upstream registry.')
output identityPrincipalId string = managedIdentity.properties.principalId

Save this file as acr-cache.bicep.

Deploy the template

1. Deploy the Bicep template to create the managed identity and cache rule:

   az deployment group create \
     --resource-group MyResourceGroup \
     --template-file acr-cache.bicep \
     --parameters \
       registryName=MyRegistry \
       upstreamLoginServer=upstreamregistry.azurecr.cn \
       sourceRepository=myapp \
       targetRepository=myapp
   

2. Note the identityPrincipalId value from the deployment output.

3. Assign the Container Registry Repository Reader role to the managed identity on the upstream registry:

   Note

   The upstream registry must have ABAC enabled. If it doesn't, run az acr update --name UpstreamRegistry --role-assignment-mode rbac-abac first.

   UPSTREAM_ID=$(az acr show --name UpstreamRegistry --query 'id' -o tsv)
   
   az role assignment create \
     --role "Container Registry Repository Reader" \
     --assignee "<identityPrincipalId>" \
     --scope "$UPSTREAM_ID/repositories/myapp"