gcr.io hospedado no Artifact Registry por padrão

Saiba como configurar repositórios gcr.io no Artifact Registry e conheça as diferenças entre as permissões do Artifact Registry e do Container Registry e a configuração do bucket de armazenamento.

As etapas manuais descritas neste documento podem ser concluídas usando a ferramenta de migração automática. Se você quiser usar a ferramenta de migração automática para fazer a transição dos projetos com uso ativo do Container Registry para repositórios padrão do Artifact Registry ou repositórios gcr.io, consulte Automatizar a migração para o Artifact Registry.

Suspensão de uso do Container Registry

Os projetos do Google Cloud que não usaram o Container Registry antes de 15 de maio de 2024 só oferecem suporte à hospedagem e ao gerenciamento de imagens no Artifact Registry. Essa mudança afeta:

Projetos recém-criados.
Projetos existentes em que você não enviou uma imagem para o Container Registry.

As organizações que não usaram o Container Registry antes de 8 de janeiro de 2024 terão novos repositórios gcr.io hospedados no Artifact Registry por padrão.

Quando você ativa a API Artifact Registry nesses projetos, o Artifact Registry processa automaticamente a criação de repositórios gcr.io no Artifact Registry e redireciona as solicitações ao domínio gcr.io para o repositório apropriado do Artifact Registry. Ao contrário do suporte ao domínio gcr.io existente em projetos com uso ativo do Container Registry, o redirecionamento para o Artifact Registry será automático.

O Container Registry permanecerá disponível em projetos em que uma das seguintes ações tenha ocorrido antes de 15 de maio de 2024:

Você ativou a API Container Registry no projeto.
Você enviou uma imagem para um host de registro no projeto.

Para se preparar para a futura mudança, recomendamos que você faça o seguinte:

Siga as instruções neste documento para configurar projetos em que você não está usando o Container Registry. Assim, eles estarão prontos para o processamento automático de solicitações gcr.io quando as alterações entrarem em vigor.
Teste o suporte ao domínio gcr.io para verificar se a automação atual continuará funcionando.

Os repositórios gcr.io hospedados no Artifact Registry são criados nas mesmas multirregiões compatíveis com o Container Registry. Se você quiser armazenar suas imagens em outras regiões, será preciso fazer a transição para repositórios padrão no domínio pkg.dev.

Funções exigidas

Para ter 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
Para visualizar e gerenciar a configuração do Container Registry aplicada aos buckets de armazenamento do Cloud Storage: Administrador do Storage (roles/storage.admin) no projeto
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) no projeto, na pasta ou na organização
Para listar os serviços ativados em uma organização: Leitor de recursos do Cloud (roles/cloudasset.viewer) na organização

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.

Antes de começar

É possível listar projetos em que pelo menos uma imagem está armazenada no Container Registry. Depois, é possível se concentrar na configuração de outros projetos para hospedar solicitações gcr.io no Artifact Registry usando as instruções deste documento.

Execute o seguinte comando para encontrar qualquer uso do Container Registry na sua organização do Google Cloud.

  gcloud containers list-gcr-usage \
      --organization=ORGANIZATION

Substitua ORGANIZATION pelo ID da organização do Google Cloud.

Também é possível listar o uso do Container Registry no projeto ou na pasta. Para mais informações sobre como descobrir o uso do Container Registry, consulte Verificar o uso do Container Registry.

Ativar a API

Ative a API Artifact Registry para que as solicitações para o domínio gcr.io sejam processadas automaticamente pelo Artifact Registry quando a hospedagem automática de gcr.io entrar em vigor.

Execute este comando:

gcloud services enable \
    artifactregistry.googleapis.com

Se você normalmente colocar a API Container Registry em um perímetro de serviço do VPC Service Controls, inclua a API Artifact Registry também no perímetro. Consulte Como proteger repositórios em um perímetro de serviço para conferir as instruções.

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.

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

Acessar buckets
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
Clique na guia Permissões.
Na guia "Permissões", clique na subguia Visualizar por função.
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.

Configuração do bucket de armazenamento

Quando você cria um repositório no Artifact Registry, o Artifact Registry não cria buckets correspondentes do Cloud Storage no projeto. Se você tiver uma automação do Container Registry que interage diretamente com os buckets de armazenamento, atualize ela para fazer alterações correspondentes no repositório do Artifact Registry.

Por exemplo, se você conceder de maneira programática permissões do Cloud Storage em buckets de armazenamento do Container Registry, atualize essa automação para conceder permissões do Artifact Registry nos repositórios do Artifact Registry que hospedam imagens para o domínio gcr.io.

No Artifact Registry, defina o método de criptografia para dados armazenados em um repositório, em vez de em um bucket de armazenamento. A hospedagem automática de gcr.io no Artifact Registry cria repositórios de gcr.io que são criptografados com chaves gerenciadas pelo Google. Se você quiser usar chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês), crie os repositórios gcr.io e especifique-os como o método de criptografia ao criá-los.

Para criar manualmente um repositório gcr.io:

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.
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
```

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

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

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

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

A seguir

Configure o suporte ao domínio gcr.io em um projeto de teste para verificar se a automação e a integração com serviços como o Cloud Build, Google Kubernetes Engine ou Cloud Functions funcionam conforme o esperado.