Regional Endpoints for Geo-Replicated Azure Container Registries (Private Preview)

Imagine you're running Kubernetes clusters in multiple Azure regions—East US, West Europe, and Southeast Asia. You've configured ACR with geo-replication so your container images are available everywhere, but you've noticed something frustrating: you can't control which replica your clusters pull from. Sometimes your East US cluster pulls from West Europe, and you have no way to pin it to the co-located replica or troubleshoot why routing behaves unexpectedly.

This scenario highlights a fundamental challenge with geo-replicated container registries: while Azure-managed routing optimizes for performance, it doesn't provide explicit control for custom failover strategies, troubleshooting, regional affinity, or predictable routing. Regional endpoints solve this by letting you choose exactly which region handles your requests.

Background: How Geo-Replication Works Today

Geo-replication allows you to maintain copies of your container registry in multiple Azure regions around the world. This means your container images are stored closer to where your applications run, reducing download times and improving reliability. You maintain a single registry name (like myregistry.azurecr.io), and Azure automatically routes your requests to the most suitable replica.

The Challenge: Azure-Managed Routing Limitations

While geo-replication has been invaluable for global deployments, the automatic routing creates challenges for some customers. When you push or pull images from a geo-replicated registry, Azure-managed routing automatically directs your request to the most suitable replica based on the client's network performance profile.

While this Azure-managed routing works well for many scenarios, it creates several challenges for customers with specific requirements:

1. Misrouting Issues: Azure-managed routing may not always select the replica you expect, particularly if network conditions fluctuate or if you're testing specific regional behavior.
2. Geographic Ambiguity: Clients located equidistant from two replicas may experience unpredictable routing as Azure switches between them based on minor network performance variations.
3. Push/Pull Consistency: Images pushed to one replica may be pulled from another during geo-replication synchronization, creating temporary inconsistencies that can impact deployment pipelines. For more details on troubleshooting push operations with geo-replicated registries, see Troubleshoot push operations.
4. Lack of Regional Affinity: Clients may want to establish regional affinity between their applications and a specific replica, but Azure-managed routing doesn't provide a way to maintain this affinity.
5. No Client-Side Failover: Without the ability to target specific replicas, you cannot implement client-side failover strategies or disaster recovery logic that explicitly switches between regions based on your own health checks and business rules.

Introducing Regional Endpoints

Regional endpoints solve these challenges by providing direct access to specific geo-replicated regions through dedicated login server URLs. Instead of relying solely on the global endpoint (myregistry.azurecr.io) with Azure-managed routing, you can now target specific regional replicas using the pattern:

myregistry.<region-name>.geo.azurecr.io

For example:

• myregistry.eastus.geo.azurecr.io

• myregistry.westeurope.geo.azurecr.io

Important: Regional endpoints coexist with a geo-replicated registry's global endpoint at myregistry.azurecr.io. Enabling regional endpoints doesn't disable or replace the global endpoint - you can use both simultaneously. This allows you to use the global endpoint for most operations while selectively using regional endpoints when you need explicit regional control.

How It Works

Regional endpoints function as login servers—the URL endpoints you use to authenticate and interact with your registry—for specific geo-replicated regions. When you authenticate and interact with a regional endpoint instead of a registry's global endpoint, all your registry operations (authentication, artifact uploads/downloads, repository operations, and metadata actions) go directly to that specific regional replica, bypassing Azure-managed routing entirely.

Downloading layer blobs (the actual container image layers) still follows your registry's existing configuration:

• For registries without Private Endpoints or Dedicated Data Endpoints, layer blob downloads still redirect to Azure storage accounts (*.blob.core.windows.net).
• For registries with Private Endpoints or Dedicated Data Endpoints enabled, layer blob downloads redirect to the corresponding region's dedicated data endpoint (myregistry.<region-name>.data.azurecr.io).

Here's how the architecture compares:

Global Endpoint (Azure-Managed Routing):

Client → myregistry.azurecr.io (Azure-managed routing) → Geo-Replica with the Best Network Performance Profile ↓ Geo-Replica's Data Endpoint (blob storage or dedicated data endpoint)

Regional Endpoint (Customer-Specified Routing):

Client → myregistry.<region-name>.geo.azurecr.io (client-managed routing) → Specific Regional Geo-Replica ↓ Geo-Replica's Data Endpoint (blob storage or dedicated data endpoint)

Regional vs. Global Endpoints

Getting Started with Private Preview

Prerequisites

To participate in the regional endpoints private preview, you'll need:

• Premium SKU: Regional endpoints are available exclusively on Premium tier registries
• Azure CLI: Version 2.74.0 or later for the --regional-endpoints flag
• API version: The feature is available in all production regions in Azure Public Cloud via the 2026-01-01-preview ACR ARM API version

NOTE: During private preview, regional endpoints are only available in Azure Public Cloud. Support for Azure Government, Azure China, and other national clouds will be available in public preview and beyond.

NOTE: Regional endpoints can be enabled on any Premium SKU registry, even without geo-replication. A registry without geo-replication has a single geo-replica in the home region, which gets one regional endpoint URL. However, the feature is most useful when your registry has at least two geo-replicas.

Step 1: Register the feature flag

Register the RegionalEndpoints feature flag for your subscription:

az feature register \ --namespace Microsoft.ContainerRegistry \ --name RegionalEndpoints

The feature registration is auto-approved and takes approximately 1 hour to propagate. You can check the status with:

az feature show \ --namespace Microsoft.ContainerRegistry \ --name RegionalEndpoints

Wait until the state shows Registered before proceeding.

Step 2: Propagate the registration

Once the feature flag shows Registered, propagate the registration to your subscription's resource provider:

az provider register -n Microsoft.ContainerRegistry

Step 3: Install the preview CLI extension

Download the preview CLI extension wheel file from https://aka.ms/acr/regionalendpoints/download and install it:

az extension add \ --source acrregionalendpoint-1.0.0b1-py3-none-any.whl \ --allow-preview true

What to Expect

Once setup is complete, you can:

• Enable regional endpoints on both new and existing registries
• Access preview documentation
• Provide feedback via our GitHub roadmap

Technical Deep Dive

Enabling Regional Endpoints

Enabling regional endpoints is simple and can be done for both new and existing registries:

# Enable for new registry az acr create -n myregistry -g myrg -l <region-name> --regional-endpoints enabled --sku Premium # Enable for existing registry az acr update -n myregistry -g myrg --regional-endpoints enabled

When you enable regional endpoints, ACR automatically creates login server URLs for all your geo-replicated regions. There's no need to manually configure individual regions - they're all available immediately.

Authentication and Pushing/Pulling Images

Using regional endpoints follows the same authentication experience as a geo-replicated registry's global endpoint:

# Login to a specific regional endpoint az acr login --name myregistry --endpoint eastus # Tag an image with the regional endpoint URL docker tag myapp:v1 myregistry.eastus.geo.azurecr.io/myapp:v1 # Push images to the regional endpoint docker push myregistry.eastus.geo.azurecr.io/myapp:v1 # Pull images from the regional endpoint docker pull myregistry.eastus.geo.azurecr.io/myapp:v1

Regional endpoints support all the same authentication mechanisms as the global endpoint: Microsoft Entra, service principals, managed identities, and admin credentials.

Kubernetes Integration

One of the most powerful uses of regional endpoints is in Kubernetes deployments. You can specify regional endpoints directly in your deployment manifests, ensuring that Kubernetes clusters in specific regions always pull from their local replica:

# East US-based AKS 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-based AKS 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

Integration with Dedicated Data Endpoints

Regional endpoints work seamlessly with ACR's existing dedicated data endpoints feature. If your registry has dedicated data endpoints enabled, blob downloads from regional endpoints will automatically redirect to the dedicated data endpoints for that region, maintaining all the security benefits of scoped firewall rules without wildcard storage access.

Integration with Private Endpoints

For registries with Private Endpoints enabled, enabling regional endpoints creates an additional private IP address allocation for each geo-replicated region in all associated virtual networks (VNets). For example, if you have a registry with 3 existing geo-replicas and enable regional endpoints, each VNet with a private endpoint to your registry will consume 3 additional private IPs (one per regional endpoint).

Firewall and Network Configuration

When using regional endpoints, you'll need to configure your firewall rules to allow access to the specific endpoints you plan to use:

# Registry operations using regional endpoints myregistry.<region-name>.geo.azurecr.io # Registry operations using the existing global endpoint for Azure-managed routing myregistry.azurecr.io # Layer blob downloads (choose based on your registry configuration) myregistry.<region-name>.data.azurecr.io # If Private Endpoints or Dedicated Data Endpoints enabled *.blob.core.windows.net # If without Private Endpoints or Dedicated Data Endpoints

Related Resources

• Regional endpoints for geo-replicated registries (Preview)
• Geo-replication in Azure Container Registry
• Mitigate data exfiltration with dedicated data endpoints
• Connect privately to an Azure container registry using Azure Private Link
• Configure rules to access an Azure container registry behind a firewall