Azure Container Registry

Azure Container Registry (ACR) is a private, Docker/OCI-compatible registry offered in three SKUs (pricing plans): Basic, Standard and Premium. All three provide the same data-plane APIs, Microsoft Entra authentication, image deletion, webhooks and availability-zone redundancy (where the region supports zones) — the differences are storage/throughput and a set of Premium-only features:

Bookshelf runs acrbookshelf as Premium, because it is the only tier that unlocks the geo-replication, private endpoint and retention features covered later on this page. A registry can be moved between SKUs later (az acr update --sku) with no downtime, though moving down from Premium requires first deleting any geo-replicas or connected registries the higher tier created. Every SKU shares the same request-rate limits model (requests per minute, per registry and per identity) with Premium roughly doubling Basic/Standard’s limits; a registry that consistently hits 429 Too Many Requests is a signal to move up a tier rather than to retry harder.

The registry ships with an admin user account (a single shared username/password pair) that is disabled by default on a newly created registry. Leave it disabled — it is a shared secret with no per-caller identity or audit trail, which is exactly what the managed-identity pull flow later on this page exists to avoid. It is useful only for the earliest manual docker login while nothing else is wired up yet, and even then az acr login (below) is the better default because it reuses the caller’s own Azure CLI/Entra session instead of a shared password.

az acr login authenticates the local Docker (or Podman/nerdctl) daemon against a registry using the caller’s own Azure CLI session, so no separate registry credential ever needs to be typed or stored locally.

az acr build queues an image build inside Azure — streaming the Dockerfile build log back to the caller — without needing a local Docker daemon at all. The build context can be a local directory, a remote Git URL, or an OCI artifact reference; ACR provisions the build compute, runs the build, and (unless --no-push is passed) pushes the resulting image straight into the same registry.

az acr build is a one-off, manually queued build. ACR Tasks (az acr task) turns the same build into a standing definition that runs automatically on a commit trigger (a push or pull request against a linked Git repository) or a base-image trigger (the FROM image in the Dockerfile gets a new version in the registry, so every image built from it is rebuilt and repatched). A task can also run on a timer, or on demand.

Every Bookshelf compute service authenticates its own image pull with a managed identity holding the built-in AcrPull role on acrbookshelf, scoped to the registry — never with the admin account’s username/password, and never with a long-lived personal access token embedded in a deployment manifest. AcrPull is a data-plane role: it lets the identity pull image layers and manifests, and nothing else. The three compute services covered elsewhere in this section wire it up differently, since none of them share a single --attach-acr flag:

Three Premium-only features round out acrbookshelf for a production footprint:

Geo-replication creates additional, fully writable copies (geo-replicas) of the registry in other Azure regions, all reachable through the same global login server (acrbookshelf.azurecr.io) and the same set of credentials and role assignments. Azure routes each request to whichever geo-replica gives the caller the best network performance, which is usually the closest one, and automatically reroutes away from a geo-replica that becomes unhealthy. Replication between geo-replicas is eventually consistent — a pipeline that pushes an image in one region and immediately expects a pull to see it in another region can occasionally hit a manifest unknown error until replication catches up, so a cross-region CI/CD pipeline should build in retry-with-backoff around that window, or pin push and pull to the same region’s regional endpoint to sidestep it entirely. Storage is billed once per geo-replica, so replicating a registry into three regions roughly triples its storage cost.

Retention policy (currently a preview feature) automatically deletes untagged manifests a configurable number of days after they lose their last tag, which is what keeps a registry that constantly retags (rather than deletes) old builds from growing without bound. It never touches a manifest that still has a tag pointing at it. Deleted image data cannot be recovered, so set the retention window deliberately and keep it disabled on any repository still pulled by digest rather than by tag.

Private endpoint (Azure Private Link) gives acrbookshelf a private IP address inside a virtual network, so traffic between a client on that network and the registry never crosses the public internet; combined with disabling public network access, it restricts the registry to callers reachable through that network (plus any explicitly allowed trusted services). A private endpoint also auto-enables dedicated data endpoints, giving each geo-replica its own IP for image-layer downloads instead of sharing Azure Storage’s shared public endpoints. Disabling public network access breaks az acr build/ACR Tasks unless a dedicated agent pool is used, since Tasks' build compute otherwise reaches the registry over its public endpoint.

A GitHub Actions workflow that builds and pushes an image to acrbookshelf should authenticate the same way any other CI/CD caller does in this section: workload identity federation, not a stored ACR admin password or a long-lived service-principal secret. The workflow mechanics — the federated credential, azure/login’s `id-token: write permission, and the build/push steps themselves — are already covered end to end on Docker CI/CD with GitHub Actions; the only ACR-specific requirement on top of that flow is that the workflow’s service principal (or managed identity) holds AcrPush (or AcrPull for a workflow that only deploys, never builds) scoped to acrbookshelf, assigned the same way as the AcrPull role assignments above.

Deleting rg-bookshelf removes acrbookshelf along with every image, geo-replica and private endpoint it holds — there is no separate purge or soft-delete step to run first by default, and no recovery window afterwards. The one built-in exception is the Premium retention policy covered above: it is not a registry-wide soft-delete of everything in the registry, but if left enabled it continues to prune untagged manifests on its own schedule right up until the registry itself is deleted, which is worth turning off first if a deletion is meant to be delayed rather than immediate.