Determinismo sobre magia: a engenharia por trás dos Regional Endpoints do Azure Container Registry
TL;DR: O Azure Container Registry (ACR) lançou os Regional Endpoints, que oferecem DNS nominais por réplica (ex.: contoso.eastus.geo.azurecr.io). Isso resolve o roteamento opaco do Traffic Manager, permitindo que equipes brasileiras com exigências de data residency escolham explicitamente qual réplica usar, sem perder o failover automático do endpoint global. O trade-off principal: determinismo significa que não há reroteamento silencioso em caso de falha.
Por Zoey Li, Huangli Wu, Johnson Shi, Wei Meng
Introdução
O Azure Container Registry (ACR) suporta geo-replication: um único recurso de registry com réplicas active-active em múltiplas regiões do Azure. Você faz push ou pull através de qualquer réplica, e o ACR replica o conteúdo de forma assíncrona para todas as outras.
Para registries geo-replicados, o ACR expõe um endpoint global — myregistry.azurecr.io — sustentado pelo Azure Traffic Manager (TM), que roteia requisições com base em performance de rede. Isso funciona bem para a maioria das cargas de trabalho. Mas "automático" também é "opaco": os clientes não conseguem ver ou influenciar qual região o TM escolhe. Para equipes com exigências de data residency ou lógica própria de failover, não saber qual réplica atendeu a requisição não era suficiente.
Este artigo é um mergulho profundo na engenharia dos Regional Endpoints: nomes DNS por réplica que permitem aos clientes mirar explicitamente uma única réplica do registry, preservando o endpoint global como ponto de entrada para failover automático. Vamos percorrer a topologia DNS, como a autenticação permanece portátil entre endpoints, a estratégia de certificados, a integração com private endpoints e os trade-offs que fizemos para manter o roteamento determinístico.
O Problema: Roteamento Opaco, Sem Controle do Cliente
O roteamento baseado em performance do Traffic Manager é uma caixa-preta do ponto de vista do cliente. O sistema escolhe a "melhor" região para cada resolução de DNS, mas os clientes não podem influenciar ou prever essa escolha. Isso criou vários pontos de dor:
- Roteamento imprevisível: Um cliente em uma região específica não consegue garantir que atingirá a réplica local. Mudanças na topologia de rede, timing das sondas do TM e cache de DNS introduzem não-determinismo. Diagnosticar picos de latência exige primeiro descobrir qual região atendeu a requisição.
- Lacunas de isolamento de rede: Empresas com requisitos rigorosos de data residency precisam de tratamento determinístico de requisições dentro da região. O endpoint global pode rotear cross-region, o que pode não satisfazer esses requisitos. Uma grande instituição financeira relatou construir registries single-region duplicados por geografia como workaround — abandonando a geo-replication completamente.
- Sem failover do lado do cliente: Clientes que queriam controle de failover (ex.: "tentar local, cair para DR region") não tinham alvos por região endereçáveis para configurar em mirrors do containerd ou lógica de retry.
- Confiança reduzida na geo-replication: Alguns clientes desabilitaram a geo-replication porque não conseguiam verificar se ela estava funcionando como esperado. Sem endereçabilidade por região, não podiam confirmar a localidade dos dados ou medir performance por réplica.
O que são os Regional Endpoints
Regional Endpoints fornecem um nome DNS dedicado para cada região de réplica:
myregistry.<region>.geo.azurecr.io
Por exemplo, um registry contoso com réplicas em East US e West Europe ganha:
- contoso.eastus.geo.azurecr.io → resolve para a réplica de East US
- contoso.westeurope.geo.azurecr.io → resolve para a réplica de West Europe
- contoso.azurecr.io → endpoint global inalterado com roteamento TM e auto-failover
Propriedades principais:
- Coexistência: Regional endpoints existem junto com o endpoint global. Habilitá-los não muda nada no comportamento existente do endpoint global.
- Sem auto-failover no regional (por design): Uma requisição para contoso.eastus.geo.azurecr.io vai para East US. Se East US estiver fora do ar, a requisição falha. Este é o trade-off explícito — determinismo significa sem reroteamento silencioso.
- Global continua sendo o ponto de entrada para failover: Clientes que querem failover automático continuam usando o endpoint global, agora aprimorado com health-aware routing. Regional endpoints complementam, não substituem, o endpoint global.
- Registries DNL: Registries usando Deterministic Name Labels incluem o hash no hostname (ex.: contoso-ffb4cphwfsc2gbgg.eastus.geo.azurecr.io).
Mergulho na Arquitetura
Infraestrutura DNS
Cada réplica ganha um hostname estável — contoso.eastus.geo.azurecr.io. Para acesso público, ele resolve via CNAME para o servidor regional do ACR. Para acesso via private endpoint, ele resolve através da zona privatelink (
Como a Autenticação Funciona
Quando um cliente chama um regional endpoint, o desafio de autenticação (auth challenge) usa o hostname regional para o token endpoint. No entanto, o token em si é escopo do nome global do registry (service=contoso.azurecr.io), tornando os tokens interoperáveis entre todos os endpoints para o mesmo registry e escopo solicitado.
A escolha de design chave: o realm usa o host regional (para que o token endpoint corresponda ao hostname com o qual o cliente está falando), mas o service permanece global (para que os tokens sejam portáteis). Um token obtido de contoso.eastus.geo.azurecr.io funciona igualmente contra contoso.azurecr.io ou contoso.westeurope.geo.azurecr.io.
Isso significa que os clientes não precisam de stores de credenciais separadas por região — mas o Docker exige um docker login por hostname porque ele chaveia o armazenamento de credenciais pela URL do registry.
Integração com Private Endpoint
Regional endpoints reutilizam o grupo de private endpoints existente do registry. Quando regional endpoints são habilitados, novos membros do grupo da forma registry_
Consumo de IP: Habilitar regional endpoints adiciona N IPs privados (um por região de réplica) à linha de base existente de 1 + N (1 global + N data). Total com regional endpoints: 1 + 2×N IPs privados. Planeje a capacidade da subnet adequadamente.
Quando regional endpoints são habilitados em um registry que já tem private endpoints, as conexões de PE são atualizadas de forma assíncrona para incluir os novos membros regionais do grupo.
Estratégia de Certificados
Os certificados TLS são estendidos com entradas SAN wildcard por região (ex.: .
Ciclo de Vida e Reversibilidade
Regional endpoints são uma funcionalidade em nível de registry. Uma vez habilitada, cada réplica ganha automaticamente um hostname regional. A funcionalidade segue as operações padrão de registry e réplica:
- Habilitar (az acr update --regional-endpoints enabled): Registros DNS públicos são criados para todas as réplicas existentes. Se private endpoints existirem, eles são atualizados assincronamente para incluir novos membros regionais.
- Adicionar réplica: A nova região ganha automaticamente seu registro DNS regional. Se private endpoints existirem, eles são atualizados para incluir a nova região.
- Remover réplica: O registro DNS regional daquela região é removido. Se private endpoints existirem, o membro correspondente é removido.
- Desabilitar (az acr update --regional-endpoints disabled): Todos os registros DNS regionais são removidos. Se private endpoints existirem, os membros regionais são removidos. O endpoint global continua funcionando durante todo o processo. A funcionalidade pode ser reabilitada depois.
Isso é separado da propriedade por replicação --global-endpoint-routing (anteriormente --region-endpoint-enabled, renomeada no Azure CLI 2.87.0), que controla se uma réplica participa do roteamento do Traffic Manager no endpoint global. Essa propriedade não tem efeito no acesso ao regional endpoint.
Trade-offs de Design
Regional Endpoints tornam a região explícita, então intencionalmente não fazem auto-failover. Se East US estiver fora do ar, contoso.eastus.geo.azurecr.io falha — não significa silenciosamente West US. Esse é o ponto: determinismo significa sem reroteamento silencioso. Clientes que querem failover automático continuam usando o endpoint global.
Outros trade-offs que fizemos:
- Docker login é por hostname. Tokens são interoperáveis entre endpoints, mas stores de credenciais são escopo do hostname. az acr login --endpoint
fornece um atalho conveniente. - Habilitação all-or-nothing. Regional endpoints são habilitados para todas as réplicas simultaneamente — você não pode habilitar para uma região e não para outra. Isso simplifica o plano de controle e evita confusão de estado parcial.
- Mais IPs privados. Cada regional endpoint adiciona um IP privado por PE. Planeje para 1 + 2×N IPs para N réplicas.
- Replication lag não é mascarado. Um pull para contoso.eastus.geo.azurecr.io falhará se a imagem ainda não tiver replicado para East US. Regional endpoints garantem afinidade de região, não disponibilidade de dados. Para workflows de push-then-immediate-pull, use retries ou verifique o status da replicação antes de puxar de uma região diferente.
O que os Clientes Devem Saber
Habilitando Regional Endpoints
Requer Azure CLI 2.86.0 ou superior.
# Habilitar no registry existente
az acr update -n myregistry --regional-endpoints enabled
# Verificar endpoints
az acr show-endpoints -n myregistry
Autenticação
# Login em um regional endpoint
az acr login -n myregistry --endpoint eastus
# Ou manualmente com Docker (tokens são interoperáveis)
TOKEN=$(az acr login -n myregistry --expose-token --query accessToken -o tsv)
echo $TOKEN | docker login myregistry.eastus.geo.azurecr.io -u 00000000-0000-0000-0000-000000000000 --password-stdin
Tokens são interoperáveis — um token obtido de qualquer endpoint (regional ou global) funciona em todos os endpoints. Docker exige um docker login separado por hostname, já que ele chaveia credenciais na URL do registry.
Desabilitando Roteamento TM
O comando existente az acr replication update --global-endpoint-routing disabled remove uma região do roteamento do Traffic Manager no endpoint global. Isso não afeta o acesso direto ao regional endpoint — contoso.eastus.geo.azurecr.io permanece acessível independentemente do status do endpoint TM.
Rollout e Segurança
A funcionalidade é projetada para adoção segura e incremental:
- Aditivo: Habilitar cria novos hostnames DNS. Registros e comportamento do endpoint global existentes permanecem intocados.
- Reversível: Desabilitar remove os registros DNS regionais. O endpoint global continua funcionando durante todo o processo.
- Domínio de falha isolado: Um problema no regional endpoint afeta apenas o tráfego explicitamente enviado para aquele hostname. O tráfego do endpoint global não é afetado.
- Nenhuma infraestrutura do lado do cliente necessária: Sem agentes, sidecars ou serviços adicionais para implantar.
A funcionalidade foi validada através de testes de integração.
Resultado e Próximos Passos
Regional Endpoints completam a história de endereçabilidade para registries geo-replicados. Os clientes agora têm dois padrões de acesso complementares:
- Endpoint global (contoso.azurecr.io): Roteamento automático com failover health-aware. Melhor para workloads que querem resiliência sem sobrecarga operacional.
- Regional endpoints (contoso.
.geo.azurecr.io ): Acesso determinístico, fixado à região. Melhor para conformidade, troubleshooting e estratégias de failover controladas pelo cliente.
Juntos, eles dão aos clientes tanto controle explícito quanto failover automático — a combinação que antes era impossível sem abandonar a geo-replication.
Olhando adiante, estamos explorando maneiras de melhorar o comportamento de pull quando o conteúdo ainda não foi replicado localmente — abordando a limitação de replication lag sem sacrificar a afinidade de região.
Artigo originalmente publicado por Zoey Li, Huangli Wu, Johnson Shi, Wei Meng em Azure Updates - Latest from Azure Charts.
Perguntas Frequentes
-
O que muda no meu fluxo de autenticação com os Regional Endpoints?
- Tokens são interoperáveis entre endpoints regionais e global. Um token obtido via contoso.eastus.geo.azurecr.io funciona em contoso.azurecr.io. Porém, o Docker armazena credenciais por hostname, então é necessário um docker login por endpoint regional. O comando az acr login --endpoint
simplifica esse processo.
- Tokens são interoperáveis entre endpoints regionais e global. Um token obtido via contoso.eastus.geo.azurecr.io funciona em contoso.azurecr.io. Porém, o Docker armazena credenciais por hostname, então é necessário um docker login por endpoint regional. O comando az acr login --endpoint
-
Quantos IPs privados a mais vou precisar no meu VNet?
- Com regional endpoints habilitados, o total de IPs privados passa a ser 1 + 2×N (1 global + N data endpoints + N regionais). Para N réplicas, planeje o subnet capacity adicionando N IPs além do baseline existente. A atualização das conexões de private endpoint é assíncrona.
-
O que acontece com o failover automático se eu usar um regional endpoint?
- Regional endpoints não fazem auto-failover por design. Se a região East US falhar, contoso.eastus.geo.azurecr.io falhará — sem reroteamento silencioso para West US. Para failover automático, continue usando o endpoint global (contoso.azurecr.io), que agora conta com health-aware routing.
-
Posso habilitar regional endpoints para apenas uma réplica do meu registry?
- Não. A habilitação é all-or-nothing: ao ativar o recurso, todas as réplicas existentes e futuras recebem automaticamente um DNS regional. Isso simplifica o plano de controle e evita estados parciais. Se você remover uma réplica, o DNS regional correspondente é removido.
-
Como o replication lag afeta pulls via regional endpoints?
- Regional endpoints garantem afinidade com a região, não disponibilidade de dados. Um pull para contoso.eastus.geo.azurecr.io falhará se a imagem ainda não tiver replicado para East US. Para workflows de push-then-immediate-pull, use retries ou verifique o status da replicação antes de puxar de outra região.
