Azure Container Registry Cache: Updated Guide with Docker Hub Integration

Some time ago, I wrote an article about Docker Hub rate limits and described ways to mitigate them. Unfortunately, the method I suggested using Azure Container Registry cache no longer works without authentication.

You can find more details about this in the Artifact cache in Azure Container Registry documentation, specifically in the Upstream support section.

Azure Container Registry supports only authenticated pulls to Docker Hub.

How to Enable Caching, the correct way

Let me walk you through enabling the cache. Here are the steps:

1. Create a free Docker Hub account if you don't have one yet

❗ Check your eligibility for a personal account first. You may need a paid subscription tier for Docker if you're not using it for personal or open source projects.

1. Create a personal access token in Docker Hub

2. Store your Docker Hub username and token credentials in Azure KeyVault

3. Create an Azure Container Registry credential cache to retrieve the KeyVault credentials for Docker Hub

4. Create an Azure Container Registry caching rule using that credential set

To simplify this process, I've created a GitHub repository with all the necessary automation.

dariuszparys / acr-cache-docker-images

Project Documentation for Bicep Project

Overview

This project configures an Azure Container Registry with Docker Hub credentials stored securely in Azure Key Vault, using managed identities for secure access.

Project Structure

The project is organized into the following directories and files:

• /src: Contains the main Bicep file and modules for resource deployment.
• /src/modules: Includes reusable Bicep modules for creating and managing Azure resources.
• deploy.sh: Script to automate the deployment process.
• .env: File for environment variables
• README.md: Project documentation and instructions.

Prerequisites

• Azure subscription
• Azure CLI installed
• Bicep CLI installed (if necessary)
• Docker Hub account

Deployment

1. Set environment variables:

export DOCKER_HUB_USERNAME="your-username"
export DOCKER_HUB_PAT="your-personal-access-token"

2. Configure parameters

Update main.bicepparam to your liking.

3. Run deployment:

chmod +x deploy.sh
./deploy.sh

Caching Repositories

Once this is set up we can now cache any public repository from docker hub in the Azure Container Registry. The following…

View on GitHub

Bicep Automation

The GitHub repository uses Bicep to automate resource creation in Azure. Before running it, you'll need a personal access token from Docker Hub.

Feel free to choose access permissions that make sense for your needs. Since I'm only working with public repositories, I selected that option.

Example Deployment

To test this, you can either export the variables DOCKER_HUB_USERNAME and DOCKER_HUB_PAT and run the deploy.sh script, or modify the src/main.bicepparam file.

The credentials will be stored in a newly created Azure KeyVault within the example resource group. You can modify the resource group name and location in the parameter file.

After deployment, you can link your public Docker Hub repository to Azure Container Registry by creating a cache with the credentials set from the Bicep deployment.

For example, to cache the public Python repository, you can

az acr cache create \
  --registry acrdemoxtpogsljytqrc \
  --name mypython \
  --source-repo docker.io/library/python \
  --target-repo python \
  --cred-set dockerhub

Once the cache rule is created we can evaluate it in the Azure Portal

To pull new images, simply reference your Azure Container Registry repository wherever you need it—whether in Azure Pipelines, GitHub Actions, or directly in the shell like

❯ az acr login --name acrdemoxtpogsljytqrc
Login Succeeded

~ took 5s
❯ docker pull acrdemoxtpogsljytqrc.azurecr.io/python
Using default tag: latest
latest: Pulling from python
Digest: sha256:d57ec66c94b9497b9f3c66f6cdddc1e4e0bad4c584397e0b57a721baef0e6fdc
Status: Image is up to date for acrdemoxtpogsljytqrc.azurecr.io/python:latest
acrdemoxtpogsljytqrc.azurecr.io/python:latest
~
❯ docker pull acrdemoxtpogsljytqrc.azurecr.io/python:alpine3.20
alpine3.20: Pulling from python
c4f340f38ec0: Download complete
0152682790bb: Download complete
bb4d68a0c460: Download complete
05da92a20133: Download complete
Digest: sha256:9ab3b6ef4afb7582afaa84e97d40a36f192595bb0578561c282cecc22a45de49
Status: Downloaded newer image for acrdemoxtpogsljytqrc.azurecr.io/python:alpine3.20
acrdemoxtpogsljytqrc.azurecr.io/python:alpine3.20

Thanks to the cache rule, the images automatically transfer to your Azure Container Registry and appear in your ACR repository.

Notes

In the shared GitHub project, I use a system-assigned identity, which requires splitting KeyVault creation and KeyVault Access Policies. This setup can be simplified once the corresponding issue is resolved to allow user-assigned managed identities.

I hope this helps!

Cover image by Photo by Guillaume Bolduc / Unsplash