Migração manual para repositórios `gcr.io` no Artifact Registry

Este documento explica como configurar manualmente repositórios no Artifact Registry.gcr.io

Se quiser criar gcr.iorepositórios no Artifact Registry com chaves de encriptação geridas pelo cliente (CMEK), conclua os passos em Antes de começar e, em seguida, siga as instruções em Criação manual de repositórios.

Antes de começar

1. Instale a CLI Google Cloud se ainda não estiver instalada. Para uma instalação existente, execute o seguinte comando para atualizar os componentes para as versões mais recentes:

   gcloud components update
   

2. Ative as APIs Artifact Registry e Resource Manager. A CLI gcloud usa a API Resource Manager para verificar uma das autorizações necessárias.

   Execute o seguinte comando:

   gcloud services enable \
       cloudresourcemanager.googleapis.com \
       artifactregistry.googleapis.com
   

3. Saiba mais sobre os preços do Artifact Registry antes de iniciar a transição.

Funções necessárias

Para receber as autorizações de que precisa para configurar repositórios do gcr.io, peça ao seu administrador que lhe conceda as seguintes funções do IAM:

• Para criar repositórios do Artifact Registry e conceder acesso a repositórios individuais: Administrador do Artifact Registry (roles/artifactregistry.admin) no Google Cloud projeto
• Para ver e gerir a configuração do Container Registry existente aplicada aos contentores de armazenamento do Cloud Storage: Administrador de armazenamento (roles/storage.admin) no Google Cloud projeto
• Para criar um repositório gcr.io na primeira vez que envia uma imagem para um nome de anfitrião gcr.io: Artifact Registry Create-on-push Writer (roles/artifactregistry.createOnPushWriter) no projeto Google Cloud
• Para conceder acesso ao repositório ao nível do projeto: Administrador de IAM do projeto (roles/resourcemanager.projectIamAdmin) no Google Cloud projeto
• Para listar os serviços ativados numa organização: Visitante de recursos do Google Cloud (roles/cloudasset.viewer) na organização

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Limitações

Aplicam-se as seguintes limitações aos repositórios do gcr.io Artifact Registry:

• Quando faz a transição do Container Registry, não pode mapear um anfitrião do Container Registry para um repositório do Artifact Registry num projeto diferente.

• Cada nome de anfitrião do Container Registry é mapeado apenas para um repositório do Artifact Registry gcr.io correspondente na mesma multirregião.

• Os nomes dos repositórios gcr.io são predefinidos e não os pode modificar.

Se precisar de mais controlo sobre a localização dos seus repositórios, pode fazer a transição para pkg.dev repositórios no Artifact Registry. Uma vez que os repositórios não têm suporte para o domínio gcr.io, esta abordagem de transição requer mais alterações à sua automatização e fluxos de trabalho existentes.pkg.dev Consulte o artigo Escolha uma opção de transição para saber mais sobre as diferenças entre funcionalidades.

Crie repositórios

Crie repositórios gcr.io para poder configurar o acesso para os seus utilizadores e copiar imagens existentes do Container Registry para o Artifact Registry antes de ativar o redirecionamento.

Criação manual de repositórios

Crie manualmente repositórios gcr.io se quiser usar chaves de encriptação geridas pelo cliente (CMEK) para encriptar o conteúdo do repositório ou se existir uma restrição de localização na suaGoogle Cloud organização que bloqueie a criação de novos recursos em localizações específicas.

Para criar manualmente um repositório gcr.io:

1. Se estiver a usar a CMEK, crie a chave que vai usar com este repositório e conceda autorizações para usar a chave. Consulte o artigo Ativar chaves de encriptação geridas pelo cliente.

2. Adicione o repositório.

   Consola

   1. Abra a página Repositórios na Google Cloud consola.

      Abra a página Repositórios

   2. Clique em Criar repositório.

   3. Especifique o nome do repositório.

      Nome do anfitrião do Container Registry	Nome do repositório do Artifact Registry
      gcr.io	gcr.io
      asia.gcr.io	asia.gcr.io
      eu.gcr.io	eu.gcr.io
      us.gcr.io	us.gcr.io

   4. Especifique o Docker como o formato do repositório.

   5. Em Tipo de localização, especifique a localização multirregional para o repositório:

      Nome do anfitrião do Container Registry	Localização do repositório do Artifact Registry	Nome do repositório do Artifact Registry
      gcr.io	us	gcr.io
      asia.gcr.io	asia	asia.gcr.io
      eu.gcr.io	europa	eu.gcr.io
      us.gcr.io	us	us.gcr.io

   6. Adicione uma descrição para o repositório. Não inclua dados confidenciais, uma vez que as descrições dos repositórios não são encriptadas.

   7. Na secção Encriptação, escolha o mecanismo de encriptação para o repositório.

      • Google-managed encryption key - Encriptar o conteúdo do repositório com um Google-owned and Google-managed encryption key.
      • Chave gerida pelo cliente: encriptar o conteúdo do repositório com uma chave que controla através do Cloud Key Management Service. Para ver instruções de configuração de chaves, consulte o artigo Configurar CMEK para repositórios.

   8. Clique em Criar.

   gcloud

   Execute o seguinte comando para criar um novo repositório:

   gcloud artifacts repositories create REPOSITORY \
       --repository-format=docker \
       --location=LOCATION \
       --description=DESCRIPTION \
       --kms-key=KMS-KEY
   

   Substitua os seguintes valores:

   • REPOSITORY é o nome do repositório.

     Nome do anfitrião do Container Registry	Nome do repositório do Artifact Registry
     gcr.io	gcr.io
     asia.gcr.io	asia.gcr.io
     eu.gcr.io	eu.gcr.io
     us.gcr.io	us.gcr.io

   • LOCATION é a região múltipla do repositório:

     Nome do anfitrião do Container Registry	Localização do repositório do Artifact Registry	Nome do repositório do Artifact Registry
     gcr.io	us	gcr.io
     asia.gcr.io	asia	asia.gcr.io
     eu.gcr.io	europa	eu.gcr.io
     us.gcr.io	us	us.gcr.io

   • DESCRIPTION é uma descrição do repositório. Não inclua dados confidenciais, uma vez que as descrições dos repositórios não são encriptadas.

   • KMS-KEY é o caminho completo para a chave de encriptação do Cloud KMS, se estiver a usar uma chave de encriptação gerida pelo cliente para encriptar o conteúdo do repositório. O caminho está no formato:

     projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

     Substitua os seguintes valores:

     • KMS-PROJECT é o projeto onde a sua chave está armazenada.
     • KMS-LOCATION é a localização da chave.
     • KEY-RING é o nome do conjunto de chaves.
     • KEY é o nome da chave.

   Pode confirmar que o repositório foi criado listando os seus repositórios com o seguinte comando:

   gcloud artifacts repositories list
   

Antes de redirecionar o tráfego para os novos repositórios, tem de se certificar de que a automatização existente consegue aceder ao repositório. O passo seguinte é configurar as autorizações para conceder acesso aos repositórios.

Conceda autorizações a repositórios

O Container Registry usa funções do Cloud Storage para controlar o acesso. O Artifact Registry tem as suas próprias funções do IAM, e estas funções separam as funções de leitura, escrita e administração do repositório de forma mais clara do que o Container Registry.

Para mapear rapidamente as autorizações existentes concedidas em contentores de armazenamento para as funções sugeridas do Artifact Registry, use a ferramenta de mapeamento de funções.

Em alternativa, pode ver uma lista de responsáveis com acesso aos contentores de armazenamento através da Google Cloud consola.

1. Na Google Cloud consola, aceda à página Recipientes do Cloud Storage.
   

   Aceda aos contentores

2. Clique no contentor de armazenamento do anfitrião do registo que quer ver. Nos nomes dos contentores, PROJECT-ID é o seu Google Cloud ID do projeto.

   • gcr.io: artifacts.PROJECT-ID.appspot.com
   • asia.gcr.io: asia.artifacts.PROJECT-ID.appspot.com
   • eu.gcr.io: eu.artifacts.PROJECT-ID.appspot.com
   • us.gcr.io: us.artifacts.PROJECT-ID.appspot.com

3. Clique no separador Autorizações.

4. No separador Autorizações, clique no subseparador Vista por função.

5. Expanda uma função para ver os responsáveis que têm essa função.

A lista inclui funções de IAM concedidas diretamente no contentor e funções herdadas do projeto principal. Com base na função, pode escolher a função do Artifact Registry mais adequada para conceder.

Cloud Storage e funções básicas

Conceda aos utilizadores e às contas de serviço que acedem atualmente ao Container Registry acesso aos repositórios do Artifact Registry. Para as funções do Cloud Storage herdadas do projeto principal, deve verificar se o principal usa atualmente o Container Registry. Alguns principais podem aceder apenas a outros contentores do Cloud Storage que não estão relacionados com o Container Registry.

As funções básicas Proprietário, Editor e Visitante que existiam antes do IAM têm acesso limitado aos contentores de armazenamento. Não concedem intrinsecamente todo o acesso aos recursos do Cloud Storage que os respetivos nomes implicam e fornecem autorizações adicionais para outros Google Cloud serviços. Verifique que utilizadores e contas de serviço requerem acesso ao Artifact Registry e use a tabela de mapeamento de funções para ajudar a conceder as funções certas se o acesso ao Artifact Registry for adequado.

A tabela seguinte mapeia as funções do Artifact Registry com base nas autorizações concedidas pelas funções predefinidas do Cloud Storage para acesso ao Container Registry.

Acesso necessário	Função atual	Função do Artifact Registry	Onde conceder a função
Extrair apenas imagens (só de leitura)	Storage Object Viewer (roles/storage.objectViewer)	Leitor do Artifact Registry (roles/artifactregistry.reader)	Repositório ou Google Cloud projeto do Artifact Registry
Enviar e receber imagens (leitura e escrita) Elimine imagens	Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter)	Administrador do repositório do Artifact Registry (roles/artifactregistry.repoAdmin)	Repositório ou Google Cloud projeto do Artifact Registry
Crie um repositório gcr.io no Artifact Registry na primeira vez que uma imagem é enviada para um nome de anfitrião gcr.io num projeto.	Administrador de armazenamento (roles/storage.admin)	Administrador do repositório de criação no envio do Artifact Registry (roles/artifactregistry.createOnPushRepoAdmin)	Google Cloud projeto
Crie, faça a gestão e elimine repositórios	Administrador de armazenamento (roles/storage.admin)	Administrador do Artifact Registry (roles/artifactregistry.admin)	Google Cloud projeto

Funções de agente do serviço herdadas do projeto

As contas de serviço predefinidas para os Google Cloud serviços têm as suas próprias funções concedidas ao nível do projeto. Por exemplo, o agente do serviço do Cloud Run tem a função de agente do serviço do Cloud Run.

Na maioria dos casos, estas funções de agente de serviço contêm autorizações predefinidas equivalentes para o Container Registry e o Artifact Registry, e não tem de fazer alterações adicionais se estiver a executar o Artifact Registry no mesmo projeto que o seu serviço do Container Registry existente.

Consulte a referência da função de agente de serviço para ver detalhes sobre as autorizações nas funções de agente de serviço.

Funções personalizadas

Use a tabela de mapeamento de funções para ajudar a decidir sobre a função a conceder aos utilizadores ou às contas de serviço com base no nível de acesso de que precisam.

Para obter instruções sobre como conceder funções do Artifact Registry, consulte o artigo Configure funções e autorizações.

Copie contentores do Container Registry

Recomendamos que use a nossa ferramenta de migração automática para copiar as suas imagens do Container Registry para o Artifact Registry.

Se quiser usar outras ferramentas para copiar as suas imagens, consulte o artigo Copie imagens do Container Registry

Configure outras funcionalidades

Esta secção descreve a configuração de outras funcionalidades que pode ter configurado no Container Registry.

Artifact Analysis

A análise de artefactos suporta o Container Registry e o Artifact Registry. Ambos os produtos usam as mesmas APIs Artifact Analysis para metadados de imagens e análise de vulnerabilidades, e os mesmos tópicos do Pub/Sub para notificações da Artifact Analysis.

No entanto, as seguintes ações só ocorrem quando o redirecionamento está ativado:

• Análise automática de repositórios do gcr.io no Artifact Registry.
• Incluir a atividade do repositório nas notificações do Pub/Sub.gcr.io

Pode continuar a usar os comandos gcloud container images para listar notas e ocorrências associadas a caminhos de imagens gcr.io.

Notificações do Pub/Sub

O Artifact Registry publica alterações no mesmo tópico do gcr que o Container Registry. Não é necessária nenhuma configuração adicional se já usar o Pub/Sub com o Container Registry no mesmo projeto que o Artifact Registry. No entanto, o Artifact Registry não publica mensagens para repositórios gcr.io até ativar o redirecionamento.

Se configurar o Artifact Registry num projeto separado, o tópico gcr pode não existir. Para ver instruções de configuração, consulte o artigo Configurar notificações do Pub/Sub.

Ative o redirecionamento do tráfego de gcr.io

Depois de criar os seus repositórios gcr.io e configurar as autorizações e a autenticação para os seus clientes de terceiros, pode ativar o redirecionamento do tráfego gcr.io.

Se encontrar um problema depois de ativar o redirecionamento, pode encaminhar o tráfego de volta para o Container Registry executando o comando gcloud artifacts settings disable-upgrade-redirection e, em seguida, ativar novamente o redirecionamento quando tiver resolvido o problema.

Valide as autorizações para ativar o redirecionamento

Para ativar o redirecionamento, tem de ter estas autorizações ao nível do projeto:

• artifactregistry.projectsettings.update – Autorizações para atualizar as definições do projeto do Artifact Registry. Esta autorização está na função de administrador do Artifact Registry (roles/artifactregistry.admin).
• storage.buckets.update – Autorizações para atualizar contentores de armazenamento em todo o projeto. Esta autorização está na função de administrador do armazenamento (roles/storage.admin).

Se não tiver estas autorizações, peça a um administrador para as conceder ao nível do projeto.

Os seguintes comandos concedem as funções de administrador do Artifact Registry e administrador do armazenamento num projeto.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/artifactregistry.admin'

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/storage.admin'

Substitua os seguintes valores:

• PROJECT_ID é o Google Cloud ID do projeto.
• PRINCIPAL é o endereço de email da conta que está a atualizar. Por exemplo, my-user@example.com

Valide a configuração do projeto

Para validar a configuração do projeto, execute o seguinte comando:

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID --dry-run

Substitua PROJECT_ID pelo seu Google Cloud ID do projeto.

O Artifact Registry verifica se existem repositórios mapeados para nomes de anfitrião do Container Registry.

Embora o Artifact Registry possa criar os repositórios gcr.ioem falta para si quando ativa o redirecionamento, recomendamos que os crie primeiro para poder realizar estas ações antes de ativar o redirecionamento:

• Configure as autorizações ao nível do repositório.
• Copie as imagens do Container Registry que ainda quer usar.
• Realize configurações adicionais.

Ative o redirecionamento

Para ativar o redirecionamento para o tráfego gcr.io:

Para ativar o redirecionamento, execute o seguinte comando:

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID

Substitua PROJECT_ID pelo seu Google Cloud ID do projeto.

O Artifact Registry começa a ativar o redirecionamento.

Para verificar o estado atual do redirecionamento, execute o seguinte comando:

gcloud artifacts settings describe

Quando o redirecionamento está ativado, o resultado é:

legacyRedirectionState: REDIRECTION_FROM_GCR_IO_ENABLED

Todo o tráfego para gcr.io, asia.gcr.io, eu.gcr.io e us.gcr.io é redirecionado, mesmo que não tenha criado repositórios gcr.io para todos os nomes de anfitrião do Container Registry. Se enviar uma imagem para um nome de anfitrião que não tenha um repositório do Artifact Registry correspondente, o Artifact Registry cria o repositório se tiver uma função com a autorização artifactregistry.repositories.createOnPush. As funções predefinidas de escritor de criação no envio (artifactregistry.createOnPushWriter) e administrador do repositório de criação no envio (artifactregistry.createOnPushRepoAdmin) têm esta autorização.

Com o redirecionamento ativado, pode testar a automatização e verificar se consegue enviar e extrair imagens através dos novos repositórios do gcr.io.

Valide o redirecionamento

Verifique se os pedidos de obtenção e envio para os nomes de anfitrião gcr.io estão a funcionar.

1. Envie uma imagem de teste para um dos seus repositórios através do respetivo caminho.gcr.iogcr.io

   1. Etiquete a imagem através do caminho gcr.io. Por exemplo, este comando marca a imagem local-image como us.gcr.io/my-project/test-image:

      docker tag local-image us.gcr.io/my-project/test-image
      

   2. Envie a imagem na qual adicionou a etiqueta. Por exemplo, este comando envia a imagem us.gcr.io/my-project/test-image:

      docker push us.gcr.io/my-project/test-image
      

2. Liste as imagens no repositório para verificar se a imagem foi carregada com êxito. Por exemplo, para listar as imagens em us.gcr.io/my-project, execute o comando:

   gcloud container images list --repository=us.gcr.io/my-project
   

3. Extraia a imagem do repositório através do respetivo caminho do Container Registry. Por exemplo, este comando extrai a imagem us.gcr.io/my-project/test-image.

   docker pull us.gcr.io/my-project/test-image
   

Após este teste inicial, verifique se a automatização existente para criar e implementar imagens funciona como esperado, incluindo:

• Os utilizadores e as contas de serviço que usam o Container Registry continuam a poder enviar, extrair e implementar imagens quando o redirecionamento está ativado.
• A automatização apenas envia imagens para repositórios existentes.
• Se a análise de vulnerabilidades da análise de artefactos estiver ativada, a análise identifica imagens com vulnerabilidades nos repositórios gcr.io.
• Se usar a autorização binária, as suas políticas existentes funcionam corretamente para imagens implementadas a partir de repositórios gcr.io.
• As subscrições do Pub/Sub configuradas incluem notificações de alterações nos seus repositórios do gcr.io.

Limpe imagens do Container Registry

Quando o redirecionamento está ativado, os comandos para eliminar imagens em caminhos gcr.io eliminam imagens no repositório gcr.io do Artifact Registry correspondente. Os comandos de eliminação para eliminar imagens em caminhos gcr.io não eliminam imagens armazenadas em anfitriões do Container Registry.

Para remover em segurança todas as imagens do Container Registry, elimine os contentores do Cloud Storage para cada nome de anfitrião do Container Registry.

Para eliminar cada contentor de armazenamento do Container Registry:

gcloud storage rm gs://BUCKET-NAME --recursive

Removing gs://artifacts.my-project.appspot.com/...

Se outros Google Cloud serviços estiverem a ser executados no mesmo Google Cloud projeto, deixe a API Container Registry ativada. Se tentar desativar a Container Registry API. O Container Registry apresenta um aviso se outros serviços com uma dependência configurada estiverem ativados no projeto. A desativação da API Container Registry desativa automaticamente todos os serviços no mesmo projeto com uma dependência configurada, mesmo que não esteja a usar atualmente o Container Registry com esses serviços.

O que se segue?

• Experimente o início rápido do Docker.
• Saiba mais sobre os gcr.io repositórios.