Georreplicação no Azure Container Registry

Ativar a geo-replicação para um Azure Container Registry (ACR) cria recursos de geo-réplica nas regiões da Azure à sua escolha. Quando faz upload de imagens para um registo geo-replicado, o conteúdo sincroniza-se automaticamente com todas as geo-replicas.

Com a geo-replicação:

  • Gerir um registo: Manter um único conjunto de credenciais, atribuições de funções, regras de rede e configuração do registo em todas as geo-réplicas.
  • Use um endpoint global: Referenciar myregistry.azurecr.io/myimage:tag em todas as suas compilações e implementações. O Azure encaminha pedidos para a geo-réplica com o melhor perfil de desempenho de rede para o cliente, que normalmente é a geo-réplica mais próxima. No entanto, se o cliente estiver equidistante de múltiplas geo-réplicas ou se a geo-réplica mais próxima não estiver disponível, os pedidos podem ser encaminhados para outro local.
  • Sincronização automática: Enviar etiquetas e digestões uma vez; O ACR replica o conteúdo e os metadados para todas as geo-réplicas.

A geo-replicação requer o SKU Premium.

Nota

Considerações sobre alta disponibilidade

Modelo de replicação

A geo-replicação ACR utiliza um modelo ativo-ativo.

  • Todas as geo-réplicas estão ativas e permitem escrita — pode transferir, obter e apagar imagens a partir de qualquer geo-réplica, não apenas da geo-réplica da região de origem.
  • Isto difere dos modelos de replicação primário-secundário, onde apenas uma região aceita escritas e as regiões secundárias são passivas.

Modelo de consistência

O ACR usa a consistência eventual.

  • Depois de enviar ou eliminar uma imagem em qualquer geo-réplica, o ACR acaba por replicar a alteração para todas as geo-réplicas em segundo plano.
  • O tempo de replicação depende do tamanho da imagem. Uma imagem ou tag enviada poderá não ficar imediatamente disponível para transferência noutras geo-réplicas se forem enviadas grandes quantidades de imagens ou imagens de grandes dimensões. De forma semelhante, uma imagem ou etiqueta eliminada pode ainda estar disponível para recolha noutras geo-réplicas até que a eliminação se propage.
  • O tempo necessário para criar uma nova geo-réplica depende da dimensão total do registo. Ao criar uma nova geo-réplica, as geo-réplicas existentes continuam a processar normalmente o tráfego de push, pull e delete. Não há uma janela de estado restrita ou degradação enquanto a nova geo-réplica se mantém em segundo plano.
  • Até que a replicação seja eventualmente concluída em segundo plano, uma geo-réplica pode não ter o conteúdo ou metadados mais recentes. Pode usar webhooks para receber notificações quando a replicação de uma imagem push específica é concluída em cada geo-réplica.

Importante

Falhas de consistência eventual a prever:

  • Envio seguido de extração imediata entre regiões — Enviar uma imagem para uma georréplica e obtê-la imediatamente a partir de outra georréplica pode falhar com manifest unknown até a replicação ficar concluída. Isto afeta frequentemente pipelines de CI/CD em que um executor de CI envia uma imagem e os pods em várias regiões tentam imediatamente transferi-la.
  • Condições de corrida na substituição de tags — Efetuar push de myapp:v1 e, pouco depois, voltar a efetuar push de myapp:v1 com um digest diferente (a mesma tag, mas conteúdo diferente) pode fazer com que diferentes geo-réplicas resolvam a mesma tag para digests diferentes durante a janela de replicação.
  • Propagação de eliminação — Eliminar uma etiqueta ou repositório numa região demora tempo a propagar-se. Os pulls de geo-réplicas onde a eliminação ainda não se propagou podem devolver o conteúdo eliminado.
  • Dispersão durante o failover a meio do push — Um push multicamada que atravessa um limite de failover com deteção do estado de funcionamento ou um evento de alternância de DNS pode fazer com que as camadas sejam colocadas numa georréplica e o manifesto noutra, o que se manifesta como erros de validação do manifesto ou blob unknown em operações de pull subsequentes. Veja falhas no Push com erros manifestos para mitigações.

Atenuações:

  • Incorpore lógica de repetição nas operações de obtenção que se seguem imediatamente a um envio entre regiões — aplique novas tentativas com recuo progressivo ou verifique o estado da replicação antes de efetuar a obtenção.
  • Utilize webhooks para receber notificações quando a replicação estiver concluída em cada georréplica antes de acionar extrações entre regiões.

Alta disponibilidade no plano de dados

A geo-replicação melhora a disponibilidade dos planos de dados ao manter imagens em múltiplas regiões. Se uma região sofrer uma falha, as imagens permanecem acessíveis a partir de outras geo-réplicas — empurrar, puxar e eliminar continuam a trabalhar nas restantes geo-réplicas.

A redundância de zonas está sempre ativada para geo-réplicas — a ACR distribui automaticamente os dados das réplicas por múltiplas zonas de disponibilidade para proteger contra interrupções zonais.

Nota

Se o seu registo utiliza uma chave gerida pelo cliente, reveja as orientações sobre ativação pós-falha e redundância do cofre de chaves para máxima resiliência.

Failover consciente da saúde

O ACR monitoriza automaticamente o estado de cada geo-réplica e redireciona o tráfego global dos endpoints para longe das geo-réplicas que não conseguem servir pedidos de forma fiável. Isto chama-se failover com reconhecimento do estado de saúde. O ACR encaminha o tráfego global dos endpoints com base na saúde do serviço ACR e na saúde da infraestrutura regional do Azure.

  • Automático e por registo: A saúde é avaliada por registo, não por região. Se uma degradação afetar apenas um subconjunto de registos numa região, apenas esses registos são redirecionados — outros registos na mesma região continuam a ser servidos localmente sem penalização de latência desnecessária.
  • Tempo: O redirecionamento de ponta a ponta é da ordem dos minutos, rápido o suficiente para detetar uma degradação regional real e lento o suficiente para suportar erros transitórios que se resolvem sozinhos. O DNS TTL pode adicionar atraso de propagação antes de todos os clientes mudarem para a nova região.
  • Não é necessária qualquer ação do cliente: Não existe um gatilho invocável pelo cliente. O failover consciente da saúde é totalmente gerido pela plataforma.
  • A reversão pós-falha é automática: Assim que a avaliação do estado de funcionamento regional de uma geo-réplica volta a ser aprovada, por exemplo, quando a infraestrutura regional do ACR ou do Azure recupera, o ponto final global pode retomar o encaminhamento do tráfego para a geo-réplica na região do Azure recuperada.
  • Não é desencadeado por limitação: O failover consciente da saúde é baseado em DNS e responde à saúde regional dos serviços ACR e à saúde da infraestrutura Azure. Não redireciona o tráfego com base nas respostas HTTP 429 (throttling). Se uma geo-réplica estiver a limitar os seus pedidos, mas a infraestrutura da região estiver saudável, o endpoint global continua a encaminhar os seus pedidos para essa geo-réplica. Para gerir a limitação, utilize endpoints regionais para distribuir cargas de trabalho por múltiplas geo-réplicas para melhor distribuição de capacidade.

Âmbito do failover consciente da saúde:

O failover health-aware aplica-se apenas a operações contra o endpoint global (myregistry.azurecr.io). Não se aplica a:

  • Endpoints regionais — Quando utilizas um endpoint regional (myregistry.<region>.geo.azurecr.io), estás a comunicar diretamente com uma geo-réplica específica. Se essa região se degradar, o ACR não redireciona automaticamente. Implemente o failover do lado do cliente mudando para um endpoint regional diferente.
  • Pontos finais de dados dedicados — Quando um ponto final do registo o redireciona para um ponto final de dados dedicado para transferir uma camada, mantém-se no ponto final de dados dessa região durante toda a transferência. A região é determinada à partida pelo endpoint do registo que respondeu à chamada blob-location.

Limitação durante o failover:

Os limites de limitação das operações da API são por réplica. Durante uma ativação pós-falha com monitorização do estado de funcionamento, o tráfego que estava distribuído por várias geo-réplicas pode passar a concentrar-se em grande medida nas geo-réplicas que permanecem no pool de encaminhamento do ponto final global. A capacidade planeia ter pelo menos duas ou três geo-réplicas para que o tráfego possa ser distribuído por múltiplas geo-réplicas saudáveis durante um failover. Os registos com apenas duas regiões podem atingir mais facilmente os limites de limitação por réplica quando uma região fica indisponível. Para mitigar, utilize os endpoints regionais para distribuir cargas de trabalho entre várias geo-réplicas e planeie a capacidade por réplica.

Como confirmar um failover:

  • Portal do Azure: Navegue até ao seu registo e selecione Estado do recurso na secção Ajuda para ver os sinais de degradação na plataforma.
  • CLI do Azure: Verifique o estado da replicação com az acr replication list --registry myregistry --output table. As geo-réplicas com problemas apresentam um estado diferente de online.
  • Azure Monitor: As métricas da plataforma são recolhidas automaticamente. Ative as Definições de Diagnóstico para registos de recursos para obter telemetria detalhada.

Comportamento em caso de falha na região de origem

A região de origem é a região onde originalmente criou o registo. Aloja o plano de controlo do registo, que gere a configuração do registo. A região de origem é fixa na criação e não pode ser alterada depois. Para mover um registo para outra região de origem, veja Relocate Azure Container Registry, que descreve um procedimento de reimplantação (criação de um novo registo), e não uma alteração no local.

Se a região de origem ficar indisponível, o efeito limita-se às operações do plano de controlo (gestão). Todas as operações do plano de dados continuam a funcionar através das restantes geo-réplicas.

O que continua a funcionar durante uma falha na região de origem:

  • Empurrar, puxar e eliminar imagens — Os clientes podem enviar, puxar e eliminar imagens de qualquer geo-réplica disponível usando o endpoint global (myregistry.azurecr.io) ou qualquer endpoint regional disponível (myregistry.<region>.geo.azurecr.io). O ACR encaminha automaticamente os pedidos globais de endpoint para uma geo-réplica saudável.
  • Autenticação — Todos os métodos de autenticação continuam a funcionar, incluindo o Microsoft Entra ID, identidades de serviço, identidades geridas e tokens no âmbito do repositório. Os clientes podem autenticar-se em qualquer geo-réplica disponível sem necessidade de alterar credenciais, tokens ou URLs de registo.
  • Entrega por Webhook — Webhooks configurados para as réplicas geográficas disponíveis continuam a acionar. Um único push resulta em eventos de webhook da geo-réplica de destino, além de eventos de cada geo-réplica à medida que a replicação é concluída. Os consumidores de webhook devem ser concebidos para processar múltiplos eventos por cada imagem enviada por push e eliminar duplicados conforme necessário.
  • Endpoints regionais — Se os endpoints regionais estiverem ativados, continuam a funcionar de forma independente. Os clientes podem ligar-se diretamente a geo-réplicas específicas utilizando URLs de ponto final regionais.

O que não está disponível durante uma interrupção na região de origem:

  • Encaminhamento global de pontos finais para a geo-réplica da região principal — A deteção do estado de funcionamento do ACR interrompe automaticamente o encaminhamento do tráfego do ponto final global para a geo-réplica da região principal e redireciona-o para geo-réplicas em bom estado.
  • Extremidade regional da região principal — A extremidade regional da região principal (myregistry.<home-region>.geo.azurecr.io) não está disponível enquanto a região principal estiver indisponível. Os endpoints regionais para outras geo-réplicas continuam a funcionar de forma independente.
  • Alterações na configuração do registo — Não pode modificar propriedades do registo, como regras de rede, definições de replicação ou configurações de zonas de disponibilidade até que a região de origem recupere.
  • Tarefas ACR — As tarefas estão associadas à região de origem e não são executadas enquanto esta estiver indisponível.

Considerações sobre o nível de serviço e os limites

Os escalões de serviço e limites do Azure Container Registry aplicam-se independentemente a cada geo-réplica.

Certos limites de nível de serviço têm a seguinte consideração especial:

  • Limites de armazenamento: Os limites de armazenamento para o seu nível de serviço são partilhados por todas as réplicas geográficas. Por exemplo, se enviares uma imagem de 1 GiB e ela for replicada para 5 geo-réplicas, apenas 1 GiB é contabilizado para os limites máximos de armazenamento do teu escalão.
  • Limites de taxa de API: Os limites de limitação das operações da API, como o número de leituras e escritas por minuto, são específicos de uma réplica geográfica. Utilize endpoints regionais para distribuir cargas de trabalho entre várias geo-réplicas, de modo a melhorar a distribuição da capacidade e evitar concentrar todo o tráfego numa única geo-réplica.

Para mais informações sobre níveis e limites de serviço, consulte camadas de serviço ACR.

Considerações sobre preços

  • Faturação de armazenamento: O armazenamento é faturado por geo-réplica. Por exemplo, uma imagem de 1 GiB replicada para 5 geo-réplicas é cobrada como 5 GiB de armazenamento (1 GiB × 5 geo-réplicas).
  • Transferência de dados: A geo-replicação pode reduzir custos ao permitir pushes e pulls de imagens dentro da região, evitando assim custos de transferência de dados entre regiões durante estas operações push ou pull. No entanto, os encargos de transferência de dados entre regiões continuam a aplicar-se quando o ACR replica o conteúdo carregado para outras geo-réplicas, como parte da consistência eventual.

Para mais informações, consulte preços ACR.

Adicionar ou eliminar geo-réplicas

Permissões necessárias

Para gerir geo-réplicas, a sua identidade precisa destas permissões:

Permissão Description
Microsoft.ContainerRegistry/registries/read Obtenha propriedades registadas
Microsoft.ContainerRegistry/registries/write Criar ou atualizar propriedades do registo
Microsoft.ContainerRegistry/registries/replications/read Lista de geo-réplicas
Microsoft.ContainerRegistry/registries/replications/write Criar ou atualizar uma geo-réplica
Microsoft.ContainerRegistry/registries/replications/delete Eliminar uma geo-réplica
Microsoft.ContainerRegistry/registries/replications/operationStatuses/read Obter o estado da operação de geo-replicação

portal do Azure

  1. Vai ao teu registo no portal Azure.
  2. Em Serviços, selecione Geo-replicações.
  3. No mapa:
    • Hexágono azul: Região de origem (onde criou o registo)
    • Hexágonos verdes: Regiões disponíveis
    • Hexágonos cinzentos: Regiões indisponíveis
  4. Seleciona um hexágono verde e depois seleciona Criar.

Captura de ecrã do mapa de geo-replicação no portal Azure.

CLI do Azure (Interface de Linha de Comando da Azure)

# Create a replica
az acr replication create --registry myregistry --location eastus

# List replicas
az acr replication list --registry myregistry --output table

# Delete a replica
az acr replication delete --registry myregistry --name eastus

Para mais comandos, consulte az acr replicação.

Endpoint global de um registo com replicação geográfica

Depois de configurar a geo-replicação, pode empurrar, puxar ou eliminar conteúdo do seu registo através do endpoint global do registo (myregistry.azurecr.io).

Como funcionam os endpoints globais

Quando envia, puxa ou elimina através do endpoint global, o ACR encaminha o pedido para a geo-réplica com o melhor perfil de desempenho de rede para o cliente.

  • A georréplica com o melhor perfil de desempenho de rede a partir do cliente é geralmente a georréplica mais próxima.
  • No entanto, se o cliente estiver equidistante de múltiplas geo-réplicas ou se a geo-réplica mais próxima não estiver disponível, os pedidos podem ser encaminhados para outro local.
  • A ACR gere este encaminhamento. Não controlas qual geo-réplica trata de um pedido específico.

Diagrama que mostra o fluxo global de pedidos de endpoint: um cliente liga-se a myregistry.azurecr.io, o encaminhamento gerido por Azure seleciona a geo-réplica com o melhor perfil de desempenho de rede, e a geo-réplica emite um redirecionamento 307 para o seu endpoint de dados para downloads de blobs.

Usando o endpoint global

Autenticar:

az acr login --name myregistry

Identifique e envie uma imagem:

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

Obter uma imagem:

docker pull myregistry.azurecr.io/myapp:v1

Importar uma imagem:

az acr import \
  --name myregistry \
  --source mcr.microsoft.com/hello-world:latest \
  --image hello-world:latest

Manifesto de implementação do Kubernetes:

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

Excluir temporariamente uma geo-réplica do encaminhamento global de endpoints

Pode excluir uma geo-réplica do encaminhamento global dos endpoints desativando a --global-endpoint-routing definição para uma geo-réplica específica. Isto é útil para manutenção ou resolução de problemas, ou quando sabe que uma geo-réplica específica ou região do Azure está a sofrer degradação. Pode até desativar o encaminhamento global de pontos finais para a geo-réplica da região de origem — a região de origem só é utilizada para operações do plano de controlo, e o tráfego do respetivo plano de dados pode ser excluído com segurança do encaminhamento global. Para mais informações sobre o que a região de origem controla, veja Comportamento de interrupção da região de origem.

  • Quando a --global-endpoint-routing definição para uma geo-réplica específica é definida para false, o ACR para de encaminhar pedidos para essa geo-réplica específica para pedidos que vão para o endpoint global.
  • Os dados continuam a sincronizar-se bidirecionalmente com uma geo-réplica mesmo que o encaminhamento global do endpoint esteja desativado para essa geo-réplica específica. Cada imagem enviada para o registo a partir de qualquer região enquanto a geo-réplica está excluída do encaminhamento global continua a ser replicada para ela. Quando reativas a geo-réplica, ela está imediatamente pronta para servir o tráfego sem qualquer janela de recuperação.
  • Assim, as quotas de armazenamento e os custos continuam a acumular-se para essa geo-réplica.
  • Se os pontos finais regionais estiverem ativados, o URL do ponto final regional da geo-réplica (myregistry.<region-name>.geo.azurecr.io) continua a funcionar mesmo quando o encaminhamento do ponto final global está desativado. --global-endpoint-routing controla apenas a participação da geo-réplica no encaminhamento do ponto final global.
# Exclude a geo-replica from global endpoint routing
az acr replication update --registry myregistry --name eastus \
  --global-endpoint-routing false

# Re-enable a geo-replica in global endpoint routing
az acr replication update --registry myregistry --name eastus \
  --global-endpoint-routing true

Nota

Em CLI do Azure 2.86.0 e posteriores, --region-endpoint-enabled foi renomeado para --global-endpoint-routing. O nome antigo da bandeira está obsoleto e foi removido no CLI do Azure 2.87.0 (junho de 2026). Se tiveres scripts ou automação existentes que usam --region-endpoint-enabled, atualiza-os para usar --global-endpoint-routing.

Importante

Não execute uma cache DNS duradoura para o endpoint global. Quando desativas o encaminhamento global de endpoints para uma geo-réplica, o ACR purga registos DNS do lado do servidor num caminho rápido. No entanto, se os clientes executarem a sua própria cache DNS de longa duração para o endpoint global, esses clientes continuam a resolver para a geo-réplica desativada até que a cache do cliente expire. Uma cache de longa duração faz --global-endpoint-routing false parecer que não tem efeito do ponto de vista do cliente.

Dica

Pode, opcionalmente, usar uma cache DNS de curta duração para os push para o endpoint global. Um pin DNS de curta duração, ajustado à duração de um único push, ajuda a garantir a consistência do push ao manter todas as camadas e o manifesto para a mesma geo-réplica. Isto também evita o ressalto do DNS, que pode causar erros manifestos — ver Resolução de Problemas.

Pontos de extremidade regionais de um registo geo-replicado (Pré-visualização)

Os endpoints regionais dão-lhe URLs dedicados para cada réplica, permitindo-lhe especificar exatamente qual a geo-réplica regional que gere o seu pedido de push, pull ou delete:

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

Use endpoints regionais quando precisar de:

Scenario Description
Roteamento previsível Garantir que uma carga de trabalho utiliza sempre uma réplica específica para afinidade dentro da região.
Failover do lado do cliente Implemente a sua própria lógica de failover que alterne explicitamente entre regiões com base nas suas próprias verificações de saúde do lado do cliente, independentemente das verificações de saúde do Azure que apoiam o endpoint global.
Consistência de push-pull Direcione para uma geo-réplica específica as operações de envio, obtenção e eliminação, para evitar atrasos na replicação e condições de corrida de consistência eventual em pipelines de CI/CD ou manifestos de implantação de contentores.
Troubleshooting Teste ou depure uma réplica regional específica.
Planeamento de capacidade Saiba exatamente que réplica serve cada carga de trabalho para poderes planear a capacidade por réplica e evitar limitações.

Importante

O failover baseado no estado de funcionamento não se aplica a endpoints regionais. Quando usas um endpoint regional, estás a falar diretamente com uma geo-réplica específica. Se essa região se degradar, o ACR não redireciona automaticamente. O failover health-aware aplica-se apenas a operações contra o endpoint global (myregistry.azurecr.io). Consulte o cenário de failover do lado do cliente na tabela anterior.

Nota

A limitação é por réplica, não por registo. Quando fixas cargas de trabalho num único endpoint regional, concentras todo o tráfego nessa geo-réplica. Se todos os seus clusters utilizarem o mesmo endpoint regional, poderá atingir os limites de limitação por região dessa geo-réplica durante os períodos de pico. Para mitigar, distribua cargas de trabalho por múltiplos endpoints regionais para uma melhor distribuição de capacidade, ou use o endpoint global para cargas de trabalho que não necessitem de fixação explícita.

Os endpoints regionais coexistem com os endpoints globais

Ativar endpoints regionais não desativa nem substitui o endpoint global. Pode usar ambos simultaneamente:

  • Use o endpoint global (myregistry.azurecr.io) se preferir o encaminhamento automático gerido por Azure entre réplicas geográficas.
  • Use terminais regionais (myregistry.<region-name>.geo.azurecr.io) se quiser um controlo de encaminhamento mais detalhado do lado do cliente, contornando completamente o encaminhamento Azure-gerido do endpoint global.

Como funcionam os endpoints regionais

Os endpoints regionais funcionam como servidores de login para réplicas geográficas específicas. Quando autenticas e interages com um endpoint regional em vez do endpoint global do registo, todas as tuas operações de registo (autenticação, uploads/downloads de artefactos, operações de repositório e ações de metadados) vão diretamente para essa réplica regional específica, ignorando completamente o encaminhamento gerido pelo Azure.

As transferências de blobs de camada (ou seja, as camadas reais da imagem do contentor) continuam a obedecer à configuração existente do seu registo:

  • Registos sem pontos finais privados ou pontos finais de dados dedicados: Quando transfere camadas da imagem a partir de uma geo-réplica específica, as transferências dos blobs das camadas são redirecionadas para contas de armazenamento do Azure (*.blob.core.windows.net).
  • Registos com pontos finais privados ou pontos finais de dados dedicados ativados: Quando descarrega camadas de imagem de uma geo-réplica específica, as transferências dos blobs de camada são redirecionadas para o ponto final de dados dedicado da região correspondente (myregistry.<region-name>.data.azurecr.io).

O diagrama seguinte ilustra o fluxo regional de pedidos ao ponto terminal:

Diagrama que mostra o fluxo do pedido do endpoint regional: um cliente estabelece ligação com myregistry.region.geo.azurecr.io, o pedido é encaminhado diretamente para a geo-réplica regional específica, e a geo-réplica emite um redirecionamento 307 para o respetivo endpoint de dados para transferência de blobs.

Nota

As imagens e os identificadores carregados para uma geo-réplica através do endpoint regional continuarão a ser propagados para todas as outras geo-réplicas, em regime de consistência eventual.

Pré-requisitos para endpoints regionais

  • SKU Premium — Os pontos finais regionais estão disponíveis exclusivamente nos registos do escalão Premium.
  • CLI do Azure — Versão 2.86.0 ou posterior. Todos os comandos regionais de endpoints (--regional-endpoints, az acr show-endpoints, az acr login --endpoint) estão disponíveis nativamente em CLI do Azure 2.86.0+.

Importante

Se instalaste anteriormente a extensão CLI de pré-visualização privada: Se participou na pré-visualização privada dos endpoints regionais e instalou a acrregionalendpoint extensão CLI, desinstale-a para evitar conflitos com os comandos CLI incorporados:

az extension remove --name acrregionalendpoint

Pode verificar se a extensão já não está instalada com:

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

Nota

Os endpoints regionais podem ser ativados em qualquer registo de SKU Premium, mesmo sem geo-replicação. Um registo sem geo-replicação tem uma única réplica na região de origem, que recebe um URL de ponto final regional. No entanto, a funcionalidade é mais útil quando a sua lista de registos tem pelo menos duas réplicas geográficas.

Ativar endpoints regionais

Pode ativar endpoints regionais ao criar um novo registo ou atualizar um registo existente.

Crie um novo registo com endpoints regionais ativados:

az acr create \
  -n myregistry \
  -g myrg \
  -l regionname \
  --sku Premium \
  --regional-endpoints enabled

Ativar endpoints regionais num registo existente:

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

Os endpoints regionais estão ativados ao nível do registo e aplicam-se a todas as geo-réplicas. Não é possível ativar endpoints regionais para réplicas individuais. Quando ativas endpoints regionais, o Azure Container Registry cria automaticamente URLs de servidor de login para cada uma das tuas réplicas geográficas.

Trabalhar com endpoints regionais

Autentique-se e utilize pontos de extremidade regionais

Os endpoints regionais suportam os mesmos métodos de autenticação que o endpoint global: Microsoft Entra ID, principais de serviço, identidades geridas e credenciais de administrador.

Importante

Re-autenticar ao mudar de endpoint. Os tokens ACR funcionam tanto em endpoints globais como regionais. No entanto, ferramentas de contentores como o Docker e o containerd armazenam credenciais por nome de host, por isso mudar do endpoint global para um endpoint regional (ou entre endpoints regionais) requer um novo az acr login para esse nome de host. Para o AKS, o fornecedor de credenciais ACR Kubernetes trata disto automaticamente quando o endpoint muda.

Iniciar sessão num endpoint regional específico:

az acr login --name myregistry --endpoint eastus

Identifica e envia uma imagem para um endpoint regional. As imagens e os identificadores carregados para uma geo-réplica através do endpoint regional continuarão a ser propagados para todas as outras geo-réplicas, em regime de consistência eventual.

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

Extrai uma imagem de um endpoint regional:

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

Utilizar endpoints regionais incorporados nos manifestos de implementação

Podes especificar endpoints regionais diretamente nos manifestos de implementação do Kubernetes se precisares de fixar cargas de trabalho em regiões específicas. Isto garante que os clusters em regiões específicas obtêm sempre dados da sua réplica colocalizada, proporcionando roteamento previsível e latência reduzida.

Implementação do cluster do Leste dos EUA:

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

Implantação de clusters na Europa Ocidental:

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

Ao usar diferentes endpoints regionais nos manifestos de cada cluster, pode optar por garantir que cada cluster extrai da sua réplica local em vez de depender do encaminhamento gerido pelo Azure.

Para informações sobre autenticação de Azure Kubernetes Service (AKS) com ACR, veja Autenticar com Azure Container Registry a partir de Azure Kubernetes Service.

Utilize endpoints regionais com encaminhamento baseado em DNS sem alterar os manifestos de implantação

Se não quiser manter manifestos de implementação diferentes por região, pode manter todos os manifestos apontados para o endpoint global (myregistry.azurecr.io) e usar redes definidas por software ou um gestor regional de tráfego para resolver o endpoint global para o endpoint regional apropriado, com base no tráfego da região de origem. Isto alcança os mesmos objetivos de colocation que os endpoints regionais (roteamento previsível e redução da latência) sem incorporar URLs específicas de cada região nos seus manifestos de implementação.

Para informações sobre autenticação de Azure Kubernetes Service (AKS) com ACR, veja Autenticar com Azure Container Registry a partir de Azure Kubernetes Service.

Importar de geo-réplicas específicas usando endpoints regionais

Ao importar imagens entre registos, pode usar endpoints regionais para importar a partir de uma georréplica específica do registo de origem. Isto é útil em cenários onde se querem caminhos de rede previsíveis ou é necessário importar de uma réplica numa região específica.

az acr import \
  --name mydownstreamregistry \
  --source myupstreamregistry.westeurope.geo.azurecr.io/myapp:v1 \
  --image myapp:v1

Considerações de rede de endpoints regionais

Regras de firewall

Se estiver a usar regras de firewall ACR ou firewalls personalizados com endpoints regionais, configure as regras de firewall para permitir o acesso a:

Ponto final Purpose
myregistry.<region-name>.geo.azurecr.io Ponto final regional para operações de registo
myregistry.azurecr.io Endpoint global (se também utilizado)
myregistry.<region-name>.data.azurecr.io Transferências de camadas (se utilizar endpoints privados ou endpoints de dados dedicados)
*.blob.core.windows.net Transferências de camadas (se não estiver a utilizar os pontos finais privados ou os pontos finais de dados dedicados)

Pontos finais privados

Quando um endpoint privado é criado para um registo dentro de uma rede virtual, o recurso do endpoint privado expõe vários IPs privados de rede virtual que cobrem todas as superfícies do endpoint do registo — o endpoint global, todos os endpoints regionais (se os endpoints regionais estiverem ativados) e todos os endpoints de dados dedicados (ativados automaticamente quando um endpoint privado é configurado).

Cada superfície de endpoint consome um endereço IP privado da sub-rede virtual. Planeie o tamanho da sua sub-rede em conformidade:

  • 1 IP para o endpoint global (myregistry.azurecr.io)
  • 1 IP por geo-réplica para endpoints de dados dedicados (myregistry.<region>.data.azurecr.io) — sempre ativado em registos com pelo menos um endpoint privado
  • 1 IP por geo-réplica para endpoints regionais (myregistry.<region>.geo.azurecr.io) — apenas se os endpoints regionais estiverem ativados

Exemplo: Um registo com 3 geo-réplicas e endpoints regionais ativados requer 1 (global) + 3 (dados) + 3 (regional) = 7 endereços IP privados por recurso de endpoint privado. Sem endpoints regionais, o mesmo registo requer 1 + 3 = 4 endereços IP privados.

Com muitas geo-réplicas, a criação de endpoints privados pode falhar se a sub-rede ficar sem IPs disponíveis. Para mais informações, consulte Ligar privadamente a um registo a partir de uma rede virtual usando endpoints privados.

Endpoints de dados dedicados

Quando os endpoints regionais são ativados juntamente com os endpoints de dados dedicados — quer sejam ativados explicitamente quer sejam ativados automaticamente quando existe pelo menos um endpoint privado configurado — as transferências de blobs de camada provenientes de endpoints regionais são automaticamente redirecionadas para o endpoint de dados dedicado da geo-réplica (myregistry.<region-name>.data.azurecr.io). O redirecionamento mantém-se sempre dentro da mesma região do endpoint regional — um pull de myregistry.eastus.geo.azurecr.io sempre redireciona para myregistry.eastus.data.azurecr.io, nunca para um endpoint de dados numa região diferente.

Esta garantia da mesma região também se aplica ao retirar do endpoint global. O ACR encaminha a solicitação para a geo-réplica com o melhor perfil de desempenho de rede para o cliente, e a geo-réplica que processa o pedido emite um redirecionamento 307 para o respetivo endpoint de dados dedicado — nunca entre regiões.

Dica

Ative endpoints de dados dedicados para um desempenho ótimo dentro da região e uma URL dedicada para downloads de camadas:

az acr update -n <registry-name> --data-endpoint-enabled true

Para mais informações, consulte Endpoints de dados dedicados em Azure Container Registry.

Referência do ponto final

Para uma referência completa de todos os tipos de pontos finais do registo, formatos de URL e opções da CLI que os controlam, consulte Azure Container Registry endpoint reference.

Solução de problemas

O push falha com erros manifestos

Um docker push é uma sequência de pedidos HTTP: carregamentos de blobs para cada camada, seguidos de um carregamento do manifesto que referencia essas camadas pelo respetivo resumo criptográfico. Alguns resolvedores DNS Linux não armazenam respostas em cache de forma consistente. Se existirem várias geo-réplicas em regiões próximas, o DNS pode resolver para réplicas diferentes durante um único push (DNS bouncing), fazendo com que o manifesto push faça referência a camadas que foram enviadas para uma geo-réplica diferente. Como a replicação é eventualmente consistente, o manifesto pode cair numa réplica que ainda não tem as camadas que referencia, e a validação do manifesto falha.

Soluções (por ordem de preferência):

  1. Utilize pontos finais regionais para encaminhar o envio para uma única georréplica de uma ponta à outra. Cada subsolicitação (início de sessão, carregamentos de blobs, carregamento do manifesto) é enviada para a mesma réplica geográfica. Esta é a solução mais limpa e a abordagem recomendada para qualquer pipeline onde a consistência push/pull seja importante.
  2. Utilize uma cache DNS de curta duração como dnsmasq limitada à duração de um único push. Para VMs Linux no Azure, consulte opções de resolução de nomes DNS. A fixação deve durar apenas durante o push — não mantenha uma cache DNS de longa duração para o endpoint global, pois interfere com --global-endpoint-routing false e com o encaminhamento de failover com monitorização do estado de funcionamento.
  3. Defina etapas de publicação idempotentes para que as novas tentativas acionadas por falhas durante o envio sejam seguras de executar.

Criação de geo-réplicas parada para registos habilitados com endpoint privado

Este problema geralmente surge quando a identidade que cria uma geo-réplica para um registo com pontos finais privados ativados não tem permissões suficientes para criar recursos de rede de ponto final privado.

Solução:

  • Para resolver, apague manualmente a geo-réplica que ficou presa no estado de provisionamento.
  • Depois, certifique-se de que a identidade tem a permissão Microsoft.Network/privateEndpoints/privateLinkServiceProxies/write antes de criar uma geo-réplica.
  • Verifique também se todas as sub-redes privadas de endpoints ligadas ao registo têm capacidade IP livre. Se qualquer sub-rede em qualquer rede virtual conectada não tiver IPs livres suficientes, o provisionamento da replicação falha e é revertido. A réplica aparece brevemente num Creating estado e depois é removida. O erro resultante não identifica qual sub-rede ou rede virtual está esgotada. Para orientações sobre dimensionamento de sub-rede, consulte Ligar privadamente a um registo usando endpoints privados.

A criação de georréplicas falha em registos que têm um endpoint privado com IP estático

A adição de uma geo-réplica falha quando o endpoint privado do registo está configurado com atribuição estática de IP privado.

Cada geo-réplica tem o seu próprio endpoint de dados dedicado, que é exposto no endpoint privado como um membro com o ID de grupo registry e um nome de membro registry_data_<region>. Quando adicionas uma nova geo-réplica, o ACR pede ao endpoint privado que adicione o membro para o endpoint de dados da nova região. Um endpoint privado configurado com alocação dinâmica de IP prevê automaticamente o IP do novo membro. Um endpoint privado configurado com alocação IP estática tem um conjunto fixo de configurações de IP definido no momento da criação e não adiciona automaticamente o novo membro, pelo que a criação de réplicas falha com um erro semelhante a:

Failed to replicate private endpoint. Private Endpoint <id> contains static ipconfigurations:
[... GroupId: registry, MemberName: registry_data_<existing-region> ...] and it's missing these
membernames/groupids requested by Private Link service [GroupId: registry, MemberName:
registry_data_<new-region>, IpVersion: IPv4]. Private Endpoint needs to be reconfigured with
missing memberNames.

Para verificar o método de alocação do endpoint privado de um registo, inspecione as PrivateIPAllocationMethod configurações de IP na interface de rede do endpoint privado. O endpoint privado refere-se a uma interface de rede que contém estas configurações IP, por isso primeiro obtenha o ID da interface de rede, depois inspecione as suas configurações IP:

nicId=$(az network private-endpoint show \
  --name <private-endpoint-name> \
  --resource-group <resource-group-name> \
  --query "networkInterfaces[0].id" --output tsv)

az network nic show --ids "$nicId" \
  --query "ipConfigurations[].{Name:name, PrivateIPAddress:privateIPAddress, PrivateIPAllocationMethod:privateIPAllocationMethod}" \
  --output table

Soluções:

  • Utilize a atribuição dinâmica de IP para o ponto final privado, caso preveja adicionar georréplicas mais tarde. Com a alocação dinâmica, o ACR provisiona automaticamente o membro do endpoint de dados para cada nova região. Esta é a abordagem recomendada.
  • Crie o endpoint privado depois de existirem todas as geo-réplicas , se for necessária alocação IP estática. Adicione primeiro todas as geo-réplicas, depois crie o endpoint privado com IP estático para que a sua configuração de IP inclua um membro para cada endpoint de dados da região existente. Depois de criar um endpoint privado com IP estático desta forma, não pode adicionar mais geo-réplicas sem reconfigurar o endpoint privado para adicionar o novo membro.

Conteúdo relacionado

  • Last updated on