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

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

Recomendamos usar 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, caso ainda não tenha feito isso. instalado. Para uma instalação já existente, execute o seguinte comando para atualizar para as versões mais recentes:

    gcloud components update

  2. Ative as APIs Artifact Registry e Resource Manager. CLI gcloud usa a API Resource Manager para verificar um dos as 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 até antes de iniciar a transição.

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 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 Create-on-push do Artifact Registry (roles/artifactregistry.createOnPushWriter)
  • Para conceder acesso ao repositório no nível do projeto: Administrador de 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 com papéis personalizados ou outros papéis predefinidos.

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 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 seus repositórios, transição para repositórios padrão no Artifact Registry pkg.dev. Como os repositórios padrão não têm suporte para a gcr.io domínio, essa abordagem de transição exige mais alterações ao seu automação e fluxos de trabalho. Consulte Escolher uma opção de transição para saber sobre as diferenças de atributos.

Criar repositórios

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

Criação rápida de repositórios

Estas etapas criam repositórios gcr.io que são criptografados com Chaves de propriedade e gerenciadas pelo Google. Se você quiser usar a criptografia gerenciada pelo cliente chaves (CMEK), será preciso criar 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 Create gcr.io repositories.

    O painel Criar gcr.io repositórios é aberto. A página Como copiar imagens lista os nomes totalmente qualificados de cada repositório que será criados. 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 gcr.io repositórios para todos os Container Registry nomes de host:

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 conferir o URL do Artifact Registry para o repositório, mantenha o ponteiro 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 permissões para conceder acesso a repositórios.

Criação manual de repositório

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

Para criar manualmente um repositório gcr.io:

  1. Se você estiver usando CMEK, crie a chave que será usada com este repositório e conceda permissões para usá-la. 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 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

    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.

      • Chave gerenciada pelo Google: criptografe o conteúdo do repositório com uma Chave de propriedade e 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 incluem dados sensíveis, já que as descrições dos repositórios não são criptografadas.

    • KMS-KEY é o caminho completo para a criptografia do Cloud KMS. chave, 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 pelo 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 a repositórios.

Conceder permissões a repositórios

O Container Registry usa os papéis do Cloud Storage para controlar o acesso. O Artifact Registry tem o próprio IAM papéis e esses papéis separam as funções de leitura, gravação e administração de repositório Container Registry.

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

Como alternativa, é possível conferir uma lista dos principais com acesso ao 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 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 na guia Permissões.

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

  5. Expanda um papel para consultar os principais que têm esse papel.

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

Cloud Storage e papéis básicos

Conceder aos usuários e contas de serviço que acessam o Container Registry com acesso aos repositórios do Artifact Registry. Para o 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 o IAM tem acesso limitado a buckets de armazenamento. Elas não dão intrinsecamente todo o acesso ao Cloud Storage recursos que seus nomes indicam 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 usar a tabela de mapeamento de papéis para ajudar você concede os papéis corretos, 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 no 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 de repositórios do Artifact Registry
(roles/artifactregistry.repoAdmin)		 Repositório do Artifact Registry ou projeto do Google Cloud
Criar um repositório gcr.io no Artifact Registry na primeira vez que uma imagem for enviado para um nome de host gcr.io em um projeto. Administrador do Storage
(roles/storage.admin)		 Administrador de repositório de Create-on-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 de agente de serviço herdados do projeto

As contas padrão de serviços do Google Cloud têm as próprias de papéis concedidos no nível do projeto. Por exemplo, o agente de serviço O 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 as permissões do Container Registry e do Artifact Registry. não será necessário fazer alterações adicionais se você estiver executando Artifact Registry no mesmo projeto que o Container Registry atual serviço.

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

Papéis personalizados

Use a tabela de mapeamento de funções para ajudar você a decidir sobre o conceder a usuários ou contas de serviço com base no nível de acesso de acordo com as necessidades.

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 as imagens do Container Registry para o Artifact Registry.

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

Configurar outros recursos

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

Artifact Analysis

O Artifact Analysis oferece suporte a Container Registry e Artifact Registry. Os dois produtos usam o mesmo APIs Artifact Analysis para metadados e vulnerabilidade de imagens 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 repositórios gcr.io no Artifact Registry.
  • Inclusão da atividade do repositório gcr.io nas notificações do Pub/Sub.

É possível continuar usando gcloud container images para listar notas e ocorrências associadas a caminhos de imagem gcr.io.

Container Registry Artifact Registry
Verifica vulnerabilidades de pacotes de idiomas e do SO com a verificação sob demanda em imagens com SO compatível. A verificação automática só retorna o SO informações sobre vulnerabilidade. Saiba mais sobre os tipos de verificação.
Verificação sob demanda
Verificação automática
 Verifica vulnerabilidades de pacotes de SO e de idiomas com recursos verificação automática. Saiba mais sobre os tipos de verificação.
Verificação sob demanda
Verificação automática
  • O comando da CLI do Google Cloud gcloud imagens do Docker de artefatos inclui flags para exibir os resultados da verificação. incluindo 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 pacote de idiomas informações de vulnerabilidade de sistemas operacionais sistemas.

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 gcr.io repositórios 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 os repositórios do gcr.io e configurou permissões e autenticação para seus 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 reative o redirecionamento quando o problema.

Verificar as permissões para ativar o redirecionamento

Para ativar o redirecionamento, é preciso ter as seguintes permissões no nível do projeto:

  • artifactregistry.projectsettings.update: permissões para atualizar Configurações do projeto do Artifact Registry. Essa permissão está nos Papel de administrador do Artifact Registry (roles/artifactregistry.admin).
  • storage.buckets.update - Permissões para atualizar buckets de armazenamento em todo o em todo o projeto. Essa permissão está no papel de Administrador de armazenamento (roles/storage.admin).

Se você não tem essas permissões, peça a um administrador para conceder e aplicá-las no nível do projeto.

Os comandos a seguir concedem ao papel 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 é Google Cloud ID do projeto.
  • PRINCIPAL é o endereço de e-mail da conta que você está atualizando. Por exemplo, user:my-user@example.com.

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 mapeados para o Container Registry nomes de host.

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

Ativar o redirecionamento

Se quiser ativar o redirecionamento para o tráfego de gcr.io, faça o seguinte:

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 estiver ativado, o resultado será:

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 se você não tiver criado repositórios gcr.io para todos Nomes de host do Container Registry. Se você enviar uma imagem para um nome de host que não têm um repositório correspondente do Artifact Registry, o Artifact Registry cria o repositório se você tiver um papel com o artifactregistry.repositories.createOnPush permissão. Os papéis predefinidos Gravador Create-on-push (artifactregistry.createOnPushWriter) e repositório Create-on-push O administrador (artifactregistry.createOnPushRepoAdmin) tem esta 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 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 gcr.io caminho.

    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 push. Por exemplo, este comando envia a imagem us.gcr.io/my-project/test-image:

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

  2. Listar imagens no repositório para verificar se elas foram enviadas 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 existente para criar e implantar imagens funciona conforme esperado, incluindo:

  • Os usuários e as contas de serviço que usam o Container Registry ainda podem realizar push, pull, e implantar imagens quando o redirecionamento estiver ativado.
  • A automação só envia imagens para os repositórios atuais.
  • Se a verificação de vulnerabilidades do Artifact Analysis estiver ativada, identifica imagens com vulnerabilidades nos repositórios gcr.io.
  • Se você usa a autorização binária, as políticas atuais funcionam corretamente com imagens implantados de repositórios gcr.io.
  • As assinaturas configuradas do Pub/Sub 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 em caminhos gcr.io excluir 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 as imagens armazenadas em Hosts do Container Registry.

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

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 que será excluído. Nos nomes dos buckets, PROJECT-ID é 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 em Excluir. Uma caixa de diálogo de confirmação será exibida.

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

gsutil

Se você quiser excluir em massa cem mil ou mais imagens de um bucket, evite usar a gsutil, pois 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 gsutil rm. com a sinalização -r.

gsutil rm -r gs://BUCKET-NAME

Substitua BUCKET-NAME pelo armazenamento do Container Registry. do bucket. Nos nomes dos buckets, PROJECT-ID é o 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

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 serviço projeto, deixe a API Container Registry ativada. Se você tentar desativar a API Container Registry. O Container Registry vai mostrar um aviso se outros serviços com uma conta estão ativadas no projeto. Como desativar a API Container Registry desativa automaticamente todos os serviços no mesmo projeto com um dependências, mesmo que você não esteja usando o Container Registry com essas serviços.

A seguir