Importar imagens de contêiner para um registro de contêiner

  • Artigo

Você pode importar (copiar) com facilidade imagens de contêiner para um registro de contêiner do Azure sem usar de comandos do Docker. Por exemplo, importe imagens de um registro de desenvolvimento para um registro de produção ou copie imagens de base de um registro público.

O Registro de Contêiner do Azure manipula muitos cenários comuns para copiar imagens e outros artefatos de um registro existente:

  • Importar imagens de um registro público

  • Importar imagens ou artefatos OCI, incluindo gráficos Helm 3 de outro registro de contêiner do Azure, no mesmo ou em uma assinatura ou locatário diferentes dos do Azure

  • Importar de um registro de contêiner particular que não é do Azure

A importação de imagem para um registro de contêiner do Azure tem os seguintes benefícios em relação ao uso de comandos da CLI do Docker:

  • Se o ambiente do seu cliente não precisar de uma instalação local do Docker, você poderá importar qualquer imagem de contêiner, independentemente do tipo de sistema operacional com suporte.

  • Se você importar imagens de várias arquiteturas (como imagens oficiais do Docker), as imagens de todas as arquiteturas e plataformas especificadas na lista de manifestos serão copiadas.

  • Se você acessar o registro de destino, ele não precisará usar o ponto de extremidade público do Registro.

Importante

  • A importação de imagens requer o suporte ao registro externo RFC 7233. É recomendável usar um registro que dê suporte a intervalos RFC 7233 ao usar o comando az acr import com o URI do Registro para evitar falhas.

Limitações

  • O número máximo de manifestos para uma imagem importada é 50.
  • O tamanho máximo da camada para uma imagem importada de um registro público é de 2 GiB.

Para importar imagens de contêiner, este artigo requer que você execute a CLI do Azure no Azure Cloud Shell ou localmente (versão 2.0.55 ou posterior recomendada). Execute az --version para encontrar a versão. Se você precisa instalar ou atualizar, consulte Instalar a CLI do Azure.

Observação

Se for necessário distribuir imagens de contêiner idênticas em várias regiões do Azure, o Registro de Contêiner do Azure também suporta a replicação geográfica. Ao fazer replicação geográfica de um registro (SKU Premium necessário), você pode atender a várias regiões com nomes e marcas idênticos de imagem de um único registro.

Importante

As alterações na importação de imagem entre dois registros de contêiner do Azure foram introduzidas a partir de janeiro de 2021:

  • Importar de ou para um registro de contêiner do Azure restrito à rede requer que o registro restrito permita o acesso por serviços confiáveis para ignorar a rede. Por padrão, a configuração é habilitada, permitindo a importação. Se a configuração não estiver habilitada em um registro recém-criado com um ponto de extremidade privado ou com regras de firewall do registro, a importação falhará.
  • Em um registro de contêiner do Azure com restrição de rede existente que é usado como uma origem ou destino de importação, a habilitação desse recurso de segurança de rede é opcional, mas recomendada.

Pré-requisitos

Se você ainda não tiver um registro de contêiner do Azure, crie um. Para as etapas, consulte Início Rápido: criar um registro de contêiner privado usando a CLI do Azure.

Para importar uma imagem para um registro de contêiner do Azure, sua identidade deve ter permissões de gravação no registro de destino (pelo menos uma função de Contribuidor ou uma função personalizada que permite a ação importImage). Confira Funções e permissões do Registro de Contêiner do Azure.

Importar de um registro público

Importante

Para fazer a importação de um registro público para um registro de contêiner do Azure restrito à rede, é necessário que o registro restrito permita o acesso de serviços confiáveis para ignorar a rede. Por padrão, a configuração está habilitada, permitindo a importação. Se a configuração não estiver habilitada em um registro recém-criado com um ponto de extremidade privado ou com regras de firewall do registro, a importação falhará.

Importar do Hub do Docker

Por exemplo, use o comando az acr import para importar as imagens de várias arquiteturas hello-world:latest do Hub do Docker para um registro chamado myregistry. Como hello-world é uma imagem oficial do Hub do Docker, esta imagem está no repositório library padrão. Inclua o nome do repositório e, opcionalmente, uma marca no valor do parâmetro de imagem --source. (Opcionalmente, você pode identificar uma imagem pelo resumo do manifesto, em vez de usar marca, o que garante uma versão específica de uma imagem.)

az acr import \
  --name myregistry \
  --source docker.io/library/hello-world:latest \
  --image hello-world:latest

Você pode verificar que vários manifestos são associados esta imagem executando o comando az acr manifest list-metadata:

az acr manifest list-metadata \
  --name hello-world \
  --registry myregistry

Para importar um artefato por resumo sem adicionar marca:

az acr import \
   --name myregistry \
   --source docker.io/library/hello-world@sha256:abc123 \
   --repository hello-world

Se você tiver uma conta de Hub do Docker, recomendamos que use as credenciais ao importar uma imagem do Hub do Docker. Passe o nome de usuário do Hub do Docker e a senha ou um token de acesso pessoal como parâmetros para az acr import. O exemplo a seguir importa uma imagem pública do repositório tensorflow no Hub do Docker:

az acr import \
  --name myregistry \
  --source docker.io/tensorflow/tensorflow:latest-gpu \
  --image tensorflow:latest-gpu
  --username <Docker Hub user name>
  --password <Docker Hub token>

Importar do Registro de Contêiner da Microsoft

Por exemplo, importe a imagem mais recente do ltsc2019 Windows Server Core do repositório no windows Registro de Contêiner do Microsoft.

az acr import \
--name myregistry \
--source mcr.microsoft.com/windows/servercore:ltsc2019 \
--image servercore:ltsc2019

Importar de um registro de contêiner do Azure no mesmo locatário do AD

Você pode importar uma imagem de um registro de contêiner do Azure no mesmo locatário do AD usando permissões integradas do Microsoft Entra.

  • Sua identidade deve ter permissões do Microsoft Entra para ler do registro de origem (função Leitor) e importar para o registro de destino (função Colaborador ou uma função personalizada que permite a ação importImage).

  • O registro pode estar na mesmo assinatura ou em uma assinatura diferente do Azure no mesmo locatário do Active Directory.

  • O acesso público ao registro de origem pode ser desabilitado. Se o acesso público estiver desabilitado, especifique o registro de origem por ID de recurso em vez de por nome do servidor de logon do Registro.

  • O registro de origem e/ou o registro de destino com um ponto de extremidade privado ou regras de firewall do Registro devem garantir que o registro restrito permita que os serviços confiáveis acessem a rede.

Importar de um registro na mesma assinatura

Por exemplo, importe a imagem aci-helloworld:latest de um registro de origem mysourceregistry para myregistry na mesma assinatura do Azure.

az acr import \
  --name myregistry \
  --source mysourceregistry.azurecr.io/aci-helloworld:latest \
  --image aci-helloworld:latest

O exemplo a seguir importa a imagem aci-helloworld:latest para myregistry de um registro de origemmysourceregistry no qual o acesso ao ponto de extremidade público do Registro está desabilitado. Forneça a ID de recurso do registro de fonte com o parâmetro --registry. Observe que o parâmetro --source especifica somente o repositório de origem e o nome da imagem, não o nome de servidor de logon do registro.

az acr import \
  --name myregistry \
  --source aci-helloworld:latest \
  --image aci-helloworld:latest \
  --registry /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/sourceResourceGroup/providers/Microsoft.ContainerRegistry/registries/mysourceregistry

O exemplo a seguir importa uma imagem pelo resumo do manifesto (hash de SHA-256, representado como sha256:...) em vez de por marca:

az acr import \
  --name myregistry \
  --source mysourceregistry.azurecr.io/aci-helloworld@sha256:123456abcdefg

Importar um registro de uma assinatura diferente

Observação

Para importar uma imagem de um registro para outro, os registros de origem e de destino devem garantir que ambas as regiões sejam registradas para o ACR (Registro de Contêiner do Azure) nos provedores de recursos da assinatura.

No exemplo a seguir, mysourceregistry está em uma assinatura diferente de myregistry no mesmo locatário do Active Directory. Forneça a ID de recurso do registro de fonte com o parâmetro --registry. Observe que o parâmetro --source especifica somente o repositório de origem e o nome da imagem, não o nome de servidor de logon do registro.

az acr import \
  --name myregistry \
  --source aci-helloworld:latest \
  --image aci-hello-world:latest \
  --registry /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/sourceResourceGroup/providers/Microsoft.ContainerRegistry/registries/mysourceregistry

Importar de um registro usando as credenciais da entidade de serviço

Para importar de um registro que você não pode acessar usando as permissões integradas do Active Directory, você pode usar as credenciais principais do serviço (se disponíveis) para o registro de origem. Forneça a appID e a senha da entidade de serviço do Active Directory que tem acesso de ACRPull no registro de origem. O uso de uma entidade de serviço é útil para sistemas de compilação e outros sistemas autônomos que precisam importar imagens confiáveis para seu registro.

az acr import \
  --name myregistry \
  --source sourceregistry.azurecr.io/sourcerrepo:tag \
  --image targetimage:tag \
  --username <SP_App_ID> \
  --password <SP_Passwd>

Importar de um registro de contêiner do Azure em um locatário diferente do AD

Para importar de um registro de contêiner do Azure em um locatário diferente do Microsoft Entra, especifique o registro de origem pelo nome do servidor de logon e forneça credenciais que permitem o acesso de pull ao registro.

Importação de entre locatários com nome de usuário e senha

Por exemplo, use um token e senha no escopo do repositório ou a appID e a senha de uma entidade de serviço do Active Directory que tenha acesso ACRPull ao registro de origem.

az acr import \
  --name myregistry \
  --source sourceregistry.azurecr.io/sourcerrepo:tag \
  --image targetimage:tag \
  --username <SP_App_ID> \
  --password <SP_Passwd>

Importação entre locatários com token de acesso

Para acessar o registro de origem com uma identidade no locatário de origem que tem permissões de registro, você pode obter um token de acesso:

# Login to Azure CLI with the identity, for example a user-assigned managed identity
az login --identity --username <identity_ID>

# Get access token returned by `az account get-access-token`
az account get-access-token

No locatário de destino, passe o token de acesso como uma senha ao comando az acr import. O registro de origem especifica o nome do servidor de logon. Observe que nenhum nome de usuário é necessário neste comando:

az acr import \
  --name myregistry \
  --source sourceregistry.azurecr.io/sourcerrepo:tag \
  --image targetimage:tag \
  --password <access-token>

Observação

O locatário cruzado não funciona entre nuvens. Também não há suporte para a importação entre locatários em pontos de extremidade privados.

Importar de um registro de contêiner particular que não é do Azure

Importe uma imagem de um registro privado não Azure especificando credenciais que permitem o acesso por pull ao registro. Por exemplo, efetue o pull de uma imagem de um registro particular do Docker:

az acr import \
  --name myregistry \
  --source docker.io/sourcerepo/sourceimage:tag \
  --image sourceimage:tag \
  --username <username> \
  --password <password>

Próximas etapas

Neste artigo, você aprendeu sobre como importar imagens de contêiner para um registro de contêiner do Azure a partir de um registro público ou de outro registro particular.

  • Para saber opções adicionais de importação de imagem, consulte a referência do comando az acr import.