Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 57 ยท Containers

Azure Container Registry

Store and secure container images with Azure Container Registry: SKUs, push and pull, ACR Tasks, geo-replication and passwordless access with managed identity.

A container image is only useful if every machine that needs it can fetch it. Your laptop builds the image, but a web app, a Container Apps environment or a Kubernetes cluster somewhere else has to pull it. A container registry is the server that stores images and hands them out on request. Azure Container Registry (ACR) is Azure's private, managed registry: it speaks the standard registry protocol, so the normal docker push and docker pull commands work against it.

Why not just use a public registry? A private registry keeps your images out of public view, sits in the same region as the services that pull from it (fast and cheap transfers), and uses the same identity and network controls as the rest of Azure. If you have never built an image, read Dockerfile basics and Image layers first. This lesson needs an Azure account for the real commands, so they are read-only. The runnable examples are Node.js stand-ins that show how a registry stores layers by their content hash.

Registries and SKUs

A registry is an Azure resource with a globally unique name (lowercase letters and digits, 5 to 50 characters). Its address is <name>.azurecr.io, called the login server. Inside it, images live in repositories (for example shop/api), and each image version has a tag such as v3.

You pick a SKU (service tier) when you create it:

SKU Typical use Notable features
Basic Learning, small projects Lowest cost and the smallest storage and throughput limits
Standard Most production workloads More included storage and higher throughput
Premium Large or regulated environments Geo-replication, private endpoints, zone redundancy, customer-managed encryption keys, highest throughput

Limits and prices change, so check the current pricing page before you choose. The feature split is the part to remember: if you need replicas in several regions or a private network path, you need Premium.

Create a registry and sign Docker in to it (read-only, the commands need an account):

Terminal
az group create --name containers-rg --location westeurope

az acr create \
  --resource-group containers-rg \
  --name contososhopacr \
  --sku Basic

az acr login --name contososhopacr

az acr login uses your Azure sign-in to obtain a short-lived token for Docker, so you never type a registry password.

Pushing and pulling images

Docker identifies where an image lives from its name. To push, you tag the local image with the registry's login server:

Terminal
docker build -t shop-api:1.0 .
docker tag shop-api:1.0 contososhopacr.azurecr.io/shop/api:1.0
docker push contososhopacr.azurecr.io/shop/api:1.0

az acr repository list --name contososhopacr --output table
az acr repository show-tags --name contososhopacr --repository shop/api

Pulling is the reverse: docker pull contososhopacr.azurecr.io/shop/api:1.0. You can also copy an image from another registry without a local Docker engine, using az acr import:

Terminal
az acr import \
  --name contososhopacr \
  --source docker.io/library/nginx:1.27 \
  --image base/nginx:1.27

Importing a few trusted base images into your own registry is a good habit. Your builds then no longer depend on a public registry being reachable or rate limiting you.

Layers, digests and tags

Understanding why pushes are fast the second time explains most of ACR's behavior. An image is a list of layers plus a manifest that names them. Every layer and every manifest is identified by a digest, a SHA-256 hash of its bytes. This is called content addressing: the name of a thing is derived from the thing itself.

Two consequences matter in practice:

  • Layers are shared. If ten images start from the same base image, the base layers are stored once. When you push a new version, Docker asks the registry which layers it already has and uploads only the missing ones.
  • Tags move, digests do not. A tag like latest or v3 is just a pointer to a manifest digest, and you can re-point it. A reference like shop/api@sha256:... always means exactly the same bytes. For reproducible deployments, many teams deploy by digest or by unique tags (a build number or commit hash) and avoid re-using latest.
flowchart LR
  T1["tag: v1"] --> M1["manifest A"]
  T2["tag: v2"] --> M2["manifest B"]
  M1 --> L1["layer: base OS"]
  M1 --> L2["layer: app v1"]
  M2 --> L1
  M2 --> L3["layer: app v2"]

Both manifests share the base layer; only the changed layer is new storage.

A content-addressed layer store: a stand-in

The real registry service is not something you can run here. The stand-in below keeps only the core idea: layers and manifests stored by their SHA-256 digest, tags that point at manifests, uploads that skip layers the registry already has, and a pull that checks every layer against its digest. It runs on the site's Node.js runner, so it can use node:crypto. The layer "contents" are short strings instead of real tarballs, and the digests are shortened to make the output readable.

Node.js Push layers, dedupe and verify digests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first push uploads three layers. The second shares two of them, so only the changed application layer travels. Repeating a push uploads nothing. The final lines show why digests matter: moving a tag never changes what an old digest means, and a layer whose bytes no longer match its digest is rejected.

ACR Tasks: build in the cloud

You do not need Docker on your machine to build an image. ACR Tasks runs the build inside Azure and stores the result straight into the registry.

Terminal
# One-off cloud build from the current folder
az acr build \
  --registry contososhopacr \
  --image shop/api:{{.Run.ID}} \
  .

# A task that rebuilds when the Git repo changes or the base image updates
az acr task create \
  --registry contososhopacr \
  --name build-shop-api \
  --image shop/api:{{.Run.ID}} \
  --context https://github.com/contoso/shop.git#main:api \
  --file Dockerfile \
  --git-access-token <token>

{{.Run.ID}} is a task variable that gives every build a unique tag. Tasks can also trigger when the base image changes, which is a convenient way to pick up security patches. For a full pipeline, see CI/CD with GitHub Actions and Azure DevOps.

Geo-replication

With a Premium registry, geo-replication keeps copies of your images in several regions under a single registry name.

Terminal
az acr replication create \
  --registry contososhopacr \
  --location japaneast

Clusters and apps pull from the nearest replica, so deployments are faster and keep working if one region has trouble. You push once; Azure replicates the new layers. Replication is asynchronous, so a brand-new image can take a short while to appear everywhere. You pay for the storage in each region.

Access with managed identity

Avoid the registry's admin user (a shared username and password). It is off by default; leave it that way. Use identities and roles instead, as described in Managed Identities and Service Principals.

The role that lets an identity pull images is AcrPull; AcrPush adds the right to push. Assign it at the registry scope:

Terminal
registryId=$(az acr show --name contososhopacr --query id --output tsv)

az role assignment create \
  --assignee <managed-identity-principal-id> \
  --role AcrPull \
  --scope $registryId

Services such as App Service, Container Apps and AKS can then pull with their managed identity, and no password appears in any setting. For AKS you can also attach the registry when you create the cluster, which sets up the pull permission for you. Roles follow the usual rules from Role-Based Access Control: narrow scope, least privilege.

For private networks, a Premium registry can be reached through a private endpoint, and you can disable public network access entirely.

Housekeeping

Registries grow. Old tags and untagged manifests keep costing storage. You can delete a tag or an image with az acr repository delete, and Premium and Standard registries support retention policies for untagged manifests. A simple rule: keep a handful of recent release tags, and let build tags expire. Also scan images for known vulnerabilities, for example with Microsoft Defender for Cloud (see Security Best Practices and Defender for Cloud).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the login server of a registry named contososhopacr?

    Every registry gets the address <name>.azurecr.io. You include it in the image name when you tag and push.
  2. 2. You need images replicated to several regions and a private endpoint. Which SKU do you need?

    Geo-replication and private endpoints are Premium features. Basic and Standard are single-region and public-endpoint registries.
  3. 3. Why is pushing a second version of an image usually quick?

    Content addressing lets the registry recognize layers it already has by their SHA-256 digest, so shared base layers are never uploaded twice.
  4. 4. How should an App Service or Container App pull from your private registry without a password?

    A managed identity with AcrPull can pull images with short-lived tokens. The admin user is a shared password and should stay disabled.
  5. 5. Which reference always points to exactly the same image bytes?

    Tags are movable pointers; a digest is derived from the content, so it cannot change without becoming a different digest.

Summary

  • ACR is a private, managed registry at <name>.azurecr.io; Basic, Standard and Premium differ in scale and in features such as geo-replication and private endpoints.
  • Tag images with the login server, then docker push; az acr import copies trusted images from other registries.
  • Layers and manifests are stored by SHA-256 digest, so layers are shared and uploaded only once; tags are movable pointers, digests are fixed.
  • ACR Tasks builds images in Azure and can rebuild on source or base-image changes.
  • Premium geo-replication serves images from the nearest region under one registry name.
  • Prefer managed identity with the AcrPull role over the admin user.

Next: Azure Container Apps.