AI-200 Container Hosting: Azure Container Registry, ACR Tasks and App Service Containers

Choose the tier by the features the scenario requires, not by storage size: Premium is the only tier with geo-replication, private endpoints, IP and virtual network access rules, the retention policy for untagged manifests and dedicated data endpoints. Basic and Standard cover the core registry operations (push, pull, ACR Tasks, tokens, image locks, artifact cache rules) with lower included storage and throughput — artifact cache works in every tier. Zone redundancy is enabled by default in supported regions for every tier.

Geo-replication beats running one registry per region because every region keeps the same login server name: the pipeline pushes once, Azure replicates the content, and DNS sends each pull to the closest replica. Separate registries synced with az acr import also give nearby copies, but each has its own name. When a Standard registry must become private, the fix is two steps: upgrade the tier to Premium, then add a private endpoint in the virtual network and disable public network access.

Dedicated data endpoints matter for strict firewalls. A client authenticates and fetches manifests from the login server but downloads layers from a data endpoint, which by default is shared storage that a firewall can only allow with a wildcard such as *.blob.core.windows.net. With dedicated data endpoints turned on, the firewall allows exactly the login server plus the registry's own regional data endpoints.

Prefer Microsoft Entra identities with registry roles (managed identities for Azure workloads, service principals for pipelines); use repository-scoped tokens for clients that have no Entra identity; keep the admin user disabled except for quick tests, because it is a single shared registry-wide credential with push and pull rights.

Roles in the RBAC Registry Permissions mode

The RBAC and ABAC mode

A registry created or switched with --role-assignment-mode rbac-abac uses attribute-based access control for repository permissions. In that mode the legacy AcrPull, AcrPush and AcrDelete roles are not honored, so an identity that only holds AcrPull gets unauthorized errors. The replacement roles are Container Registry Repository Reader, Writer and Contributor. Assigned without a condition they apply to every repository; an ABAC condition on the repository name narrows them to, for example, billing/invoices.

Tokens and scope maps

A token authenticates with its name and a generated password, and its linked scope map lists repositories and actions: content/read to pull, content/write to push (pushing needs both read and write), plus metadata and delete actions. Tokens fit edge devices, partners outside your tenant and other non-Entra clients. Issue one token per device or partner so that one can be disabled or deleted without affecting the rest. A repository wildcard is valid only with a trailing /*, as in edge-fleet/*, and it also covers repositories that a later push creates.

ARM audience tokens

Some Azure services, including App Service's managed-identity image pull, authenticate to the registry with Microsoft Entra tokens issued for the Azure Resource Manager audience. Built-in Azure Policy definitions can disable ARM-audience authentication on registries (or remediate them to disable it). When pulls fail right after a policy assignment and the role assignment is unchanged, re-enable it with az acr config authentication-as-arm update --status enabled and exempt the registry from the policy, or it is switched back.

Use a unique tag per build (build ID, commit SHA or date stamp) for anything you deploy, and a digest (repo@sha256:<digest>) when you need a guarantee of exact bytes; keep stable tags such as latest or 1.4 for base images and convenience, because they are expected to move.

Deploying a stable tag causes drift: instances that start after a new push (for example during scale-out) pull the newer, possibly untested build while older instances keep the previous one. Only a push moves a tag. Replication and authentication settings never change what it points to, and a lock (write-enabled false) only stops a push from moving it.

Use az acr import for a one-time server-side copy that keeps the original manifest digest, and an artifact cache rule when the registry should fetch an upstream image on first request and serve its stored copy afterwards.

az acr import needs only the Azure CLI: Azure pulls from the source registry (Docker Hub, MCR or another Azure registry) and writes into the target, so no local Docker engine is involved and the digest is preserved. Rebuilding an image with FROM creates a new image with a new digest instead.

az acr import --name fabrikamreg \
  --source mcr.microsoft.com/dotnet/runtime:8.0 \
  --image dotnet/runtime:8.0

For a source Azure registry in another subscription of the same tenant, pass its resource ID with --registry and the image path with --source; the import then runs with your own Entra identity, so no registry password or admin user is needed. Replication is not a copy mechanism between registries, it only replicates one registry.

Artifact cache (pull-through cache) is configured with a cache rule that maps an upstream repository, such as docker.io/library/python, to a repository in your registry. It needs the Standard or Premium tier and removes upstream rate-limit problems without copy jobs. A Docker Hub upstream supports authenticated pulls only, so its rule uses a credential set whose username and token are stored as Key Vault secrets.

Lock content with az acr repository update attributes, and clean up with acr purge (any tier, run on demand or on a schedule) or the retention policy (Premium, untagged manifests only).

Lock attributes

So an immutable release is a single tag with write-enabled false (tag and manifest attributes are set separately, so locking a tag doesn't lock its manifest digest; deploy by the locked tag, or lock the digest too, with --image x@sha256:…); a weekly-refreshed base tag that must never be deleted uses delete-enabled false with write-enabled true, and a repository that must not disappear needs its own repository-level setting as well. To delete a write-locked image, first set --write-enabled true on that same image. An Azure resource lock (az lock) protects only management-plane operations such as deleting the registry resource; it never protects images or tags.

Purge and retention

acr purge (a preview command run inside ACR Tasks) takes a required --filter of a repository regex and a tag regex ('samples/.*:.*' matches every repository under samples/), --ago for age, --untagged to also delete manifests left without tags, --keep N to retain the newest N tags per repository that would otherwise be deleted, and --dry-run to list what would be deleted without deleting it. Add --dry-run first to see the list. az acr run executes it once; an ACR task with a timer trigger and --context /dev/null makes it recur on managed compute.

az acr run --registry reg \
  --cmd "acr purge --filter 'ci/.*:.*' --ago 30d --keep 3 --untagged" \
  /dev/null

The retention policy is a registry setting with no task to maintain: az acr config retention update --status enabled --days 7 --type UntaggedManifests deletes each untagged manifest once it has been untagged for that many days. It can't delete old tags, and it requires Premium.

A quick task moves docker build into Azure: az acr build uploads the local build context, builds it on ACR Tasks compute and pushes the tagged image to the registry, so the machine needs only the Azure CLI, no Docker engine.

az acr build --registry fabrikamreg --image orders:2.3.0 .

• --platform linux/arm64 builds the same Dockerfile for another OS/architecture. A build argument such as TARGETARCH is only an input the Dockerfile can read; it doesn't change the build platform.
• --no-push builds without pushing, which suits pull-request checks that must not add images.
• az acr run runs a task once: with --cmd it runs an existing container image, and the final /dev/null context says there is no source to upload. Nothing stays configured afterwards.

az acr run --registry fabrikamreg \
  --cmd '$Registry/jobs/seed-data:1.2' /dev/null

Inside a run, $Registry expands to the registry's login server (for example fabrikamreg.azurecr.io); $RegistryName is only the short name. az acr task create, by contrast, creates a reusable task resource with triggers; it doesn't run anything by itself until triggered or started with az acr task run.

An ACR task created with az acr task create can run automatically on three triggers: a source commit (or pull request) in a Git repository, a timer, and a base image update.

Source commit

A task whose --context is a GitHub or Azure Repos URL (for example https://github.com/contoso/api.git#main) gets a commit trigger; pass --git-access-token with a personal access token so ACR can create the repository webhook.

Timer

--schedule takes a five-field cron expression in UTC: minute, hour, day of month, month, day of week. "30 4 * * Mon" is 04:30 UTC every Monday; there is no seconds field. Convert local times yourself: 07:00 in a UTC−5 city is "0 12 * * *" (12:00 UTC), and 06:00 in a UTC+9 city is "0 21 * * *" (21:00 UTC the previous day). A task can hold several named timers: az acr task timer add --timer-name midweek --schedule "0 22 * * Wed" adds one while az acr task timer update replaces a named timer's schedule. A timer-only maintenance task uses --context /dev/null.

Base image update

The base image trigger is enabled by default, and its rules are precise:

• ACR Tasks discovers base image dependencies while it builds, so the task must have run once before any update can trigger it.
• It tracks only the base of the application (runtime) image, the last stage of a multi-stage Dockerfile, not intermediate build-stage images such as an SDK image.
• It fires when the image behind the referenced tag changes, so the Dockerfile must reference a stable tag (node:20) that the platform team updates. Publishing each patch as a new tag (20.11.2) never changes a pinned 20.11.1.
• Base images in an Azure container registry trigger immediately; base images in public repositories such as Docker Hub or MCR are polled at a random interval of 10 to 60 minutes.

A multi-step task is a YAML file of steps, each of type build (docker build), push (push images) or cmd (run a container), and the when property controls ordering: without it a step waits for the step before it, when: ["-"] starts it immediately in parallel, and when: ["a", "b"] makes it wait for every named step.

version: v1.1.0
steps:
  - id: build-svc
    build: -t $Registry/svc:$ID ./svc
  - id: unit
    cmd: $Registry/svc:$ID npm test
    when: ["build-svc"]
  - id: lint
    cmd: $Registry/svc:$ID npm run lint
    when: ["build-svc"]
  - push: ["$Registry/svc:$ID"]
    when: ["unit", "lint"]

Here the build runs first, the two checks run in parallel because each names only the build, and the push waits for both checks. If a step fails, the run fails and later dependent steps never execute, which is how "push only if tests pass" is expressed: make the push depend on the test step. Listing only the build (or only one check) lets the push race the remaining check.

From version v1.1.0, predefined aliases can be used instead of run variables such as {{.Run.Registry}}, which still work: $Registry (login server of the run registry, so one file works in dev and prod), $RegistryName (short name), $ID (run ID, a convenient unique tag) and others such as $Branch. An image name without a registry prefix refers to Docker Hub.

Secrets stay out of the file and the CLI through a secrets block: each entry has an id and a keyvault secret URL (plus clientID for a user-assigned identity), and steps reference the value as {{.Secrets.<id>}}. The task authenticates to Key Vault with its own managed identity, which needs a data plane role such as Key Vault Secrets User; Key Vault Reader can't read secret values, and the creator's own rights don't apply at run time.

App Service for Linux pulls a custom container from Azure Container Registry most securely with a managed identity: grant the identity AcrPull on the registry and set the site property acrUseManagedIdentityCreds to true, so no registry user name or password is stored in configuration (the admin user with DOCKER_REGISTRY_SERVER_PASSWORD works but stores a password).

• By default the pull uses the system-assigned identity. To use a user-assigned identity, set acrUserManagedIdentityID to that identity's client ID. If the app has both identities and only the user-assigned one holds AcrPull, pulls fail until this is set.
• For a registry with public access disabled behind a private endpoint, the platform's image pull goes through the integrated virtual network only when vnetImagePullEnabled is true (shown in newer API versions and the portal as outboundVnetRouting.imagePullTraffic). Routing the app's own traffic (vnetRouteAllEnabled) doesn't cover the image pull.
• The managed-identity pull uses ARM-audience tokens, so the registry must allow ARM-audience authentication (see the authentication section).

Continuous deployment

Turning on continuous deployment in Deployment Center adds a webhook to the selected repository in ACR. Each push of the configured image posts to the webhook, which restarts the app so it pulls the updated image. Two consequences follow:

• The restarted app pulls the image:tag it is configured with. CD by webhook suits a stable tag; with unique tags per build, the pipeline must update the app's image (for example az webapp config container set), and that configuration change itself makes the app pull and start the new container.
• The webhook authenticates to the app's SCM endpoint with publishing credentials, so it needs Basic Auth Publishing Credentials enabled in the app's platform settings. Security baselines often disable it, which shows up as HTTP 401 in the webhook's delivery log while manual pulls still work.

To test each image on a warmed-up instance before users reach it, point CD at a staging slot and swap it into production. Before routing traffic, the swap applies the production slot's settings to the staging instances and warms them up, so there is no cold start. The image moves with the slot; settings marked as deployment slot settings stay behind.

App Service injects every app setting into the container process as an environment variable with the same name, so values such as DB_HOST come from configuration instead of being built into the image, and secrets come from Key Vault references placed in app settings.

Platform settings for custom containers

App settings, connection strings and slots

Connection strings are also exposed as environment variables, but with a type prefix such as SQLCONNSTR_, SQLAZURECONNSTR_, MYSQLCONNSTR_, POSTGRESQLCONNSTR_, SERVICEBUSCONNSTR_ or CUSTOMCONNSTR_. A Custom connection string named Inventory is read as CUSTOMCONNSTR_Inventory; code that reads a plain name should use an app setting. Mark a setting as a deployment slot setting (sticky) when each slot must keep its own value after a swap; unmarked settings travel with the swap.

Key Vault references

Set the app setting's value to a reference in one of two forms; the app then reads the secret as an ordinary environment variable:

@Microsoft.KeyVault(SecretUri=https://kv-shop.vault.azure.net/secrets/api-key)
@Microsoft.KeyVault(VaultName=kv-shop;SecretName=api-key)

• The URI must use the /secrets/ path, and the name form separates parts with semicolons. Omitting the version makes the reference follow the latest version, so rotation needs no setting change; adding a version pins it.
• Resolved values are cached and refetched every 24 hours. Any configuration change restarts the app and refetches immediately; to refresh without changing configuration, POST to …/config/configreferences/appsettings/refresh. App Service doesn't subscribe to Key Vault events.
• The identity used is the system-assigned one by default and needs a secret-read role such as Key Vault Secrets User (Key Vault Reader can't read values). To use a user-assigned identity, set keyVaultReferenceIdentity to its resource ID; it applies to every reference in the app. A user-assigned identity can be authorized before the app exists, so references resolve on first creation. Don't confuse it with acrUserManagedIdentityID, which takes a client ID.
• If a reference can't be resolved, the app sees the literal reference text. For a vault reachable only through a private endpoint, a Linux app with virtual network integration must route all outbound traffic through the virtual network (vnetRouteAllEnabled, or outboundVnetRouting in newer API versions).