Manage public content with Azure Container Registry

Article
10/28/2024

This article is an overview of practices and workflows to use a local registry such as an Azure container registry to maintain copies of public content, such as container images in Docker Hub.

Risks with public content

Your environment may have dependencies on public content such as public container images, Helm charts, Open Policy Agent (OPA) policies, or other artifacts. For example, you might run nginx for service routing or docker build FROM alpine by pulling images directly from Docker Hub or another public registry.

Without proper controls, having dependencies on public registry content can introduce risks to your image development and deployment workflows. To mitigate the risks, keep local copies of public content when possible. For details, see the Open Container Initiative blog.

Authenticate with Docker Hub

As a first step, if you currently pull public images from Docker Hub as part of a build or deployment workflow, we recommend that you authenticate using a Docker Hub account instead of making an anonymous pull request.

When making frequent anonymous pull requests you might see Docker errors similar to ERROR: toomanyrequests: Too Many Requests. or You have reached your pull rate limit. Authenticate to Docker Hub to prevent these errors.

Note

Effective November 2, 2020, download rate limits apply to anonymous and authenticated requests to Docker Hub from Docker Free Plan accounts and are enforced by IP address and Docker ID, respectively.

When estimating your number of pull requests, take into account that when using cloud provider services or working behind a corporate NAT, multiple users will be presented to Docker Hub in aggregate as a subset of IP addresses. Adding Docker paid account authentication to requests made to Docker Hub will avoid potential service disruptions due to rate-limit throttling.

For details, see Docker pricing and subscriptions and the Docker Terms of Service.

Docker Hub access token

Docker Hub supports personal access tokens as alternatives to a Docker password when authenticating to Docker Hub. Tokens are recommended for automated services that pull images from Docker Hub. You can generate multiple tokens for different users or services, and revoke tokens when no longer needed.

To authenticate with docker login using a token, omit the password on the command line. When prompted for a password, enter the token instead. If you enabled two-factor authentication for your Docker Hub account, you must use a personal access token when logging in from the Docker CLI.

Authenticate from Azure services

Several Azure services including App Service and Azure Container Instances support pulling images from public registries such as Docker Hub for container deployments. If you need to deploy an image from Docker Hub, we recommend that you configure settings to authenticate using a Docker Hub account. Examples:

App Service

Image source: Docker Hub
Repository access: Private
Login: <Docker Hub username>
Password: <Docker Hub token>

For details, see Docker Hub authenticated pulls on App Service.

Azure Container Instances

Image source: Docker Hub or other registry
Image type: Private
Image registry login server: dockerhub.azk8s.cn
Image registry user name: <Docker Hub username>
Image registry password: <Docker Hub token>
Image: dockerhub.azk8s.cn/<repo name>:<tag>

Configure Artifact Cache to consume public content

The best practice for consuming public content is to combine registry authentication and the Artifact Cache feature. You can use Artifact Cache to cache your container artifacts into your Azure Container Registry even in private networks. Using Artifact Cache not only protects you from registry rate limits, but dramatically increases pull reliability when combined with Geo-replicated ACR to pull artifacts from whichever region is closest to your Azure resource. In addition, you can also use all the security features ACR has to offer, including private networks, firewall configuration, Service Principals, and more. For complete information on using public content with ACR Artifact Cache, check out the Artifact Cache tutorial.

Import images to an Azure container registry

To begin managing copies of public images, you can create an Azure container registry if you don't already have one. Create a registry using the Azure CLI, Azure portal, Azure PowerShell, or other tools.

Azure CLI
Azure PowerShell

As a recommended one-time step, import base images and other public content to your Azure container registry. The az acr import command in the Azure CLI supports image import from public registries such as Docker Hub and Azure Container Registry and from other private container registries.

az acr import doesn't require a local Docker installation. You can run it with a local installation of the Azure CLI. It supports images of any OS type, multi-architecture images, or OCI artifacts such as Helm charts.

Depending on your organization's needs, you can import to a dedicated registry or a repository in a shared registry.

az acr import \
  --name myregistry \
  --source dockerhub.azk8s.cn/library/hello-world:latest \
  --image hello-world:latest \
  --username <Docker Hub username> \
  --password <Docker Hub token>

As a recommended one-time step, import base images and other public content to your Azure container registry. The Import-AzContainerRegistryImage command in the Azure PowerShell supports image import from public registries such as Docker Hub and Azure Container Registry and from other private container registries.

Import-AzContainerRegistryImage doesn't require a local Docker installation. You can run it with a local installation of the Azure PowerShell. It supports images of any OS type, multi-architecture images, or OCI artifacts such as Helm charts.

Depending on your organization's needs, you can import to a dedicated registry or a repository in a shared registry.

$Params = @{
   SourceImage       = 'library/busybox:latest' 
   ResourceGroupName = $resourceGroupName 
   RegistryName      = $RegistryName 
   SourceRegistryUri = 'dockerhub.azk8s.cn'
   TargetTag         = 'busybox:latest'
}
Import-AzContainerRegistryImage @Params

Credentials are required if the source registry is not available publicly or the admin user is disabled.

Update image references

Developers of application images should ensure that their code references local content under their control.

Update image references to use the private registry. For example, update a FROM baseimage:v1 statement in a Dockerfile to FROM myregistry.azurecr.cn/mybaseimage:v1
Configure credentials or an authentication mechanism to use the private registry. The exact mechanism depends on the tools you use to access the registry and how you manage user access.
- If you use a Kubernetes cluster or Azure Kubernetes Service to access the registry, see the authentication scenarios.
- Learn more about options to authenticate with an Azure container registry.

Automate application image updates

Expanding on image import, set up an Azure Container Registry task to automate application image builds when base images are updated. An automated build task can track both base image updates and source code updates.

For a detailed example, see How to consume and maintain public content with Azure Container Registry Tasks.