Enable artifact cache in your Azure Container Registry with Azure CLI

In this article, you learn how to use Azure CLI to enable the artifact cache feature in your Azure Container Registry (ACR) with or without authentication using Azure CLI.

In addition to the prerequisites listed here, you need an Azure account with an active subscription. Create an account for free.

Prerequisites

• Azure CLI. You can use the Azure Cloud Shell or a local installation of Azure CLI to run the commands in this article. If you'd like to use it locally, Azure CLI version 2.46.0 or later is required. To confirm your Azure CLI version, run az --version. To install or upgrade, see Install Azure CLI.
• An existing ACR instance. If you don't already have one, use our quickstart to create a new container registry.
• An existing Key Vault to create and store credentials.
• Permissions to set and retrieve secrets from your Key Vault.

In this article, we use an example ACR instance named MyRegistry.

Create the credentials

Before configuring the credentials, make sure you're able to create and store secrets in the Azure Key Vault and retrieve secrets from the Key Vault..

1. To create the credentials, run az acr credential set create:

   az acr credential-set create 
   -r MyRegistry \
   -n MyDockerHubCredSet \
   -l docker.io \ 
   -u https://MyKeyvault.vault.azure.net/secrets/usernamesecret \
   -p https://MyKeyvault.vault.azure.net/secrets/passwordsecret
   

2. To update the username or password Key Vault secret ID on the credential set, run az acr credential set update :

   az acr credential-set update -r MyRegistry -n MyDockerHubCredSet -p https://MyKeyvault.vault.azure.net/secrets/newsecretname
   

3. To show credentials, run az acr credential-set show:

   az acr credential-set show -r MyRegistry -n MyDockerHubCredSet
   

Create a cache rule

Next, create and configure the cache rule that will be used to pull artifacts from the repository into your cache.

1. To create a new cache rule, run az acr cache create:

   az acr cache create -r MyRegistry -n MyRule -s docker.io/library/ubuntu -t ubuntu -c MyDockerHubCredSet
   

2. To update credentials on the cache rule, run az acr cache update:

   az acr cache update -r MyRegistry -n MyRule -c NewCredSet
   

   If you need to remove the credentials, run az acr cache update -r MyRegistry -n MyRule --remove-cred-set.

3. To show cache rules, run az acr cache show:

    az acr cache show -r MyRegistry -n MyRule
   

Tip

To create a cache rule without using credentials, use the same command without credentials specified. For example, az acr cache create -r MyRegistry -n MyRule -s docker.io/library/ubuntu -t ubuntu. For some sources, such as Docker Hub, credentials are required in order to create a cache rule.

Assign permissions to Key Vault using access policies

You can use access policies to assign the appropriate permissions to users so they can access the Azure KeyVault.

1. Get the principal ID of the system identity in use to access Key Vault:

   PRINCIPAL_ID=$(az acr credential-set show 
                   -n MyDockerHubCredSet \ 
                   -r MyRegistry  \
                   --query 'identity.principalId' \ 
                   -o tsv) 
   

2. Run the az keyvault set-policy command to assign access to the Key Vault before pulling the image. For example, to assign permissions for the credentials to access the KeyVault secret:

   az keyvault set-policy --name MyKeyVault \
   --object-id $PRINCIPAL_ID \
   --secret-permissions get
   

Pull your image

Pull the image from your cache using the Docker command by the registry login server name, repository name, and its desired tag. For example, to pull the image from the repository hello-world with desired tag latest for the registry login server myregistry.azurecr.io, run:

 docker pull myregistry.azurecr.io/hello-world:latest

Clean up resources

When no longer needed, delete the cache rule and credentials that you created.

1. To delete the cache rule, run az acr cache delete:

   az acr cache delete -r MyRegistry -n MyRule
   

2. To delete the credentials, run az acr credential-set delete:

   az acr credential-set delete -r MyRegistry -n MyDockerHubCredSet
   

Next steps

• Learn about troubleshooting issues with artifact caching.
• Learn how to enable artifact cache using the Azure portal.