Configurar repositórios com suporte ao domínio gcr.io

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

Recomendamos o uso da nossa ferramenta de migração automática para fazer a transição para repositórios gcr.io no Artifact Registry.

Se você quiser criar repositórios gcr.io no Artifact Registry usando chaves de criptografia gerenciadas pelo cliente (CMEK), conclua as etapas em Antes de começar e siga as instruções em Criação manual de repositório.

Antes de começar

1. Instale a Google Cloud CLI, se ela ainda não estiver instalada. Para uma instalação atual, 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 permissões necessárias.

   Execute este comando:

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

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

Funções exigidas

Para receber as permissões necessárias para configurar repositórios "gcr.io", peça ao administrador para conceder a você os seguintes papéis do IAM no projeto do Google Cloud:

• Para criar repositórios do Artifact Registry e conceder acesso a repositórios individuais: Administrador do Artifact Registry (roles/artifactregistry.admin)
• Para visualizar e gerenciar a configuração atual do Container Registry aplicada aos buckets de armazenamento do Cloud Storage: Administrador do Storage (roles/storage.admin)
• Para criar um repositório gcr.io na primeira vez que você enviar uma imagem para um nome de host gcr.io: Gravador de criação em push do Artifact Registry (roles/artifactregistry.createOnPushWriter)
• Para conceder acesso ao repositório no nível do projeto: Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) ou um papel que inclua permissões equivalentes, como Administrador de pastas (roles/resourcemanager.folderAdmin) ou Administrador da organização (roles/resourcemanager.organizationAdmin)

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Observação :o papel de administrador do Artifact Registry contém a maioria das permissões em outros papéis predefinidos do Artifact Registry, mas não inclui a permissão artifactregistry.repositories.createOnPush para criar repositórios gcr.io para o primeiro envio a um repositório gcr.io.

Limitações

As seguintes limitações se aplicam a repositórios com suporte ao domínio gcr.io:

• Não é possível mapear um host do Container Registry para um repositório do Artifact Registry em um projeto diferente.
• Cada nome de host do Container Registry é mapeado para apenas um repositório gcr.io correspondente do Artifact Registry na mesma multirregião.
• Os nomes dos repositórios gcr.io são predefinidos e não podem ser modificados.

Se você precisar de mais controle sobre o local dos repositórios, faça a transição para repositórios padrão no domínio pkg.dev do Artifact Registry. Como os repositórios padrão não têm suporte para o domínio gcr.io, essa abordagem de transição exige mais mudanças na automação e nos fluxos de trabalho atuais. Consulte Escolher uma opção de transição para saber mais sobre as diferenças dos recursos.

Criar repositórios

Crie repositórios gcr.io para configurar o acesso aos usuários e copie as imagens atuais do Container Registry para o Artifact Registry antes de ativar o redirecionamento.

Criação rápida de repositórios

Estas etapas criam repositórios de gcr.io criptografados com chaves de criptografia gerenciadas pelo Google. Se você quiser usar chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês), crie repositórios manualmente.

Para criar repositórios gcr.io:

1. Abra a página Repositórios no console do Google Cloud.

   Abrir a página Repositórios

   Na página, um banner exibe a mensagem You have gcr.io repositories in Container Registry.

   Abrir a página Configurações

2. No banner, clique em Criar gcr.io repositórios.

   O painel Criar gcr.io repositórios será aberto. A seção Como copiar imagens lista os nomes totalmente qualificados de cada repositório que será criado. Você precisará desses nomes de repositório se quiser copiar imagens do Container Registry antes de ativar o redirecionamento.

3. Clique em Criar.

O Artifact Registry cria repositórios gcr.io para todos os nomes de host do Container Registry:

Nome do host 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

Para ver o URL do Artifact Registry referente ao repositório, mantenha o cursor sobre o ícone de aviso () ao lado do nome do repositório.

Antes de redirecionar o tráfego para os novos repositórios, você precisa garantir que a automação existente possa acessar o repositório. A próxima etapa é configurar as permissões para conceder acesso a repositórios.

Criação manual de repositórios

Crie repositórios gcr.io manualmente se quiser usar chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês) para criptografar o conteúdo do repositório ou se houver uma restrição de local na organização do Google Cloud que bloqueie a criação de novos recursos em locais específicos.

Para criar manualmente um repositório gcr.io:

1. Se você estiver usando a CMEK, crie a chave que será usada com esse repositório e conceda permissões para usar a chave. Consulte Como ativar chaves de criptografia gerenciadas pelo cliente.

2. Adicione o repositório.

   Console

   1. Abra a página Repositórios no console do Google Cloud.

      Abrir a página Repositórios

   2. Clique em Criar repositório.

   3. Especifique o nome do repositório.

      Nome do host 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 local, especifique a multirregião para o repositório:

      Nome do host do Container Registry	Local do repositório do Artifact Registry
      gcr.io	us
      asia.gcr.io	asia
      eu.gcr.io	europe
      us.gcr.io	us

   6. Adicione uma descrição para o repositório. Não inclua dados sensíveis, porque as descrições do repositório não são criptografadas.

   7. Na seção Criptografia, escolha o mecanismo de criptografia do repositório.

      • Chave gerenciada pelo Google: criptografe o conteúdo do repositório com uma chave de criptografia gerenciada pelo Google.
      • Chave gerenciada pelo cliente: criptografe o conteúdo do repositório com uma chave controlada por você por meio do Cloud Key Management Service. Para instruções de configuração de chaves, consulte Como configurar CMEK para repositórios.

   8. Clique em Criar.

   gcloud

   Execute o comando abaixo 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 host 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 multirregião do repositório:

     Nome do host do Container Registry	Local do repositório do Artifact Registry
     gcr.io	us
     asia.gcr.io	asia
     eu.gcr.io	europe
     us.gcr.io	us

   • DESCRIPTION é uma descrição do repositório. Não inclua dados sensíveis, porque as descrições do repositório não são criptografadas.

   • KMS-KEY é o caminho completo para a chave de criptografia do Cloud KMS, se você estiver usando uma chave de criptografia gerenciada pelo cliente para criptografar 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 em que a chave está armazenada.
     • KMS-LOCATION é o local da chave.
     • KEY-RING é o nome do keyring.
     • KEY é o nome da chave.

   Para confirmar que o repositório foi criado, liste seus repositórios com o seguinte comando:

   gcloud artifacts repositories list
   

Antes de redirecionar o tráfego para os novos repositórios, você precisa garantir que a automação existente possa acessar o repositório. A próxima etapa é configurar as permissões para conceder acesso a repositórios.

Conceder permissões aos repositórios

O Container Registry usa os papéis do Cloud Storage para controlar o acesso. O Artifact Registry tem os próprios papéis do IAM, e esses papéis separam os papéis de leitura, gravação e administração de repositório com mais clareza do que o Container Registry.

Use a ferramenta de mapeamento de papéis para fazer a correspondência entre as permissões atuais concedidas em buckets de armazenamento e papéis sugeridos do Artifact Registry.

Como alternativa, é possível ver uma lista de principais com acesso aos buckets de armazenamento usando o console do Google Cloud.

1. No console do Google Cloud, acesse a página Buckets do Cloud Storage.
   

   Acessar buckets

2. Clique no bucket de armazenamento do host de registro que você quer visualizar. Nos nomes dos buckets, PROJECT-ID é o ID do projeto do Google Cloud.

   • 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 na guia Permissões.

4. Na guia "Permissões", clique na subguia Visualizar por função.

5. Expanda um papel para ver os principais que têm ele.

Ela inclui papéis do IAM concedidos diretamente no bucket e papéis herdados do projeto pai. Com base no papel, é possível escolher o mais apropriado do Artifact Registry para conceder.

Cloud Storage e papéis básicos

Conceda aos usuários e contas de serviço que atualmente acessam o Container Registry com acesso aos repositórios do Artifact Registry. Para os papéis do Cloud Storage herdados do projeto pai, verifique se o principal usa o Container Registry. Alguns principais podem acessar apenas outros buckets do Cloud Storage que não estão relacionados ao Container Registry.

Os papéis básicos de Proprietário, Editor e Leitor que existiam antes do IAM têm acesso limitado aos buckets de armazenamento. Eles não concedem, intrinsecamente, todo o acesso aos recursos do Cloud Storage que os nomes sugerem e fornecem permissões adicionais para outros serviços do Google Cloud. Verifique quais usuários e contas de serviço exigem acesso ao Artifact Registry e use a tabela de mapeamento de papéis para ajudar a conceder os papéis certos, se o acesso ao Artifact Registry for apropriado.

A tabela a seguir mapeia os papéis do Artifact Registry com base nas permissões concedidas por papéis predefinidos do Cloud Storage para acesso ao Container Registry.

Acesso necessário	Papel atual	Papel do Artifact Registry	Onde conceder o papel
Extrair somente imagens (somente leitura)	Leitor de objetos do Storage (roles/storage.objectViewer)	Leitor do Artifact Registry (roles/artifactregistry.reader)	Repositório do Artifact Registry ou projeto do Google Cloud
Enviar e extrair imagens (leitura e gravação) Excluir imagens	Gravador de bucket legado do Storage (roles/storage.legacyBucketWriter)	Administrador do repositório do Artifact Registry (roles/artifactregistry.repoAdmin)	Repositório do Artifact Registry ou projeto do Google Cloud
Crie um repositório gcr.io no Artifact Registry na primeira vez que uma imagem for enviada para um nome de host gcr.io em um projeto.	Administrador do Storage (roles/storage.admin)	Administrador de repositório de criação em push do Artifact Registry (roles/artifactregistry.createOnPushRepoAdmin)	Projeto do Google Cloud
Criar, gerenciar e excluir repositórios	Administrador do Storage (roles/storage.admin)	Administrador do Artifact Registry (roles/artifactregistry.Admin)	Projeto do Google Cloud

Papéis do agente de serviço herdados do projeto

As contas de serviço padrão para serviços do Google Cloud têm os próprios papéis concedidos no nível do projeto. Por exemplo, o agente de serviço do Cloud Run tem o papel de Agente de serviço do Cloud Run.

Na maioria dos casos, esses papéis de agente de serviço contêm permissões padrão equivalentes para o Container Registry e o Artifact Registry, e você não precisará fazer outras alterações se estiver executando o Artifact Registry no mesmo projeto que o serviço atual do Container Registry.

Consulte a referência do papel de agente de serviço para ver detalhes sobre as permissões nesses papéis.

papéis personalizados

Use a tabela de mapeamento de papéis para decidir qual papel conceder a usuários ou contas de serviço com base no nível de acesso necessário.

Para instruções sobre como conceder papéis do Artifact Registry, consulte Configurar papéis e permissões.

Copiar contêineres do Container Registry

Recomendamos o uso da nossa ferramenta de migração automática para copiar as imagens do Container Registry para o Artifact Registry.

Se você quiser usar outras ferramentas para copiar as imagens, consulte Copiar imagens do Container Registry.

Configurar outros recursos

Esta seção descreve a configuração de outros recursos que você pode ter configurado no Container Registry.

Artifact Analysis

O Artifact Analysis é compatível com Container Registry e Artifact Registry. Os dois produtos usam as mesmas APIs Artifact Analysis para metadados de imagem e verificação de vulnerabilidades e os mesmos tópicos do Pub/Sub para notificações do Artifact Analysis.

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

• Verificação automática de gcr.io repositórios no Artifact Registry.
• Incluindo atividade de repositório gcr.io nas notificações do Pub/Sub.

É possível continuar usando os comandos gcloud container images para listar observações e ocorrências associadas aos caminhos de imagem gcr.io.

Container Registry

Artifact Registry

Verificações de vulnerabilidades de pacotes de idiomas e do SO com a verificação sob demanda em imagens com um SO com suporte. A verificação automática só retorna informações sobre vulnerabilidades do SO. Saiba mais sobre os tipos de verificação. Verificação sob demanda O comando gcloud artifacts docker images scan da CLI do Google Cloud verifica vulnerabilidades em imagens ou imagens locais no Container Registry. O comando gcloudartifact docker images list-vulnerabilities retorna os resultados da verificação de vulnerabilidades da CLI do Google Cloud. As verificações retornam informações sobre vulnerabilidades do sistema operacional e do pacote de idiomas para imagens no Container Registry com sistemas operacionais compatíveis. Verificação automática O comando gcloud container images do Google Cloud CLI inclui sinalizações para visualizar os resultados da verificação, como vulnerabilidades e outros metadados. As verificações só retornam informações de vulnerabilidade do SO para imagens no Container Registry com sistemas operacionais compatíveis.

Verificações de vulnerabilidades de pacotes de idioma e do SO com verificações sob demanda e automáticas. Saiba mais sobre os tipos de verificação. Verificação sob demanda O comando gcloud artifact docker images scan da Google Cloud CLI verifica vulnerabilidades em imagens ou imagens locais no Artifact Registry. O comando gcloudartifact docker images list-vulnerabilities retorna os resultados da verificação de vulnerabilidades da CLI do Google Cloud. As verificações retornam informações de vulnerabilidade do SO e do pacote de idiomas para imagens no Artifact Registry com sistemas operacionais compatíveis. Verificação automática O comando gcloud artifacts docker images na Google Cloud CLI inclui sinalizações para visualizar os resultados de verificações, como vulnerabilidades e outros metadados. As verificações retornam informações de vulnerabilidade do SO para imagens no Artifact Registry com sistemas operacionais compatíveis e informações de vulnerabilidades de pacotes de idiomas para sistemas operacionais com ou sem suporte.

Notificações do Pub/Sub

O Artifact Registry publica alterações no mesmo tópico gcr do Container Registry. Nenhuma outra configuração é necessária se você já usa 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é que você ative o redirecionamento.

Se você configurar o Artifact Registry em um projeto separado, o tópico gcr poderá não existir. Para instruções de configuração, consulte Como configurar notificações do Pub/Sub.

Ativar o redirecionamento do tráfego gcr.io

Depois de criar seus repositórios gcr.io e configurar permissões e autenticação para clientes de terceiros, ative o redirecionamento do tráfego gcr.io.

Se você encontrar um problema depois de ativar o redirecionamento, encaminhe o tráfego de volta para o Container Registry e ative o redirecionamento novamente depois de solucionar o problema.

Verificar as permissões para ativar o redirecionamento

Para ativar o redirecionamento, você precisa ter estas permissões no nível do projeto:

• artifactregistry.projectsettings.update: permissões para atualizar as configurações do projeto do Artifact Registry. Essa permissão está no papel de administrador do Artifact Registry (roles/artifactregistry.admin).
• storage.buckets.update: permissões para atualizar buckets de armazenamento em todo o projeto. Essa permissão está no papel de administrador do Storage (roles/storage.admin).

Se você não tiver essas permissões, peça a um administrador para concedê-las no nível do projeto.

Os comandos a seguir concedem os papéis de administrador do Artifact Registry e administrador de armazenamento em um 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 ID do projeto do Google Cloud.
• PRINCIPAL é o endereço de e-mail da conta que você está atualizando. Por exemplo: user:[e-mail]

Validar 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 ID do projeto do Google Cloud.

O Artifact Registry verifica repositórios que mapeiam nomes de host do Container Registry.

Embora o Artifact Registry possa criar os repositórios gcr.io ausentes para você quando você ativar o redirecionamento, recomendamos criá-los primeiro para que possa executar estas ações antes de ativar o redirecionamento:

• Configurar permissões no nível do repositório
• Copie imagens do Container Registry que você ainda quer usar
• Execute qualquer configuração adicional.

Ativar o redirecionamento

Se quiser ativar o redirecionamento para o tráfego gcr.io:

Console

1. Abra a página Configurações no console do Google Cloud.

   Abrir a página Configurações

2. Clique em Rotear para o Artifact Registry.

gcloud

Para ativar o redirecionamento, execute o comando:

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

Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

O Artifact Registry começa a ativar o redirecionamento.

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

gcloud artifacts settings describe

Quando o redirecionamento é 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 você não tenha criado repositórios gcr.io para todos os nomes de host do Container Registry. Se você enviar uma imagem para um nome de host que não tenha um repositório correspondente do Artifact Registry, o Artifact Registry criará o repositório se você tiver um papel com a permissão artifactregistry.repositories.createOnPush. Os papéis predefinidos Gravador em push (artifactregistry.createOnPushWriter) e Administrador de repositório de criação em push (artifactregistry.createOnPushRepoAdmin) têm essa permissão.

Com o redirecionamento ativado, é possível testar a automação e verificar se é possível enviar e extrair imagens usando os novos repositórios gcr.io.

Verificar o redirecionamento

Verifique se as solicitações de envio e extração para os nomes de host gcr.io estão funcionando.

1. Envie uma imagem de teste para um dos repositórios gcr.io usando o caminho gcr.io.

   1. Marque a imagem usando o 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 por push a imagem que você marcou. 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 o upload foi concluído. Por exemplo, para listar 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 usando o 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 esse teste inicial, verifique se a automação existente para criar e implantar imagens funciona conforme o esperado, incluindo:

• Os usuários e as contas de serviço que usam o Container Registry ainda podem enviar, extrair e implantar imagens quando o redirecionamento estiver ativado.
• A automação envia imagens apenas para os repositórios que já existem.
• Se a verificação de vulnerabilidades do Artifact Analysis estiver ativada, ela identifica imagens com vulnerabilidades em repositórios gcr.io.
• Se você usar a autorização binária, as políticas existentes funcionarão corretamente para imagens implantadas de repositórios gcr.io.
• As assinaturas do Pub/Sub configuradas incluem notificações para alterações nos repositórios gcr.io.

Limpar imagens do Container Registry

Quando o redirecionamento está ativado, os comandos para excluir imagens nos caminhos gcr.io excluem imagens no repositório gcr.io correspondente do Artifact Registry. Os comandos de exclusão para excluir imagens em caminhos gcr.io não excluem imagens armazenadas nos hosts do Container Registry.

Para remover com segurança todas as imagens do Container Registry, exclua os buckets do Cloud Storage para cada nome de host do Container Registry.

Aviso: a exclusão de um bucket também remove todas as imagens dele. Não é possível recuperar imagens de um bucket excluído.

Para excluir cada bucket de armazenamento do Container Registry:

Console

1. Acesse a página do Cloud Storage no console do Google Cloud.

2. Selecione o bucket de armazenamento a ser excluído. Nos nomes dos buckets, PROJECT-ID é o ID do projeto do Google Cloud.

   • 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 em Excluir. Uma caixa de diálogo de confirmação será exibida.

4. Para confirmar a exclusão, insira o nome do bucket e clique em Excluir.

gsutil

Se você quiser excluir em massa 100 mil ou mais imagens de um bucket, evite usar o gsutil, já que o processo de exclusão leva muito tempo para ser concluído. Use o console do Google Cloud para realizar a operação.

Para excluir um bucket, use o comando gsutil rm com a sinalização -r.

gsutil rm -r gs://BUCKET-NAME

Substitua BUCKET-NAME pelo nome do bucket de armazenamento do Container Registry. Nos nomes dos buckets, PROJECT-ID é o ID do projeto do Google Cloud.

• 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

A resposta terá esta aparência:

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

Se outros serviços do Google Cloud estiverem em execução no mesmo projeto do Google Cloud, deixe a API Container Registry ativada. Se você tentar desativar a API Container Registry. O Container Registry exibirá um aviso se outros serviços com uma dependência configurada estiverem ativados no projeto. Desativar a API Container Registry desativa automaticamente todos os serviços no mesmo projeto com uma dependência configurada, mesmo que você não esteja usando o Container Registry com esses serviços.

A seguir

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