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.

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

Prerequisites

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. 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. Run az acr credential set update to update the username or password Key Vault secret ID on the credential set:

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

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

Create a cache rule

Next, create and configure the cache rule that pulls 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 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

To pull an image from your cache, use the Docker command and provide the registry sign-in server name, repository name, and its desired tag. For example, to pull an image from the repository hello-world with desired tag latest for the registry sign-in 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