Cache de artefato no Registro de Contêiner do Azure

O recurso cache de artefato permite que os usuários armazenem em cache imagens de contêiner em um registro de contêiner particular. O cache de artefato está disponível nas camadas de serviço Básico, Standard e Premium.

O cache de artefato aprimora o gerenciamento de imagens de contêiner fornecendo uma solução de armazenamento em cache para repositórios públicos e particulares.

O cache de artefato oferece operações de pull mais rápidas e confiáveis por meio do ACR (Registro de Contêiner do Azure), utilizando recursos como replicação geográfica e suporte à zona de disponibilidade para efetuar pulls de imagem com mais velocidade e maior disponibilidade.

O cache de artefato permite que os registros armazenados em cache possam ser acessados por redes particulares para os usuários atendam perfeitamente as configurações de firewall e aos padrões de conformidade.

O cache de artefatos aborda o desafio dos limites de pull impostos por registros públicos. Recomendamos que os usuários autentiquem as regras de cache deles com as respectivas credenciais de origem upstream. Em seguida, efetue pull de imagens do ACR local para ajudar a reduzir os limites de taxa.

Terminologia

• Regra de Cache - Uma Regra de Cache é uma regra que você pode criar para efetuar pull de artefatos de um repositório com suporte para o cache.

  • Uma regra de cache contém quatro partes:

    • Nome da Regra - O nome da regra de cache. Por exemplo, Hello-World-Cache.

    • Origem - O nome do Registro de Origem.

    • Caminho do Repositório - O caminho de origem do repositório para localizar e recuperar artefatos que você deseja armazenar em cache. Por exemplo, docker.io/library/hello-world.

    • Novo Namespace do Repositório do ACR - O nome do novo caminho do repositório para armazenamento. Por exemplo, hello-world. O Repositório não pode existir dentro da instância do ACR.

• Credenciais

  • As credenciais são um conjunto de nome de usuário e senha para o registro de origem. Você precisa de Credenciais para autenticar com um repositório público ou privado. As credenciais contêm quatro partes

    • Credenciais - O nome de suas credenciais.

    • Servidor de Logon do Registro de Contêiner - O servidor de logon do registro de origem.

    • Autenticação de Origem - Os locais do cofre de chaves para armazenar credenciais.

    • Segredos de Nome de Usuário e Senha - Os segredos que contém o nome de usuário e a senha.

Limitações

• O cache só ocorrerá depois que pelo menos um pull de imagem for concluído na imagem de contêiner disponível. Para cada nova imagem disponível, um novo pull de imagem deve ser concluído. O cache de artefato não efetua pull automático de novas marcas de imagens quando uma nova marca está disponível. Ele está no roteiro, mas não é compatível com esta versão.

• O cache de artefato só dá suporte a 1.000 regras de cache.

Compatibilidade com upstream

Atualmente, o cache de artefato dá suporte aos seguintes registros upstream:

Aviso

Os clientes precisam gerar um conjunto de credenciais para o conteúdo de origem do Docker Hub.

Registros Upstream	Suporte	Disponibilidade
Docker Hub	Dá suporte somente a pulls autenticados.	CLI do Azure, portal do Azure
Registro de Artefato da Microsoft	Compatível apenas com pulls não autenticados.	CLI do Azure, portal do Azure
Galeria Pública do Registro de Contêiner Elástico (ECR) da AWS	Compatível apenas com pulls não autenticados.	CLI do Azure, portal do Azure
Registro de Contêiner do GitHub	Dá suporte a pulls autenticados e não autenticados.	CLI do Azure, portal do Azure
Quay	Dá suporte a pulls autenticados e não autenticados.	CLI do Azure, portal do Azure
registry.k8s.io	Dá suporte a pulls autenticados e não autenticados.	CLI do Azure
Registro de contêiner do Google	Dá suporte a pulls autenticados e não autenticados.	CLI do Azure

Curingas

Curinga use asteriscos (*) para corresponder a vários caminhos dentro do registro de imagem de contêiner. Atualmente, o cache de artefato dá suporte aos seguintes curingas:

Observação

O mapa de regras de cache do Repositório de Destino => Repositório de Origem.

Curinga no Nível do Registro

O curinga no nível do Registro permite que você armazene em cache todos os repositórios de um registro upstream.

Regra de cache	Mapeamento	Exemplo
contoso.azurecr.io/* => mcr.microsoft.com/*	Mapeamento para todas as imagens em ACR para MCR.	contoso.azurecr.io/myapp/image1 => mcr.microsoft.com/myapp/image1 contoso.azurecr.io/myapp/image2 => mcr.microsoft.com/myapp/image2

Curinga no nível do repositório

O curinga no nível do repositório permite armazenar em cache todos os repositórios de um mapeamento de registro upstream para o prefixo do repositório.

Regra de cache	Mapeamento	Exemplo
contoso.azurecr.io/dotnet/* => mcr.microsoft.com/dotnet/*	Mapeando repositórios específicos no ACR para repositórios correspondentes no MCR.	contoso.azurecr.io/dotnet/sdk => mcr.microsoft.com/dotnet/sdk contoso.azurecr.io/dotnet/runtime => mcr.microsoft.com/dotnet/runtime
contoso.azurecr.io/library/dotnet/* => mcr.microsoft.com/dotnet/* contoso.azurecr.io/library/python/* => docker.io/library/python/*	Mapeando repositórios específicos no ACR para repositórios de diferentes registros upstream.	contoso.azurecr.io/library/dotnet/app1 => mcr.microsoft.com/dotnet/app1 contoso.azurecr.io/library/python/app3 => docker.io/library/python/app3

Limitações para regras de cache baseadas em curinga

As regras de cache curinga usam asteriscos (*) para corresponder a vários caminhos dentro do registro de imagem de contêiner. Essas regras não podem se sobrepor a outras regras de cache curinga. Em outras palavras, se você tiver uma regra de cache curinga para um determinado caminho do Registro, não poderá adicionar outra regra curinga que se sobreponha a ela.

Aqui estão alguns exemplos de regras sobrepostas:

Exemplo 1:

Regra de cache existente: contoso.azurecr.io/* => mcr.microsoft.com/*
Novo cache sendo adicionado: contoso.azurecr.io/library/* => docker.io/library/*

A adição da nova regra de cache é bloqueada porque o caminho contoso.azurecr.io/library/* do repositório de destino se sobrepõe à regra curinga existente contoso.azurecr.io/*.

Exemplo 2:

Regra de cache existente: contoso.azurecr.io/library/* =>mcr.microsoft.com/library/*
Novo cache sendo adicionado: contoso.azurecr.io/library/dotnet/* =>docker.io/library/dotnet/*

A adição da nova regra de cache é bloqueada porque o caminho do repositório de destino contoso.azurecr.io/library/dotnet/* se sobrepõe à regra curinga existente contoso.azurecr.io/library/*.

Limitações para regras de cache estáticas/fixas

As regras de cache estáticas ou fixas são mais específicas e não usam curingas. Eles podem se sobrepor às regras de cache baseadas em curinga. Se uma regra de cache especificar um caminho de repositório fixo, ela poderá se sobrepor a uma regra de cache baseada em curinga.

Exemplo 1:

Regra de cache existente: contoso.azurecr.io/* =>mcr.microsoft.com/*
Novo cache sendo adicionado: contoso.azurecr.io/library/dotnet =>docker.io/library/dotnet

A adição da nova regra de cache é permitida porque contoso.azurecr.io/library/dotnet é um caminho estático e pode se sobrepor à regra de cache curinga contoso.azurecr.io/*.

Habilitar o cache do artefato - CLI do Azure

É possível habilitar o cache de artefato no Registro de Contêiner do Azure com ou sem autenticação usando a CLI do Azure seguindo as etapas.

Pré-requisitos

• Você pode usar o Azure Cloud Shell ou uma instalação local da CLI do Azure para executar os exemplos de comandos incluídos neste artigo. Para usá-lo localmente, é necessária a versão 2.46.0 ou posterior. Execute az --version para localizar a versão. Se você precisa instalar ou atualizar, consulte Instalar a CLI do Azure.
• Você tem um Key Vault existente para armazenar as credenciais. Saiba mais sobre como criar e armazenar credenciais em um Key Vault.
• Você pode definir e recuperar segredos do seu Key Vault. Saiba mais sobre como definir e recuperar um segredo do Key Vault.

Configurar e criar uma regra de cache sem as credenciais.

1. Execute o comando az acr Cache create para criar uma regra de armazenamento em cache.

   • Por exemplo, para criar uma regra de Cache sem as credenciais para um determinado Registro de Contêiner do Azure MyRegistry.

   az acr Cache create -r MyRegistry -n MyRule -s docker.io/library/ubuntu -t ubuntu-
   

2. Execute o comando az acr Cache show para mostrar uma regra de armazenamento em cache.

   • Por exemplo, mostrar uma regra de armazenamento em cache para um determinado MyRegistry Registro de Contêiner do Azure.

    az acr Cache show -r MyRegistry -n MyRule
   

Criar as credenciais

Antes de configurar as Credenciais, você deve criar e armazenar segredos no Azure KeyVault e recuperar os segredos do Key Vault. Saiba mais sobre como criar e armazenar credenciais em um Key Vault. E definir e recuperar um segredo do Key Vault.

1. Execute o comando az acr credential set create para criar as credenciais.

   • Por exemplo, criar as credenciais para determinado MyRegistry Registro de Contêiner do Azure.

   az acr credential-set create 
   -r MyRegistry \
   -n MyDockerHubCredSet \
   -l docker.io \ 
   -u https://MyKeyvault.vault.azure.net/secrets/usernamesecret \
   -p https://MyKeyvault.vault.azure.net/secrets/passwordsecret
   

2. Execute az acr credential set update para atualizar a ID do segredo do KV de nome de usuário ou senha em um conjunto de credenciais.

   • Por exemplo, para atualizar a ID do segredo de KV do nome de usuário ou senha nas credenciais de determinado Registro de Contêiner do Azure MyRegistry.

   az acr credential-set update -r MyRegistry -n MyDockerHubCredSet -p https://MyKeyvault.vault.azure.net/secrets/newsecretname
   

3. Execute az-acr-credential-set-show para mostrar as credenciais.

   • Por exemplo, mostrar um conjunto de credenciais em um determinado MyRegistry Registro de Contêiner do Azure.

   az acr credential-set show -r MyRegistry -n MyDockerHubCredSet
   

Configurar e criar uma regra de cache com as credenciais

1. Execute o comando az acr cache create para criar uma regra de cache.

   • Por exemplo, criar uma regra de armazenamento em cache com as credenciais para um determinado MyRegistry Registro de Contêiner do Azure.

   az acr cache create -r MyRegistry -n MyRule -s docker.io/library/ubuntu -t ubuntu -c MyDockerHubCredSet
   

2. Execute o comando az acr cache update para atualizar as credenciais em uma regra de armazenamento em cache.

   • Por exemplo, atualizar as credenciais em uma regra de armazenamento em cache para um determinado MyRegistry Registro de Contêiner do Azure.

   az acr cache update -r MyRegistry -n MyRule -c NewCredSet
   

   • Por exemplo, remover as credenciais de uma regra de armazenamento em cache existente para um determinado MyRegistry Registro de Contêiner do Azure.

   az acr cache update -r MyRegistry -n MyRule --remove-cred-set
   

3. Execute o comando az acr cache show para mostrar uma regra de cache.

   • Por exemplo, para mostrar uma regra de cache para um determinado MyRegistry Registro de Contêiner do Azure.

    az acr cache show -r MyRegistry -n MyRule
   

Atribuir permissões ao Key Vault usando políticas de acesso (herdado)

1. Obter a ID principal da identidade do sistema em uso para acessar o Key Vault.

   PRINCIPAL_ID=$(az acr credential-set show 
                   -n MyDockerHubCredSet \ 
                   -r MyRegistry  \
                   --query 'identity.principalId' \ 
                   -o tsv) 
   

2. Execute o comando az keyvault set-policy para atribuir o acesso ao Key Vault, antes de efetuar pull da imagem.

   • Por exemplo, atribuir permissões para as credenciais acessar o segredo do KeyVault

   az keyvault set-policy --name MyKeyVault \
   --object-id $PRINCIPAL_ID \
   --secret-permissions get
   

Efetuar pull da imagem

1. Efetue pull da imagem do cache usando o comando do Docker pelo nome do servidor de logon do registro, pelo nome do repositório e pela marca desejada.

   • Por exemplo, para efetuar pull da imagem do repositório hello-world com a marca desejada latest para um determinado servidor de logon do registro myregistry.azurecr.io.

    docker pull myregistry.azurecr.io/hello-world:latest
   

Limpar os recursos

1. Execute o comando az acr cache list para listar as regras de armazenamento em cache no Registro de Contêiner do Azure.

   • Por exemplo, listar as regras de armazenamento em cache para um determinado MyRegistry Registro de Contêiner do Azure.

    az acr cache list -r MyRegistry
   

2. Execute o comando az acr cache delete para excluir uma regra de armazenamento em cache.

   • Por exemplo, para excluir uma regra de cache para um determinado MyRegistry Registro de Contêiner do Azure.

   az acr cache delete -r MyRegistry -n MyRule
   

3. Execute az acr credential set list para listar as credenciais em um Registro de Contêiner do Azure.

   • Por exemplo, listar as credenciais para determinado MyRegistry Registro de Contêiner do Azure.

   az acr credential-set list -r MyRegistry
   

4. Execute az-acr-credential-set-delete para excluir as credenciais.

   • Por exemplo, para excluir as credenciais para determinado MyRegistry Registro de Contêiner do Azure.

   az acr credential-set delete -r MyRegistry -n MyDockerHubCredSet
   

Habilitar o cache de artefato – portal do Azure

É possível habilitar o cache de artefato no Registro de Contêiner do Azure com ou sem autenticação usando o portal do Azure seguindo as etapas.

Pré-requisitos

• Entre no Portal do Azure
• Você tem um Key Vault existente para armazenar credenciais. Saiba mais sobre como criar e armazenar credenciais em um Key Vault.
• Você tem os cofres de chaves existentes sem os RBAC (controles de acesso baseado em função).

Configurar o cache de artefato sem credenciais

Siga as etapas para criar uma regra de cache no portal do Azure.

1. Navegue até o Registro de Contêiner do Azure.

2. No Menu lateral, em Serviços, selecione Cache.

   

3. Selecione Criar Regra.

   

4. Uma janela para Nova regra de cache será exibida.

   

5. Insira o Nome da regra.

6. Selecione Registro de Origem no menu suspenso.

7. Insira o Caminho do Repositório para os artefatos que deseja armazenar em cache.

8. Você poderá ignorar a Autenticação se não estiver acessando um repositório privado nem executando um pull autenticado.

9. Em Destino, insira o nome do Novo Namespace do Repositório do ACR para armazenar os artefatos armazenados em cache.

   

10. Selecione Salvar.

11. Efetue pull da imagem do cache usando o comando do Docker pelo nome do servidor de logon do registro, pelo nome do repositório e pela marca desejada.

    • Por exemplo, para efetuar pull da imagem do repositório hello-world com a marca desejada latest para um determinado servidor de logon do registro myregistry.azurecr.io.

     docker pull myregistry.azurecr.io/hello-world:latest
    

Configurar o cache de artefato com a autenticação

Siga as etapas para criar uma regra de cache no portal do Azure.

1. Navegue até o Registro de Contêiner do Azure.

2. No Menu lateral, em Serviços, selecione Cache.

   

3. Selecione Criar Regra.

   

4. Uma janela para Nova regra de cache será exibida.

   

5. Insira o Nome da regra.

6. Selecione Registro de Origem no menu suspenso.

7. Insira o Caminho do Repositório para os artefatos que deseja armazenar em cache.

8. Para adicionar a autenticação ao repositório, marque a caixa Autenticação.

9. Escolha Criar credenciais para criar um conjunto de credenciais para armazenar o nome de usuário e a senha do registro de origem. Saiba como criar credenciais.

10. Se as credenciais estiverem prontas, escolha Selecionar credenciais no menu suspenso.

11. Em Destino, insira o nome do Novo Namespace do Repositório do ACR para armazenar os artefatos armazenados em cache.

    

12. Selecione Salvar.

13. Efetue pull da imagem do cache usando o comando do Docker pelo nome do servidor de logon do registro, pelo nome do repositório e pela marca desejada.

    • Por exemplo, para efetuar pull da imagem do repositório hello-world com a marca desejada latest para um determinado servidor de logon do registro myregistry.azurecr.io.

     docker pull myregistry.azurecr.io/hello-world:latest
    

Criar credenciais

Antes de configurar as Credenciais, você precisa criar e armazenar segredos no Azure KeyVault e recuperar os segredos do Key Vault. Saiba mais sobre como criar e armazenar credenciais em um Key Vault. E definir e recuperar um segredo do Key Vault.

1. Navegue até Credenciais>Criar credenciais.

   

   

2. Insira Nome para as novas credenciais do registro de origem.

3. Selecione uma Autenticação de Origem. Atualmente, o cache de artefato dá suporte a Selecionar do Key Vault e Inserir URIs dos segredos.

4. Para a opção Selecionar do Key Vault, saiba mais sobre como criar credenciais usando o cofre de chaves.

5. Selecione Criar.

Próximas etapas

• Avance para o próximo artigo para acompanhar o guia de solução de problemas do Cache do Registro.