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

Neste documento, explicamos como configurar manualmente 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órios.

Antes de começar

1. Instale a Google Cloud CLI, caso ainda não tenha feito isso. Para uma instalação atual, execute o comando a seguir 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 os preços 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:

• Para criar repositórios do Artifact Registry e conceder acesso a repositórios individuais: Administrador do Artifact Registry (roles/artifactregistry.admin) no projeto Google Cloud
• 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) no projeto Google Cloud
• Para criar um repositório gcr.io na primeira vez que você envia uma imagem para um nome de host gcr.io: Gravador Create-on-push do Artifact Registry (roles/artifactregistry.createOnPushWriter) no projeto Google Cloud
• Para conceder acesso ao repositório no nível do projeto: Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) no projeto Google Cloud
• Para listar os serviços ativados em uma organização: Visualizador de recursos do Cloud (roles/cloudasset.viewer) na organização

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

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

Limitações

As seguintes limitações se aplicam aos repositórios gcr.io do Artifact Registry:

• Ao fazer a transição do Container Registry, 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 do gcr.io são predefinidos e não podem ser modificados.

Se você precisar de mais controle sobre a localização dos repositórios, faça a transição para repositórios pkg.dev no Artifact Registry. Como os repositórios do pkg.dev 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 entre os recursos.

Criar repositórios

Crie repositórios gcr.io para configurar o acesso dos usuários e copiar imagens do Container Registry para o Artifact Registry antes de ativar o redirecionamento.

Criação manual de repositório

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

Para criar um repositório gcr.io manualmente:

1. Se você estiver usando CMEK, crie a chave que será usada com este 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 Docker como o formato do repositório.

   5. Em Tipo de local, especifique a multirregião do repositório:

      Nome do host do Container Registry	Local 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 sensíveis, já que as descrições do repositório não são criptografadas.

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

      • Google-managed encryption key: criptografa o conteúdo do repositório com um Google-owned and Google-managed encryption key.
      • 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 a seguir para criar um 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	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 sensíveis, já que 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 se 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 permissões para conceder acesso aos repositórios.

Conceder permissões a repositórios

O Container Registry usa papéis do Cloud Storage para controlar o acesso. O Artifact Registry tem seus próprios papéis do IAM, que separam as funções de leitura, gravação e administração de repositório de maneira mais clara do que o Container Registry.

Para mapear rapidamente as permissões concedidas em buckets de armazenamento para papéis sugeridos do Artifact Registry, use a ferramenta de mapeamento de papéis.

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

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

   Acessar buckets

2. Clique no bucket de armazenamento do host do registro que você quer visualizar. Nos nomes dos buckets, PROJECT-ID é oGoogle 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 na guia Permissões.

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

5. Expanda uma função para ver os principais que a têm.

A lista inclui papéis do IAM concedidos diretamente no bucket e papéis herdados do projeto pai. Com base na função, você pode escolher o papel do Artifact Registry mais adequado para conceder.

Cloud Storage e papéis básicos

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

Os papéis básicos Proprietário, Editor e Leitor que existiam antes do IAM têm acesso limitado a 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 precisam de acesso ao Artifact Registry e use a tabela de mapeamento de papéis para conceder os papéis certos, se o acesso ao Artifact Registry for adequado.

A tabela a seguir mapeia os papéis do Artifact Registry com base nas permissões concedidas pelos 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 apenas 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 por push para um nome de host gcr.io em um projeto.	Administrador do Storage (roles/storage.admin)	Administrador de repositório de Create-on-push no Artifact Registry (roles/artifactregistry.createOnPushRepoAdmin)	Google Cloud projeto
Criar, gerenciar e excluir repositórios	Administrador do Storage (roles/storage.admin)	Administrador do Artifact Registry (roles/artifactregistry.admin)	Google Cloud projeto

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 papéis próprios 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. Não é necessário fazer outras mudanças se você estiver executando o Artifact Registry no mesmo projeto que o serviço do Container Registry.

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

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 usar nossa ferramenta de migração automática para copiar suas 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

Nesta seção, descrevemos a configuração de outros recursos que você pode ter configurado no Container Registry.

Artifact Analysis

A Análise de artefatos é compatível com o Container Registry e o Artifact Registry. Ambos os produtos usam as mesmas APIs do Artifact Analysis para metadados de imagem e verificação de vulnerabilidades, além dos 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 repositórios gcr.io no Artifact Registry.
• Incluir a atividade do repositório gcr.io nas notificações do Pub/Sub.

Você pode continuar usando os comandos gcloud container images para listar notas e ocorrências associadas a caminhos de imagem gcr.io.

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 seus clientes de terceiros, você pode ativar o redirecionamento do tráfego gcr.io.

Se você encontrar um problema depois de ativar o redirecionamento, poderá encaminhar o tráfego de volta para o Container Registry executando o comando gcloud artifacts settings disable-upgrade-redirection e ativando o redirecionamento novamente quando o problema for resolvido.

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 do Storage 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. Google Cloud
• PRINCIPAL é o endereço de e-mail da conta que você está atualizando. Por exemplo, my-user@example.com

Validar a configuração do projeto

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

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

Substitua PROJECT_ID pelo Google Cloud ID do projeto.

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

Embora o Artifact Registry possa criar os repositórios gcr.io ausentes para você quando o redirecionamento é ativado, recomendamos que você os crie primeiro para poder realizar estas ações antes de ativar o redirecionamento:

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

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

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 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 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 do host que não tem um repositório correspondente do Artifact Registry, o Artifact Registry vai criar o repositório se você tiver uma função com a permissão artifactregistry.repositories.createOnPush. Os papéis predefinidos "Gravador de criação por push" (artifactregistry.createOnPushWriter) e "Administrador de repositório de criação por push" (artifactregistry.createOnPushRepoAdmin) têm essa permissão.

Com o redirecionamento ativado, você pode testar sua automação e verificar se é possível enviar e extrair imagens usando seus 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 dela.

   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 a imagem marcada. 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 com sucesso. 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 atual para criar e implantar imagens funciona como 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 está ativado.
• Sua automação envia imagens apenas para repositórios existentes.
• Se a verificação de vulnerabilidades do Artifact Analysis estiver ativada, ela identificará imagens com vulnerabilidades nos repositórios gcr.io.
• Se você usa a autorização binária, as políticas atuais funcionam corretamente para imagens implantadas de repositórios gcr.io.
• As assinaturas configuradas do Pub/Sub incluem notificações de mudanças nos seus repositórios do gcr.io.

Limpar imagens do Container Registry

Quando o redirecionamento está ativado, os comandos para excluir imagens em 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 em hosts do Container Registry.

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

Para excluir cada bucket 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 sendo executados no mesmo projeto Google Cloud, deixe a API Container Registry ativada. Se você tentar desativar a API Container Registry. O Container Registry mostra 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 gcr.io.