Microsoft Azure — Azure Container Registry (ACR)

Azure is Microsoft's cloud computing platform offering over 200 services. This article covers azure container registry (acr) with production-ready configurations, best practices, and hands-on examples.

Why ACR Exists and When to Use It

Azure Container Registry (ACR) is a managed Docker registry service for storing and managing container images across all Azure deployment targets. Unlike Docker Hub, ACR integrates natively with Azure Active Directory, supports geo-replication for low-latency pulls, and provides advanced security features like image scanning and content trust. Use ACR when you need private, secure storage for your container images within the Azure ecosystem, especially for production workloads where you control access, retention, and compliance. Avoid ACR if you need a multi-cloud registry or prefer a vendor-neutral solution like Harbor. ACR shines in single-cloud Azure shops where tight integration with AKS, App Service, and Azure Pipelines reduces operational overhead.

#!/bin/bash
# Create an ACR instance with Premium SKU for geo-replication
az acr create \
  --resource-group my-rg \
  --name myacr \
  --sku Premium \
  --admin-enabled false \
  --location eastus

# Enable geo-replication to West Europe
az acr replication create \
  --registry myacr \
  --location westeurope

Authentication and Authorization: Beyond admin keys

Never use admin keys in production. They are static, shared secrets that bypass Azure AD and cannot be rotated without downtime. Instead, use Azure AD authentication with managed identities or service principals. For AKS clusters, assign the AcrPull role to the cluster's managed identity. For CI/CD pipelines, use a service principal with AcrPush role scoped to the registry. This enables token-based authentication that can be rotated and audited. For third-party tools that don't support Azure AD, use repository-scoped tokens (preview) to limit access to specific repositories. Always enforce Azure AD authentication and disable admin user after initial setup.

#!/bin/bash
# Assign AcrPull role to AKS cluster managed identity
AKS_CLUSTER_NAME="my-aks"
AKS_RESOURCE_GROUP="my-aks-rg"
ACR_NAME="myacr"

# Get the principal ID of the AKS cluster's kubelet identity
AKS_PRINCIPAL_ID=$(az aks show \
  --resource-group $AKS_RESOURCE_GROUP \
  --name $AKS_CLUSTER_NAME \
  --query identityProfile.kubeletidentity.objectId \
  --output tsv)

# Assign AcrPull role
az role assignment create \
  --assignee $AKS_PRINCIPAL_ID \
  --role AcrPull \
  --scope $(az acr show --name $ACR_NAME --query id --output tsv)

Building and Pushing Images with ACR Tasks

ACR Tasks provides on-demand container image building directly in Azure, eliminating the need for a local Docker daemon. Use it for automated builds triggered by Git commits or base image updates. ACR Tasks supports multi-step workflows, parallel builds, and can build from any Dockerfile. For production, define tasks with YAML that include unit tests, linting, and security scanning. Use the acr build command for ad-hoc builds, but prefer task definitions for repeatability. ACR Tasks also caches layers across builds, speeding up subsequent runs. Integrate with Azure Pipelines or GitHub Actions for full CI/CD, but ACR Tasks alone can handle simple build pipelines.

version: v1.1.0
steps:
  - build: -t {{.Values.image}} -f Dockerfile .
  - push:
      - {{.Values.image}}
  - cmd: echo "Build complete"

# Trigger on Git commits
# az acr task create --registry myacr --name build-task --file acr-task.yaml --context https://github.com/myorg/myrepo.git --git-access-token <token> --commit-trigger-enabled true

Geo-Replication for Global Deployments

Geo-replication replicates your container images across multiple Azure regions, enabling fast pulls from any location and providing disaster recovery. Enable it on Premium SKU only. When you push an image to one region, it's asynchronously replicated to all enabled regions. AKS clusters in different regions pull from their local replica, reducing latency and avoiding single points of failure. Monitor replication status via Azure Monitor or CLI. Be aware of eventual consistency: a newly pushed image may not be immediately available in all regions. For critical deployments, wait for replication confirmation before rolling out. Geo-replication also helps with data sovereignty requirements.

#!/bin/bash
# Add geo-replication to West Europe and Southeast Asia
az acr replication create --registry myacr --location westeurope
az acr replication create --registry myacr --location southeastasia

# List all replications
az acr replication list --registry myacr --output table

# Check replication status for a specific image
az acr manifest show-metadata --registry myacr --name myapp:latest --query "repositories[0].tags[0].digest"

Security: Image Scanning and Content Trust

ACR integrates with Microsoft Defender for Cloud to scan images for vulnerabilities on push. Enable this for all repositories. Additionally, use content trust (Notary v1) to sign images and verify publisher identity. Content trust ensures only signed images are pulled, preventing tampering. For production, enforce that only signed images can be deployed by configuring AKS admission controllers or using Azure Policy. Also, enable quarantine: when a vulnerability is found, the image is marked as untrusted and cannot be pulled until resolved. Regularly review scan results and set up alerts for critical vulnerabilities. Rotate signing keys periodically.

#!/bin/bash
# Enable Defender for Cloud on ACR
az acr update --name myacr --resource-group my-rg --enable-scanning true

# Enable content trust
az acr config content-trust update --registry myacr --status enabled

# Sign an image (requires Docker Content Trust)
export DOCKER_CONTENT_TRUST=1
docker push myacr.azurecr.io/myapp:latest

# Verify signature
docker trust inspect myacr.azurecr.io/myapp:latest

Automated Cleanup and Retention Policies

Without cleanup, ACR repositories accumulate stale images, consuming storage and increasing costs. Use retention policies to automatically delete untagged manifests after a specified number of days. For tagged images, implement a custom cleanup strategy using ACR Tasks or Azure Automation. A common approach is to keep only the last N versions per repository. Use the acr purge command in a scheduled task to remove old images. Be careful not to delete images currently in use by running containers. Tag images with build numbers or dates to facilitate selective deletion. Monitor storage usage and set alerts for unexpected growth.

version: v1.1.0
steps:
  - cmd: |
      az acr run --registry myacr --cmd "acr purge --filter 'myapp:.*' --ago 30d --untagged" /dev/null

# Schedule task to run daily at 2 AM
# az acr task create --registry myacr --name cleanup --file cleanup-task.yaml --schedule "0 2 * * *"

Integrating ACR with AKS for Seamless Deployments

The most common production pattern is ACR feeding images to AKS. Use the AKS cluster's managed identity to pull images from ACR (as shown earlier). For deployments, reference images by digest rather than tag to ensure immutability. Use Helm charts or Kustomize to manage deployments, and update the image digest in your CI/CD pipeline. For blue-green or canary deployments, leverage ACR's repository structure to separate versions. Monitor pull latency and set up Azure Monitor alerts for failed pulls. Consider using ACR Connected Registry for edge deployments where connectivity is intermittent.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: myacr.azurecr.io/myapp@sha256:abc123...
        ports:
        - containerPort: 8080
      imagePullSecrets:
      - name: acr-auth  # Only needed if not using managed identity

Monitoring and Troubleshooting ACR

Monitor ACR health using Azure Monitor metrics: pull/push latency, storage usage, and authentication failures. Set up alerts for high latency or failed requests. Enable diagnostic logs to capture all registry operations, including authentication attempts and image pulls. Use Log Analytics to query logs for troubleshooting. Common issues: authentication failures (check role assignments), pull timeouts (check network latency or geo-replication status), and storage limits (monitor usage and set alerts). For slow pulls, ensure the AKS cluster is in the same region as the ACR replica. Use az acr check-health for a quick diagnostic.

#!/bin/bash
# Run health check
az acr check-health --name myacr --yes

# Query logs for failed pulls
az monitor log-analytics query \
  --workspace my-workspace \
  --query "ContainerRegistryLoginEvents | where ResultType != 'Success' | project TimeGenerated, Identity, ResultDescription"

Cost Optimization and SKU Selection

ACR pricing is based on SKU, storage, and data transfer. Basic SKU is for development only (10 GB storage, no geo-replication). Standard SKU (100 GB) is for low-volume production. Premium SKU (500 GB) is for production with geo-replication, content trust, and higher throughput. Optimize costs by: using retention policies to delete unused images, choosing the right SKU based on storage needs, and minimizing cross-region data transfer by co-locating registries and compute. For high-volume pulls, consider using a content delivery network (CDN) or Azure Front Door to cache images. Monitor storage growth and scale up SKU only when needed.

#!/bin/bash
# Estimate monthly cost for Premium SKU with 200 GB storage
az acr show-usage --name myacr --resource-group my-rg --output table

# Calculate cost: Premium SKU ~$0.60/day + storage $0.10/GB/month + data transfer $0.01/GB
# Example: 200 GB storage + 500 GB egress = $0.60*30 + 200*0.10 + 500*0.01 = $18 + $20 + $5 = $43/month

Disaster Recovery and Backup Strategies

ACR geo-replication provides built-in disaster recovery for the registry itself. However, you also need to protect against accidental deletion of images or the entire registry. Enable soft delete (preview) to recover deleted images within a retention period. Export critical images to another Azure region or another cloud as a backup. Use Azure Backup for the registry metadata, but note that images themselves are not backed up by default. For compliance, export image manifests and layers to Azure Blob Storage periodically. Test your disaster recovery plan by simulating a regional failure and verifying that your AKS clusters can pull from the secondary replica.

#!/bin/bash
# Export all images from ACR to another registry (e.g., in another region)
az acr import \
  --source myacr.azurecr.io/myapp:latest \
  --target myacr-backup.azurecr.io/myapp:latest \
  --registry myacr-backup

# Enable soft delete
az acr config soft-delete update --registry myacr --status enabled --days 7

Advanced: Connected Registry and Edge Deployments

ACR Connected Registry extends ACR to on-premises or edge environments with intermittent connectivity. It acts as a local cache that synchronizes images from the cloud registry. Use it for IoT, retail, or manufacturing scenarios where pulling from the cloud is slow or unreliable. Deploy the connected registry agent on a local server, configure synchronization rules, and manage it via Azure. The connected registry supports read-only (pull) and read-write (push) modes. For production, ensure the local cache has enough storage and monitor synchronization status. Failover to cloud registry if local cache is outdated.

#!/bin/bash
# Create a connected registry (preview)
az acr connected-registry create \
  --registry myacr \
  --name my-edge-registry \
  --repository "myapp/*" \
  --sync-token my-token \
  --sync-schedule "0 */6 * * *"

# Deploy the connected registry agent on edge device
# (requires Docker or Kubernetes)
docker run -d \
  --name acr-connected-registry \
  -e ACR_REGISTRY_NAME=myacr \
  -e ACR_CONNECTED_REGISTRY_NAME=my-edge-registry \
  -e ACR_SYNC_TOKEN=my-token \
  -p 8080:8080 \
  mcr.microsoft.com/acr/connected-registry:latest

Putting It All Together: Production CI/CD Pipeline

A production-grade CI/CD pipeline using ACR integrates source control, automated builds, security scanning, and deployment. Use Azure Pipelines or GitHub Actions to trigger ACR Tasks on commits. After build, scan the image with Defender for Cloud. If vulnerabilities are found, fail the pipeline. Sign the image with content trust. Then, update the Kubernetes deployment manifest with the new image digest and apply it to AKS. Use staged rollouts with canary deployments. Monitor the rollout with Azure Monitor and roll back if errors exceed thresholds. This end-to-end automation ensures only secure, signed images reach production.

trigger:
  branches:
    include:
      - main

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: AzureCLI@2
  inputs:
    azureSubscription: 'my-service-connection'
    scriptType: 'bash'
    scriptLocation: 'inlineScript'
    inlineScript: |
      az acr build --registry myacr --image myapp:$(Build.BuildId) .
      az acr scan --registry myacr --image myapp:$(Build.BuildId)
      # Sign image (requires DCT)
      export DOCKER_CONTENT_TRUST=1
      docker trust sign myacr.azurecr.io/myapp:$(Build.BuildId)
- task: KubernetesManifest@0
  inputs:
    action: 'deploy'
    kubernetesServiceConnection: 'my-aks-connection'
    namespace: 'production'
    manifests: 'deployment.yaml'
    imagePullSecrets: |
      acr-auth
    containers: |
      myacr.azurecr.io/myapp:$(Build.BuildId)

Artifact Cache: Pull-Through Proxy for Public and Private Registries

ACR Artifact Cache acts as a pull-through proxy for container images from upstream registries like Docker Hub, Microsoft Artifact Registry (MCR), Quay, GitHub Container Registry, and Google Container Registry. Define cache rules that map an upstream repository to a local ACR repository. When a client pulls an image through the cache, ACR proxies the request to the upstream registry and streams the content back while asynchronously copying the image to local storage. Subsequent pulls are served directly from ACR with no upstream traffic. This mitigates Docker Hub rate limits, improves reliability (cached images are available even if the upstream is down), and reduces latency. Use wildcard rules (e.g., contoso.azurecr.io/ => mcr.microsoft.com/) to cache entire namespaces. For authenticated registries like Docker Hub, create a credential set for authentication. For production, configure cache rules for all external images your workloads depend on. Enable geo-replication on your ACR to propagate cached images to all regions. Monitor cache hit ratio via Azure Monitor metrics to understand effectiveness.

#!/bin/bash
# Create a credential set for Docker Hub (authenticated pulls)
az acr credential-set create \
  --registry myacr \
  --name docker-hub-creds \
  --login-server docker.io \
  --username "my-docker-hub-user" \
  --password "my-docker-hub-token"

# Create a cache rule for nginx from Docker Hub
az acr cache create \
  --registry myacr \
  --name nginx-cache \
  --source-repo docker.io/library/nginx \
  --target-repo nginx \
  --credential-set docker-hub-creds

# Wildcard cache rule for all MCR images
az acr cache create \
  --registry myacr \
  --name mcr-all \
  --source-repo mcr.microsoft.com/* \
  --target-repo mcr/*

Network Security: Private Endpoints, Firewall Rules, and Service Tags

For production security, restrict network access to your ACR using Private Endpoints (Premium SKU) or IP firewall rules. Private Endpoints assign private IP addresses to the registry from your virtual network, eliminating exposure to the public internet. Traffic stays on the Microsoft backbone network. Configure DNS with a private zone (privatelink.azurecr.io) so the registry FQDN resolves to the private IP. Each geo-replica adds dedicated data endpoints (..data.azurecr.io) — plan subnet sizing accordingly (minimum /27, ideally /24 for geo-replicated registries). For clients outside Azure (on-premises, IoT), use IP firewall rules on the public endpoint. Lock down access to specific IP ranges or use the AzureContainerRegistry service tag. Enable dedicated data endpoints to replace the broad *.blob.core.windows.net wildcard with scoped firewall rules for your specific registry's data endpoints, mitigating data exfiltration risks. For trusted Azure services (Defender for Cloud, ACR Tasks), enable the 'Allow trusted services' setting to bypass network rules. When using Private Endpoints, disable public network access for defense-in-depth.

#!/bin/bash
# Disable public network access
az acr update --name myacr --public-network-enabled false

# Create a private endpoint
az network private-endpoint create \
  --name myacr-pe \
  --resource-group my-rg \
  --vnet-name my-vnet \
  --subnet my-subnet \
  --private-connection-resource-id $(az acr show --name myacr --query id -o tsv) \
  --group-ids registry \
  --connection-name myacr-connection

# Create private DNS zone
az network private-dns zone create \
  --resource-group my-rg \
  --name privatelink.azurecr.io

# Link to virtual network
az network private-dns link vnet create \
  --resource-group my-rg \
  --zone-name privatelink.azurecr.io \
  --name myacr-dns-link \
  --virtual-network my-vnet \
  --registration-enabled false