Azure Container Registry Guide: Architecture, Security, and Best Practices

Containerized applications have become the default deployment model for cloud-native systems. They provide consistency across environments, efficient resource utilization, and simplified dependency management. But containers introduce a new challenge: where do you store the container images themselves?

A container image is a lightweight, standalone, executable package that includes everything needed to run a piece of software: code, runtime, system tools, libraries, and settings. These images can be large—often hundreds of megabytes or even gigabytes. They need to be stored somewhere accessible, versioned, and distributed to the systems that run them.

Public registries like Docker Hub provide a convenient place to store and share images. But for production workloads, organizations typically need a private registry. A private registry provides:

• Control over access – Only authorized users and systems can pull images
• Security – Images are stored in your own environment, not a public service
• Performance – Images are stored close to your deployment targets
• Integration – Deep integration with your cloud infrastructure and CI/CD pipelines
• Compliance – Images remain within your data residency and compliance boundaries

Azure Container Registry (ACR) is Microsoft's managed private registry service for container images and related artifacts. It is based on the open-source Docker platform and integrates deeply with Azure services like Azure Kubernetes Service (AKS), Azure Container Apps, and Azure App Service.

ACR is more than simply "a place to store Docker images." It provides:

• Integrated authentication with Microsoft Entra ID
• Geo-replication for global distribution and reliability
• Virtual network configuration with Private Link
• Tag locking and image retention policies
• Support for OCI artifacts including Helm charts
• Automated vulnerability scanning
• ACR Tasks for building images in Azure

ACR fits into an Azure architecture as the secure, private source of container images for all your containerized workloads. Whether you're running microservices on AKS, serverless containers on Container Apps, or custom applications on Azure VMs, ACR provides the registry layer that makes container deployment secure, reliable, and scalable.

What Is Azure Container Registry?

Azure Container Registry is a managed, private Docker registry service that stores and distributes container images and related artifacts. Unlike public registries such as Docker Hub, ACR provides direct control over access, geo-replication for global distribution, and integration with Azure services.

Core concepts

Registry – The top-level resource that hosts all container content. Each registry has a unique login server URL in the format <registry-name>.azurecr.io. A registry contains multiple repositories and provides authentication, access control, and management capabilities.

Repository – A collection of container images or other artifacts in a registry that have the same name but different tags. For example, a repository named inference-api contains all versions of an inference API image.

Image – A container image is a read-only template with instructions for creating a container. Images are composed of layers and identified by a manifest.

Tag – A human-readable reference that identifies a specific version of an artifact within a repository. The format repository:tag provides a human-readable reference.

Manifest – A JSON file that describes the image, including its layers and configuration. The manifest uniquely identifies the image using a digest (SHA-256 hash).

Layer – Container images are composed of one or more layers. Each layer corresponds to an instruction in the Dockerfile. Layers are shared across images, improving storage efficiency.

Registry vs. repository

This distinction is important: a registry is the service (ACR instance) that stores images. A repository is a collection of images with the same name within a registry. One registry can have many repositories. One repository can have many tagged images.

ACR vs. Docker Hub

Aspect	Azure Container Registry	Docker Hub
Hosting	Azure-managed, private	Public or Docker-managed private
Authentication	Microsoft Entra ID, managed identities	Docker ID, personal access tokens
Private repositories	Yes (all private by default)	Limited on free plan
Azure integration	Deep (AKS, Container Apps, App Service)	Limited
Geo-replication	Yes (Premium tier)	No
Security scanning	Yes (Microsoft Defender)	Limited
Rate limits	Based on SKU and throughput	Strict limits on free plan
Best for	Enterprise Azure workloads	Public images, open-source, getting started

Azure Container Registry at a Glance

Capability	Description
Private container image storage	Store container images securely in your Azure subscription
Image repositories	Organize images by name with versioned tags
Image versioning and tags	Use semantic versioning, Git SHA, or environment tags
Authentication	Microsoft Entra ID, service principals, managed identities, admin account
Authorization	Azure RBAC with built-in roles (AcrPull, AcrPush, AcrDelete)
Image push/pull	Standard Docker CLI and OCI tooling support
Geo-replication	Premium tier: replicate images across Azure regions
Private endpoints	Premium tier: connect privately using Azure Private Link
Network access control	IP firewall rules, virtual network service endpoints, private endpoints
Image security	Vulnerability scanning with Microsoft Defender for Cloud
Webhooks/events	Trigger actions on image push, delete, or other events
CI/CD integration	GitHub Actions, Azure Pipelines, and other CI/CD tools
AKS integration	Seamless authentication and image pulling
Artifact support	Docker images, Helm charts, OCI artifacts

ACR Architecture

Major components and relationships

Azure Subscription
  └── Resource Group
        └── Container Registry (ACR)
              ├── Login Server (registryname.azurecr.io)
              ├── Repositories
              │     ├── myapp/web
              │     │     ├── :latest
              │     │     ├── :v1.2.3
              │     │     └── :abc1234
              │     └── myapp/api
              │           ├── :latest
              │           └── :v2.0.0
              ├── Replications (Premium tier)
              │     ├── Region 1 (home)
              │     └── Region 2 (geo-replica)
              ├── Private Endpoints (Premium tier)
              ├── Webhooks
              └── Azure RBAC assignments

Typical flow

Developer / CI pipeline
        ↓
Build container image (docker build)
        ↓
Authenticate to ACR (az acr login / docker login)
        ↓
Tag image (docker tag)
        ↓
Push image (docker push)
        ↓
ACR repository stores image
        ↓
[Vulnerability scan (Microsoft Defender)]
        ↓
Workload pulls image (AKS / Container Apps / VM)
        ↓
Container runs

Registry hierarchy

ACR uses a three-level hierarchy to organize content:

1. Registry – The top-level resource; hosts all repositories
2. Repository – A collection of images with the same name
3. Artifact – A specific image version identified by a tag and manifest

How ACR stores images

Container images and artifacts are composed of one or more layers. Each layer corresponds to an instruction in the Dockerfile. Registries store layers efficiently—common layers are shared across different images and repositories. This means if multiple images use the same base layer (e.g., ubuntu:22.04), that layer is stored only once.

Each image is identified by a manifest that describes the image, its layers, and configuration. The manifest is referenced by a digest (SHA-256 hash), which uniquely identifies the image content. Tags provide human-readable references to specific manifests.

Geo-replication architecture

For Premium tier registries, ACR supports geo-replication with an active-active model:

• All geo-replicas are active and writable—you can push, pull, and delete images from any geo-replica
• ACR uses eventual consistency: after you push or delete an image in any geo-replica, ACR eventually replicates the change to all geo-replicas
• A single global endpoint (myregistry.azurecr.io) routes requests to the best geo-replica based on network performance

Data plane vs. management plane

ACR separates management operations (creating/deleting registries, configuring networking) from data operations (pushing and pulling images). This separation allows fine-grained access control—you can grant someone permission to push images without giving them permission to delete the registry.

ACR SKUs and Choosing the Right Tier

Azure Container Registry offers three pricing plan options: Basic, Standard, and Premium. Each SKU provides the same programmatic capabilities and data plane APIs, but differs in storage, throughput, and available features.

Comparison table

Resource	Basic	Standard	Premium
Included storage (GiB)	10	100	500
Storage limit (TiB)	40	40	100
Image layer size max (GiB)	200	200	200
Manifest size max (MiB)	4	4	4
Webhooks	2	10	500
Private endpoints	Not available	Not available	Up to 200
Public IP network rules	Not available	Not available	Up to 200
Geo-replication	Not available	Not available	✅
Zone redundancy	✅ (default)	✅ (default)	✅ (default)

When to choose each SKU

Basic – A cost-optimized entry point for developers learning Azure Container Registry. Basic registries have most of the same capabilities as Standard and Premium, including Microsoft Entra authentication integration, image deletion, and webhooks. The included storage and image throughput are best suited for low-usage environments. Use Basic for development, testing, and learning.

Standard – Standard registries offer the same capabilities as Basic with higher included storage and image throughput. Standard registries meet the needs of many production scenarios. Use Standard for most production workloads that don't require Premium features.

Premium – Premium registries provide the highest included storage and concurrent operations, enabling high-volume scenarios. In addition to higher image throughput, Premium adds:

• Geo-replication for managing a single registry across regions with high availability
• Private endpoints with Private Link to restrict registry access
• Higher API concurrency and bandwidth throughput for large-scale parallel deployments
• Content trust for image signing
• Dedicated data endpoints for tightly scoped firewall rules

Use Premium for mission-critical production workloads, multi-region deployments, and enterprise security requirements.

Important notes

• All SKUs are zone-redundant by default in supported regions
• All SKUs benefit from fully Azure-managed image storage
• Storage beyond the included amount is charged at a per-GB rate
• You can upgrade from Basic to Standard to Premium at any time
• Downgrading from Premium may require removing Premium-only features first

Repositories, Images, Tags, and Manifests

Repository naming

Repository names can contain lowercase alphanumeric characters, periods, hyphens, underscores, and forward slashes. Use forward slashes to create namespaces for organization:

marketing/campaign10-18/web:v2
marketing/campaign10-18/api:v3
product-returns/web-submission:20230604

Namespaces help with organization and access control—you can grant teams permission to push images only to their namespace while restricting access to production images.

Tagging strategies

You can assign one or more tags to a single artifact. How you tag container images depends on your development or deployment context.

Recommended production tagging strategies:

Strategy	Example	Use Case
Semantic versioning	v1.2.3, v2.0.0	Release versions
Git commit SHA	abc1234, a1b2c3d	Unique build identification
Environment tags	production, staging	Environment-specific deployments
Date-based	2024-01-15, 2024-01-15-1200	Timestamped builds

Avoid relying on latest – The latest tag is the default if no tag is specified. However, latest is mutable and provides no versioning guarantees. Using latest in production makes it difficult to determine which version is actually deployed and impossible to roll back reliably.

Immutable versioning: Use immutable tags (e.g., Git SHA or semantic version) for production images. This ensures each deployment uses a specific, identifiable image version.

Multi-architecture images: ACR supports multi-architecture images through manifests that reference architecture-specific image layers (e.g., linux/amd64, linux/arm64). A single tag can point to a manifest list that serves the appropriate architecture.

Untagging: You can "untag" an image by deleting all its tags while preserving the image's data (layers) in the registry.

Manifests and digests

Each image is identified by a manifest that describes the image, its layers, and configuration. The manifest is referenced by a digest (SHA-256 hash) that uniquely identifies the image content.

Using the digest (e.g., myregistry.azurecr.io/myapp@sha256:abc123...) provides an immutable reference that never changes, even if the tag is moved.

Authentication and Authorization

Azure Container Registry supports multiple authentication methods. For most scenarios, use Microsoft Entra ID-based methods.

Authentication methods

Method	How to Authenticate	Scenario	RBAC Support
Individual Microsoft Entra identity	az acr login or Connect-AzContainerRegistry	Developers, testers interactive push/pull	✅
Microsoft Entra service principal	docker login with service principal credentials	Unattended push/pull from CI/CD pipelines	✅
Managed identity for Azure resources	docker login with managed identity	Azure CI/CD pipelines, automated pushes to Azure services	✅
Admin user	docker login with username/password	Individual developers, portal-based deployment	❌ (always full push/pull)
Non-Microsoft Entra token-based repository permissions	docker login with token	Repository-scoped interactive operations	❌

Microsoft Entra ID authentication (recommended)

For most scenarios, authenticate using one of the Microsoft Entra ID-based methods:

Individual login: Use az acr login with your Azure credentials. This provides Azure role-based access control (RBAC) for registry operations.

Service principal: Use a Microsoft Entra service principal for unattended or "headless" authentication. Service principal credentials have a default validity of one year.

Managed identity: Use a managed identity for Azure resources in CI/CD pipelines. This is the most secure approach for automated scenarios.

Azure RBAC roles

ACR provides built-in Azure roles for granular access control:

Role	Permissions
AcrPull	Pull images from the registry
AcrPush	Push images to the registry (includes AcrPull)
AcrDelete	Delete images from the registry
AcrImageSigner	Sign images with content trust
Owner / Contributor	Full management of the registry resource

Least privilege

Apply least-privilege principles:

• Developers need AcrPush for their development registry, but only AcrPull for production
• CI/CD pipelines need AcrPush for the build stage and AcrPull for deployment
• AKS clusters only need AcrPull

Admin account warning

The ACR admin account provides full push and pull access to the registry with a single set of credentials. It is not recommended for multiple users or production scenarios. Avoid using the admin account for production workloads. Use Microsoft Entra ID-based authentication instead.

Authentication vs. authorization

• Authentication – Proving who you are (Microsoft Entra ID, service principal, managed identity)
• Authorization – Determining what you can do (RBAC roles like AcrPull, AcrPush)

ACR supports both. Authentication establishes identity; authorization grants permissions based on that identity.

Developer Workflow

Typical developer workflow

A developer working with ACR follows these steps:

1. Build a Docker image

docker build -t myapp .

2. Authenticate to ACR

az acr login --name myregistry

This authenticates using your Microsoft Entra identity and Azure RBAC permissions.

3. Tag the image

docker tag myapp myregistry.azurecr.io/myapp:v1.0.0

4. Push the image

docker push myregistry.azurecr.io/myapp:v1.0.0

5. Verify the repository

az acr repository list --name myregistry --output table
az acr repository show-tags --name myregistry --repository myapp --output table

6. Pull the image (on another system or deployment target)

docker pull myregistry.azurecr.io/myapp:v1.0.0

7. Run the container

docker run myregistry.azurecr.io/myapp:v1.0.0

Authentication options for developers

The recommended authentication method for developers is az acr login with your Microsoft Entra identity. This provides Azure RBAC and doesn't require managing credentials.

Alternatively, you can use docker login with a service principal or admin credentials, but these approaches are less secure for interactive development.

ACR Tasks

Azure Container Registry Tasks (ACR Tasks) allows you to build container images in Azure. You can build on-demand or fully automate builds with triggers such as source code commits and base image updates.

ACR Tasks is particularly useful for:

• Cloud-native builds: Offload docker build operations to Azure
• Base image updates: Automatically rebuild application images when base images are updated
• Source code integration: Automate image builds when code is committed to Git

ACR and Azure Kubernetes Service

ACR and AKS are designed to work together seamlessly. AKS pulls container images from ACR to run application pods.

Integration

The AKS-to-ACR integration assigns the AcrPull role (or Container Registry Repository Reader role for ABAC-enabled registries) to the kubelet identity associated with the AKS cluster. This allows the AKS nodes to pull images from the registry.

In Azure CLI, use --attach-acr when creating an AKS cluster:

az aks create --resource-group myrg --name myaks --attach-acr myregistry

In Terraform, assign the AcrPull role to the AKS kubelet managed identity.

How AKS pulls images

Developer / CI
    ↓ (push)
ACR repository
    ↓ (pull, authenticated by kubelet managed identity)
AKS node
    ↓ (runs container)
Pod

The AKS kubelet managed identity uses the AcrPull role to authenticate to ACR. No credentials need to be stored in the cluster.

Important considerations

Same tenant requirement: The AKS cluster and ACR registry must be in the same Microsoft Entra tenant for the AKS-to-ACR integration to work.

Cross-tenant authentication: If AKS and ACR are in different tenants, you can configure cross-tenant authentication using service principal credentials.

Image pull failures: If an AKS node cannot pull an image, the pod enters ImagePullBackOff state. Common causes include:

• Insufficient AcrPull permissions
• Registry network restrictions (private endpoint, firewall)
• Image tag doesn't exist
• Registry name is incorrect

ACR and CI/CD

ACR integrates with modern CI/CD pipelines to provide a secure container image build and deployment workflow.

Typical CI/CD pipeline

Source code (Git)
    ↓
CI Pipeline (GitHub Actions / Azure DevOps)
    ↓
Build container image
    ↓
Run tests
    ↓
Security scan (vulnerability scanning)
    ↓
Push to ACR
    ↓
CD Pipeline
    ↓
Deploy to AKS / Container Apps / App Service
    ↓
Verify deployment

Authentication for CI/CD

For secure CI/CD authentication, use one of these approaches:

Workload identity federation: The recommended approach for GitHub Actions and Azure DevOps. It uses OpenID Connect (OIDC) to authenticate to Azure without storing secrets. Workload identity federation tokens are short-lived (typically minutes to hours) and are automatically rotated.

Service principal: Use a Microsoft Entra service principal with AcrPush permissions. Service principal credentials have a default validity of one year.

Managed identity: When running CI/CD on Azure resources (e.g., Azure DevOps self-hosted agents on Azure VMs), use managed identity.

GitHub Actions integration

GitHub Actions can authenticate to ACR using OIDC federation or service principal credentials. The workflow builds the container image, pushes it to ACR, and deploys it to AKS.

Azure Pipelines integration

Azure Pipelines provides native tasks for building and pushing container images to ACR. Use the Docker@2 task with the containerRegistry service connection.

Image Security

ACR provides multiple layers of image security.

Vulnerability scanning

Microsoft Defender for Cloud automatically scans container images stored in ACR for Common Vulnerabilities and Exposures (CVEs). When your CI/CD pipeline pushes a new image, Microsoft Defender immediately scans the image.

Within minutes, you receive a security report showing which base image layers contain vulnerabilities, their severity ratings (critical, high, medium, low), and specific remediation steps.

How scanning works:

• Registry vulnerability assessment identifies vulnerabilities in container images stored in ACR before deployment
• Images are scanned within 24 hours
• Scanning supports images in ACR only

Best practice: Integrate vulnerability scanning into your CI/CD pipeline. Block deployments of images with critical or high-severity vulnerabilities.

Content trust

Content trust allows you to sign images to verify their authenticity and integrity. When content trust is enabled:

• Images must be signed to be pushed
• Only signed images can be pulled
• Signing requires the AcrImageSigner role

Content trust is available in the Premium tier.

Trusted images policy

ACR provides trusted images policy enforcement at deploy time. You can enforce a single image integrity policy bound to ACR, with platform-native enforcement.

Security best practices

• Scan images before deployment – Use Microsoft Defender for Cloud vulnerability scanning
• Remove vulnerable images – Delete or untag images with critical vulnerabilities
• Use trusted registries – Only pull images from trusted sources
• Sign images – Use content trust for production images
• Keep images small – Remove unnecessary layers and use minimal base images
• Disable local authentication – Disable admin user, repository-scoped access tokens, and anonymous pull to ensure registries exclusively require Microsoft Entra identities

Private Access and Networking

Network access models

ACR supports multiple network access configurations:

Public endpoint (default) – The registry is accessible from the internet with optional IP firewall rules.

Service endpoint – Restrict access to the registry from specific Azure virtual networks using VNet service endpoints.

Private endpoint – Assign private IP addresses from your virtual network to the registry endpoints using Azure Private Link. Network traffic between clients on the virtual network and the registry's private endpoints traverses the virtual network and a private link on the Microsoft backbone network.

Private endpoints

Private endpoints are available in the Premium tier. They provide:

• Network isolation – The registry is only accessible from your virtual network
• No public exposure – No public endpoint is exposed
• Private IP address – The registry is accessed via a private IP in your VNet
• DNS configuration – DNS settings resolve the registry name to the private IP address

Azure Private Link is the most secure way to control network access between clients and the registry, as network traffic is limited to the Azure Virtual Network using private IP addresses.

IP firewall rules

Premium tier supports up to 200 public IP network rules. You can restrict access to specific IP addresses or ranges.

Dedicated data endpoints

Dedicated data endpoints in ACR enable tightly scoped client firewall rules to specific registries, minimizing data exfiltration concerns.

DNS considerations for private endpoints

When using private endpoints, configure DNS settings so that the registry's FQDN resolves to the private IP address. This typically requires:

• A private DNS zone linked to your virtual network
• An A record mapping the registry name to the private endpoint IP

Enterprise network architecture

For enterprise environments where container images must not traverse unrestricted public paths:

1. Deploy ACR with private endpoints
2. Deploy AKS as a private cluster in the same VNet
3. Configure DNS for private resolution
4. Use Azure Firewall or Network Security Groups for additional control

Dedicated data endpoints for data exfiltration prevention

For highly regulated environments, dedicated data endpoints allow you to scope firewall rules to specific registries, minimizing the risk of data exfiltration. Without dedicated data endpoints, a registry's data endpoint is shared across all registries in a region, making it difficult to write strict firewall rules.

Geo-Replication and Global Architecture

Geo-replication enables an Azure Container Registry to function as a single registry that serves multiple regions with multi-master regional registries.

How geo-replication works

When you enable geo-replication for an ACR registry, Azure creates geo-replica resources in Azure regions of your choosing. When you push images to a geo-replicated registry, content automatically syncs to all geo-replicas.

Active-active model: All geo-replicas are active and writable—you can push, pull, and delete images from any geo-replica, not just the home region.

Eventual consistency: After you push or delete an image in any geo-replica, ACR eventually replicates the change to all geo-replicas in the background. Replication time depends on image size.

Single global endpoint

You maintain a single set of credentials, role assignments, networking rules, and registry configuration across all geo-replicas. Use one global endpoint (myregistry.azurecr.io/myimage:tag) in all your builds and deployments. Azure routes requests to the geo-replica with the best network performance profile for the client.

When to use geo-replication

• Multi-region AKS deployments – Pull images quickly from local replicas
• Global applications – Reduce image pull latency for clients worldwide
• Disaster recovery – Images remain accessible from other regions if one region has an outage
• Development teams in multiple locations – Simplifies registry management and minimizes latency

Practical multi-region architecture

Developer / CI
        ↓
Primary ACR (Home Region)
        ↓
Geo-replicated to multiple regions
        ↓
AKS clusters in each region pull from local replica

Important considerations

Region endpoint exclusion: You can exclude a specific geo-replica from global endpoint routing by turning off --region-endpoint-enabled for maintenance or troubleshooting.

Push-then-pull cross-region: Pushing an image to one geo-replica and immediately pulling it from a different geo-replica can fail with manifest unknown until replication catches up. This commonly affects CI/CD pipelines where a CI runner pushes an image and pods across multiple regions immediately attempt to pull it.

Tag overwrite races: Pushing myapp:v1, then re-pushing myapp:v1 shortly after with a different digest can cause consistency issues during replication.

Geo-replication requires Premium SKU.

ACR in AI and Cloud-Native Architectures

ACR plays a crucial role in AI and machine learning workloads on Azure. For AI workloads, ACR offers several important capabilities:

• Private storage: Keep model serving images, preprocessing containers, and inference APIs secure within your Azure environment
• Geo-replication: Distribute images close to deployment regions for faster pulls and reduced latency
• Integration: Connect directly to AKS, Azure Container Apps, and Azure App Service for seamless deployments
• Content formats: Store Docker images, Helm charts, and OCI artifacts in a single registry

AI workload architecture

Source code / Model artifacts
        ↓
CI/CD pipeline
        ↓
Build container image (with model serving framework)
        ↓
Vulnerability scanning (Microsoft Defender)
        ↓
ACR (secure container image storage)
        ↓
AKS GPU node pool (or Container Apps)
        ↓
Model endpoint / Inference API

AI use cases for ACR

Containerized inference services: Package model inference code (Triton, vLLM, TensorFlow Serving, PyTorch Serve) as container images stored in ACR.

RAG applications: Store RAG API containers in ACR; deploy to AKS with GPU node pools.

AI agent services: Containerize AI agent code and store in ACR for deployment and scaling.

Batch inference workloads: Store batch processing containers in ACR; deploy to AKS for scheduled or event-driven inference.

ML pipelines: Store preprocessing, training, and evaluation containers in ACR as part of ML pipeline orchestration.

Separation of concerns

In AI architectures, ACR stores application container images but not model artifacts or training data. Keep these separate:

Component	Storage Location
Application container images	ACR
Model artifacts	Azure Blob Storage, Azure Machine Learning model registry
Training data	Azure Data Lake, Blob Storage
Runtime configuration	Kubernetes ConfigMaps, Azure App Configuration
Secrets	Azure Key Vault

Common Architecture Patterns

Pattern 1: Small development project

Developer
    ↓ (docker push)
ACR (Basic)
    ↓ (docker pull)
Azure Container App

When to use: Single developer or small team, simple containerized application. Security: Developer has AcrPush; Container App pulls with managed identity. Trade-off: Simple, low cost, but limited scalability and no geo-replication.

Pattern 2: Production AKS

CI/CD (GitHub Actions / Azure DevOps)
    ↓ (build + push)
ACR (Standard)
    ↓ (pull via kubelet managed identity)
AKS (multiple node pools)
    ↓
Azure services (database, cache, storage)

When to use: Production microservices on AKS. Security: CI/CD uses workload identity federation; AKS uses AcrPull via managed identity; private networking. Trade-off: More complex, higher operational overhead, but full control and scalability.

Pattern 3: Enterprise private architecture

CI/CD (self-hosted agents)
    ↓ (build + push)
ACR (Premium)
    ↓ (private endpoint)
Private AKS (VNet integration)
    ↓
Azure services (all private)

When to use: Regulated environments, zero-trust security requirements. Security: Private endpoints, VNet integration, no public access, managed identity. Trade-off: Highest security, highest cost and operational complexity.

Pattern 4: Multi-region architecture

CI/CD (push to primary)
    ↓
ACR (Premium, geo-replicated)
    ├── Region A (home)
    ├── Region B (geo-replica)
    └── Region C (geo-replica)
        ↓
AKS clusters in each region pull from local replica

When to use: Global applications, multi-region AKS deployments. Security: Private endpoints per region, managed identity. Trade-off: Higher cost (Premium), eventual consistency considerations.

Pattern 5: AI container platform

CI/CD (push with vulnerability scanning)
    ↓
ACR (Premium, with security scanning)
    ↓
AKS GPU node pool (private cluster)
    ↓
AI inference services + RAG APIs

When to use: AI/ML inference workloads with GPU requirements. Security: Private ACR, vulnerability scanning, managed identity for AKS, private networking. Trade-off: GPU node pools are expensive; Premium SKU required for enterprise features.

ACR vs. Docker Hub vs. GitHub Container Registry

Aspect	Azure Container Registry	Docker Hub	GitHub Container Registry
Hosting	Azure-managed	Docker Inc.-managed	GitHub-managed
Private repositories	Yes (all private by default)	Limited on free plan	Yes (GitHub plan)
Authentication	Microsoft Entra ID	Docker ID / PAT	GitHub token
Azure integration	Deep (AKS, Container Apps, App Service)	Limited	Limited
Geo-replication	✅ (Premium)	❌	❌
Security scanning	✅ (Microsoft Defender)	Limited	Third-party
CI/CD integration	Native with GitHub Actions, Azure DevOps	Docker Hub actions	Native with GitHub Actions
Rate limits	SKU-based	Strict on free plan	GitHub usage-based
Pricing model	Pay-as-you-go (storage + throughput)	Free tier + paid plans	Free for public, storage + transfer fees
Best for	Enterprise Azure workloads	Public images, open-source	GitHub-native CI/CD workflows

When to choose ACR

• You're deploying to Azure services (AKS, Container Apps, App Service)
• You need enterprise security (private endpoints, managed identity)
• You need geo-replication for global deployments
• You want integrated vulnerability scanning
• You need granular RBAC with Microsoft Entra ID

When to choose Docker Hub

• You're publishing public open-source images
• You're getting started with containers
• You need access to official Docker images

When to choose GitHub Container Registry

• You're already using GitHub for source control and CI/CD
• You want free private repositories (within GitHub plan limits)
• You want tight integration with GitHub Actions

Cost and Capacity Considerations

Major cost drivers

Cost Factor	Description
Registry tier	Basic, Standard, or Premium (different base costs and included storage)
Storage consumption	Images stored beyond included storage (charged per GB/month)
Data transfer	Egress from Azure to internet or other regions
Geo-replication	Premium tier cost; each replica region adds cost
Throughput	Higher throughput tiers cost more
Image builds	ACR Tasks build time and compute
Webhooks and events	Minimal cost, but adds up at scale

Storage optimization strategies

Image retention policies: Retain only necessary images. Deleting old, unused images reduces storage costs. Configure automatic retention policies in ACR.

Layer sharing: ACR shares common layers across images. Building images from common base images reduces storage.

Image cleanup: Regularly review and delete:

• Images older than a retention period
• Untagged images (images with no tags)
• Development/test images no longer in use

Data transfer costs

Pulling images from ACR to Azure services in the same region typically incurs no data transfer costs. Pulling images across regions or to external systems incurs data transfer costs.

Cost optimization recommendations

• Choose the smallest SKU that meets your throughput and feature requirements
• Use Basic for development and testing; Standard for most production workloads
• Use Premium only when you need geo-replication, private endpoints, or content trust
• Implement image retention policies to remove unused images
• Place registries in the same region as your deployments
• Monitor storage usage and clean up regularly
• Use ACR Tasks for builds only when necessary

Production Best Practices

Registry configuration

• Use Premium SKU for mission-critical production – Premium provides the most comprehensive reliability features
• Create registry in the same region as deployments – Reduces latency and cost
• Use geo-replication for multi-region deployments – Distribute registries based on geographic and compliance requirements

Authentication and authorization

• Use Microsoft Entra ID instead of registry admin credentials – Never use the admin account for production
• Use managed identities where possible – For Azure services and workloads
• Use workload identity federation for external CI/CD – OIDC federation eliminates long-lived secrets
• Apply least-privilege RBAC – Grant AcrPull to consumers, AcrPush to CI/CD pipelines, AcrDelete to cleanup processes
• Avoid broad AcrPush permissions – Limit who can push to production registries

Image management

• Use immutable image versioning – Semantic versioning or Git SHA; avoid latest in production
• Scan images before deployment – Use Microsoft Defender for Cloud vulnerability scanning
• Remove vulnerable images – Delete or quarantine images with critical vulnerabilities
• Implement retention policies – Remove old, untagged, or unused images
• Keep images small – Remove unnecessary layers and use minimal base images

Networking

• Use private endpoints for sensitive enterprise environments – Azure Private Link is the most secure approach
• Use dedicated data endpoints – For tightly scoped firewall rules
• Disable public access where possible – For zero-trust architectures
• Configure DNS properly for private endpoints – Ensure FQDNs resolve to private IPs

Operations

• Monitor registry operations – Use Azure Monitor metrics and alerts
• Integrate registry security into CI/CD – Scan images before deployment; block vulnerable images
• Maintain software supply-chain visibility – Know what images are deployed and where
• Document image ownership and lifecycle – Who owns each image? When should it be retired?
• Separate development and production – Use different registries or repositories with different access controls
• Test disaster recovery – Ensure images can be restored if needed

Common Mistakes

Using the ACR admin account everywhere

The admin account provides full push/pull access with a single set of credentials. It should never be used for production. Use Microsoft Entra ID and managed identities instead.

Consequence: Shared credentials with full access are a security risk. No audit trail per user.

Better approach: Use Microsoft Entra ID with RBAC (AcrPull, AcrPush, etc.).

Giving every developer AcrPush

Developers should have AcrPush on development registries only, not production registries. Production registries should be write-protected.

Consequence: Accidental pushes to production; no change control.

Better approach: Use different registries or repositories for development and production. Limit AcrPush to CI/CD pipelines in production.

Using latest as the production version

The latest tag is mutable and provides no versioning guarantees. Using latest in production makes it impossible to determine which version is deployed or to roll back.

Consequence: Cannot reliably roll back; cannot track which version caused issues.

Better approach: Use immutable tags (semantic version or Git SHA) for production.

Storing secrets inside images

Secrets (connection strings, API keys, passwords) hard-coded in images are exposed to anyone with image access. They cannot be rotated without rebuilding the image.

Consequence: Security breach; difficult to rotate secrets.

Better approach: Use environment variables, Kubernetes Secrets, Azure Key Vault, or ConfigMaps.

Ignoring image vulnerabilities

Not scanning images before deployment allows vulnerable images to reach production.

Consequence: Production systems are vulnerable to known CVEs.

Better approach: Integrate vulnerability scanning into CI/CD. Block deployments of images with critical or high-severity vulnerabilities.

Making production registries publicly accessible unnecessarily

Publicly accessible registries increase the attack surface.

Consequence: Potential unauthorized image pulls; data exfiltration risk.

Better approach: Use private endpoints or IP firewall rules. Disable public access where possible.

Keeping unlimited old images

Old images consume storage and increase costs. They also make it harder to find which images are actually in use.

Consequence: Higher storage costs; operational confusion.

Better approach: Implement retention policies. Delete old, untagged, or unused images.

Using one registry without considering organizational isolation

One registry with broad permissions makes it difficult to control access per team or application.

Consequence: Security risks; difficult to audit.

Better approach: Use multiple registries per team, environment, or application with appropriate RBAC.

Forgetting private DNS when using private endpoints

Without proper DNS configuration, registry FQDNs may not resolve to private IP addresses.

Consequence: Cannot connect to the registry from the VNet.

Better approach: Configure private DNS zones with A records pointing to private endpoint IPs.

Giving AKS insufficient AcrPull permissions

Without AcrPull permission, AKS nodes cannot pull images from ACR. Pods enter ImagePullBackOff.

Consequence: Deployments fail.

Better approach: Use the AKS-to-ACR integration to grant AcrPull to the kubelet managed identity.

Using long-lived CI/CD credentials

Long-lived credentials (service principal passwords, API keys) are a security risk if leaked.

Consequence: Security breach; difficult to rotate.

Better approach: Use workload identity federation (OIDC) for GitHub Actions and Azure DevOps.

Treating container images as trusted by default

Images may contain vulnerabilities or malicious code even if they come from a private registry.

Consequence: Security breach.

Better approach: Scan images; sign images with content trust; enforce trusted images policy.

Mixing development and production images without governance

No separation makes it difficult to control what reaches production.

Consequence: Accidental production deployments; security risks.

Better approach: Use separate registries or repository namespaces with different access controls.

Troubleshooting

Common problems and solutions

docker push authentication failure

• Symptom: denied: requested access to the resource is denied
• Likely cause: Insufficient permissions (not authenticated or missing AcrPush role)
• Diagnose: Run az acr login --name myregistry; check your RBAC assignment
• Fix: Authenticate with az acr login; ensure you have AcrPush role

docker pull authentication failure

• Symptom: denied: requested access to the resource is denied
• Likely cause: Missing AcrPull role or authentication expired
• Diagnose: Check RBAC assignments; verify authentication
• Fix: Ensure AcrPull role is assigned to the pulling identity

AKS ImagePullBackOff

• Symptom: Pod status shows ImagePullBackOff
• Likely cause: AKS cannot pull the image from ACR
• Diagnose: Check pod events (kubectl describe pod); verify AcrPull assignment
• Fix: Ensure the AKS cluster has AcrPull on the kubelet managed identity

Private endpoint connectivity problems

• Symptom: Cannot connect to registry from VNet
• Likely cause: DNS resolution issue or network configuration
• Diagnose: Check private endpoint status; verify DNS resolution
• Fix: Configure private DNS zone; verify VNet integration

Image not found

• Symptom: manifest unknown: manifest tagged by "v1.0.0" is not found
• Likely cause: Image tag doesn't exist or was deleted
• Diagnose: List tags (az acr repository show-tags)
• Fix: Push the image with the correct tag; verify the tag name

CI/CD authentication failures

• Symptom: Pipeline fails to authenticate to ACR
• Likely cause: Expired credentials or incorrect configuration
• Diagnose: Check service principal expiration; verify OIDC configuration
• Fix: Rotate service principal credentials; configure OIDC federation

Quick diagnostic command

Run az acr check-health --name myregistry to diagnose common issues. This command checks:

• Docker client installation
• Registry accessibility
• Authentication status
• Network connectivity

Practical Learning Path

For developers

1. Understand containers and OCI images – Docker basics, image layers, Dockerfile
2. Create an ACR registry – Use Azure portal or Azure CLI
3. Build and push an image – docker build, az acr login, docker push
4. Understand repositories and tags – Repository naming, tagging strategies
5. Configure Microsoft Entra ID and RBAC – Assign AcrPull, AcrPush, AcrDelete

For architects

6. Integrate ACR with AKS – Managed identity integration, AcrPull role
7. Secure ACR – Private endpoints, IP firewall, dedicated data endpoints
8. Integrate ACR with CI/CD – GitHub Actions, Azure Pipelines, workload identity federation
9. Configure private networking – VNet integration, private DNS
10. Design production and multi-region architectures – Geo-replication, multi-region AKS

For AI engineers

11. Use ACR in AI/cloud-native workloads – Containerized inference, RAG applications
12. Configure vulnerability scanning – Microsoft Defender for Cloud, CI/CD security gates
13. Implement image signing – Content trust for AI model containers

Key Takeaways

Azure Container Registry (ACR) is a managed, private Docker registry service that stores and distributes container images and related artifacts. It provides direct control over container content with integrated authentication, geo-replication, and virtual network configuration.

ACR uses a three-level hierarchy: Registry → Repository → Artifact (image with tags). Understanding this structure helps you plan image organization.

ACR offers three SKUs: Basic (development), Standard (production), and Premium (enterprise with geo-replication and private endpoints).

Authentication should use Microsoft Entra ID and RBAC – never the admin account for production. Built-in roles include AcrPull, AcrPush, and AcrDelete.

AKS integrates with ACR using managed identity – the kubelet managed identity is granted AcrPull to pull images.

Security features include vulnerability scanning with Microsoft Defender for Cloud, content trust (Premium), and trusted images policy.

Private endpoints (Premium) provide the most secure network access, limiting traffic to your Azure Virtual Network using private IP addresses.

Geo-replication (Premium) enables a single registry to serve multiple regions with active-active replicas. Use for global applications and multi-region AKS deployments.

ACR is a critical component in AI architectures for storing containerized inference services, RAG APIs, and AI agent containers.

Production best practices include: use immutable versioning, scan images before deployment, apply least-privilege RBAC, use private networking, implement retention policies, and monitor registry operations.