Regional Endpoints for Azure Container Registry Geo-Replication — Now in Public Preview

By Johnson Shi, Zoey (Zhuyu) Li, Huangli Wu

What's new

Regional endpoints for geo-replicated Azure Container Registries are now in public preview. See the feature's official MS Learn documentation. If you've been following since the private preview announcement, here's what changed:

• No feature flag registration. No subscription enrollment so all Azure subscriptions and customers can now use this feature.
• No CLI extension. Regional endpoints commands are built into Azure CLI 2.86.0+ natively. If you installed the private preview acrregionalendpoint extension, uninstall it to avoid conflicts.
• Native CLI and portal support.
  • With Azure CLI 2.86.0+, enable regional endpoints for all geo-replicas of a registry with az acr create --regional-endpoints enabled or az acr update --regional-endpoints enabled.
  • The Azure portal also supports configuring regional endpoints natively.
• CLI flag rename for configuring a geo-replica's global endpoint routing (an existing separate feature). The existing flag --region-endpoint-enabled (on az acr replication create/update) has been renamed to --global-endpoint-routing.
  • Key clarifications:
    • "--global-endpoint-routing" (formerly "--region-endpoint-enabled" on "az acr replication create / az acr replication update") — controls whether a specific geo-replica participates in global endpoint routing. This is an existing feature that is different from the new registry-level "--regional-endpoints" feature being discussed in this post.
    • "--regional-endpoints" (on az "acr create / az acr update") — enables or disables the regional endpoints feature at the registry level for all geo-replicas. This is the feature discussed in this post.
  • See the endpoint reference for the full breakdown of the various registry endpoints (global endpoints, regional endpoints, and data endpoints).

Regional endpoints are available on Premium SKU registries in all Azure public cloud regions.

What are regional endpoints?

Regional endpoints give you dedicated, per-region login server URLs for each geo-replica with the following URL pattern:

• myregistry.eastus.geo.azurecr.io
• myregistry.westeurope.geo.azurecr.io

Regional endpoints coexist with the registry's global endpoint (myregistry.azurecr.io) — enabling regional endpoints doesn't disable a registry's global endpoint that is backed by Azure-managed routing. You can choose per workload:

• You can use the global endpoint with automatic Azure-managed routing with health-aware failover, where Azure will route your requests to the geo-replica with the best network performance profile to the client.
• You can use a regional endpoint when you need explicit control or routing to a specific geo-replica.

Other resources:

• For the full background on why regional endpoints exist and the problems they solve, see the private preview blog post.
• For the complete operational deep dive — health-aware failover, throttling considerations, storage quota and pricing, eventual consistency, home region outage behavior, DNS propagation, private endpoint interaction, capacity planning, and monitoring guidance — see How ACR geo-replication handles failover, failback, and traffic redirection.
• For the behind-the-scenes engineering implementation — architectural overview and the engineering system design of the feature — see Determinism over magic: the engineering design behind Azure Container Registry Regional Endpoints.

Getting started

Enable regional endpoints on an existing registry:

az acr update -n myregistry -g myrg --regional-endpoints enabled

View all registry endpoint URLs, including the registry global endpoint, geo-replica regional endpoints, and data endpoints:

az acr show-endpoints --name myregistry --resource-group myrg

Using regional endpoints

Authenticate to a specific regional endpoint:

az acr login --name myregistry --endpoint eastus

Push to a specific geo-replica.

Images and tags pushed to a geo-replica via regional endpoints still propagate to all other geo-replicas under eventual consistency.

docker tag   myapp:v1  myregistry.eastus.geo.azurecr.io/myapp:v1
docker push            myregistry.eastus.geo.azurecr.io/myapp:v1

Pull an image:

docker pull myregistry.eastus.geo.azurecr.io/myapp:v1

You can specify regional endpoints directly in Kubernetes deployment manifests if you need to pin workloads to specific regions. This ensures clusters in specific regions always pull from their colocated replica, providing predictable routing and reduced latency.

By using different regional endpoints in each cluster's manifests, you can choose to guarantee that each cluster pulls from its local replica instead of relying on Azure-managed routing.

East US cluster deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-eastus
spec:
  template:
    spec:
      containers:
      - name: myapp
        image: myregistry.eastus.geo.azurecr.io/myapp:v1

West Europe cluster deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-westeurope
spec:
  template:
    spec:
      containers:
      - name: myapp
        image: myregistry.westeurope.geo.azurecr.io/myapp:v1

When to use regional endpoints

What changed from private preview

Enabling regional endpoints in the Azure portal

You can enable regional endpoints directly from the Azure portal for both new registries (during creation), as well as existing registries:

If you were in the private preview

1. Uninstall the CLI extension.

The private preview CLI extension conflicts with the built-in commands in Azure CLI 2.86.0+. Remove it:

az extension remove --name acrregionalendpoint

Verify it's gone:

az extension list --query "[?name=='acrregionalendpoint']" -o table

2. Ensure you're running Azure CLI 2.86.0 or later.

Regional endpoints commands are available natively starting in Azure CLI 2.86.0. Check your version:

az version

3. Update scripts that use --region-endpoint-enabled for controlling global endpoint routing for a geo-replica.

The old flag name for controlling a geo-replica's global endpoint routing configuration is deprecated and will be removed in Azure CLI 2.87.0 (June 2026). Update to --global-endpoint-routing:

# Old (deprecated)
az acr replication update --registry myregistry --name westus \
  --region-endpoint-enabled false

# New
az acr replication update --registry myregistry --name westus \
  --global-endpoint-routing false

Why the rename? The old flag name --region-endpoint-enabled was confusing — it sounded like it controlled the regional endpoints feature, but it actually controlled whether a geo-replica participates in global endpoint routing. The new name --global-endpoint-routing says exactly what it does. For a full breakdown of all three CLI flags and how they relate, see the endpoint reference.

Learn more

• Full documentation: Geo-replication in Azure Container Registry — Regional endpoints — prerequisites, CLI commands, network considerations, private endpoint integration, and troubleshooting.
• Operational deep dive: How ACR geo-replication handles failover, failback, and traffic redirection — health-aware failover, throttling, eventual consistency, DNS considerations, monitoring, pricing, and a full walkthrough.
• Behind-the-scenes engineering implementation: Determinism over magic: the engineering design behind Azure Container Registry Regional Endpoints — architectural details and the engineering system design behind the feature.
• Endpoint reference: Azure Container Registry endpoint reference — all endpoint types, URL formats, and CLI flags in one place.
• Private endpoints: Connect privately to a registry using private endpoints — IP allocation math, subnet sizing, and NIC queries for registries with regional endpoints.
• Firewall rules: Configure firewall access rules — which FQDNs to allow for regional endpoints.

Feedback

We'd love to hear how you're using regional endpoints and what we can improve. Reach out via:

• Azure Container Registry GitHub repository — issues, feature requests, and discussion
• Azure portal feedback — use the feedback button in the Azure portal on your registry's page

Regional endpoints are on the path to GA. Your feedback directly shapes the feature's direction.