Controle de acesso com o IAM

Nesta página, descrevemos as permissões para controlar o acesso ao Container Registry.

Depois de configurar as permissões, você pode configurar a autenticação para clientes do Docker que usa para enviar e extrair imagens.

Se você usa o Artifact Analysis para trabalhar com metadados de contêiner, como vulnerabilidades encontradas em imagens, consulte a documentação do Artifact Analysis e saiba como conceder acesso para visualizar ou gerenciar metadados.

Antes de começar

Verifique se você tem permissões para gerenciar usuários. Você precisa ter permissões em uma das seguintes funções:

• Administrador IAM do projeto (roles/resourcemanager.projectIamAdmin)
• Administrador de segurança (roles/iam.securityAdmin)

Como alternativa à concessão desses papéis, é possível usar um papel personalizado ou predefinido com as mesmas permissões.

Permissões e papéis

Todos os usuários, contas de serviço e outras identidades que interagem com o Container Registry precisam ter as permissões apropriadas do Identity and Access Management (IAM) para o Cloud Storage.

• Os serviçosGoogle Cloud que normalmente acessam o Container Registry são configurados com permissões padrão para registros no mesmo projetoGoogle Cloud . Se as permissões padrão não atenderem às suas necessidades, configure as permissões adequadas.
• Para outras identidades, é necessário configurar as permissões necessárias.

Você controla o acesso aos hosts do Container Registry com permissões do Cloud Storage. A tabela a seguir lista os papéis do Cloud Storage que têm as permissões necessárias para o Container Registry.

Algumas permissões adicionais são necessárias ao visualizar imagens do Container Registry usando o console Google Cloud . Consulte Permissões comuns necessárias para usar o console do Cloud.

Acesso necessário	Papel	Onde conceder permissões
Extrair imagens (somente leitura) de um registro atual	Leitor de objetos do Storage (roles/storage.objectViewer)	Conceda o papel no bucket de armazenamento do registro.
Enviar (gravar) e extrair (ler) imagens de um host de registro existente em um projeto	Gravador de bucket legado do Storage (roles/storage.legacyBucketWriter)	Conceda o papel no bucket de armazenamento do registro. Essa permissão está disponível apenas no nível do bucket, não sendo possível concedê-la no nível do projeto.
Adicione hosts de registro a projetos Google Cloud e crie os buckets de armazenamento associados.	Administrador do Storage (roles/storage.admin)	Conceder o papel no nível do projeto

Para enviar imagens, é necessário ter permissões de leitura e gravação de objetos, além da permissão storage.buckets.get. O papel Gravador de bucket legado do Storage inclui as permissões necessárias em um único papel do Cloud Storage, mas não concede controle total sobre buckets e objetos de armazenamento.

O papel de administrador do Storage concede controle total sobre buckets e objetos de armazenamento. Se você conceder essa permissão no nível do projeto, o principal terá acesso a todos os buckets de armazenamento no projeto, incluindo aqueles que não são usados pelo Container Registry. Considere cuidadosamente quais principais precisam desse papel.

• Por padrão, a conta de serviço do Cloud Build tem permissões no papel de administrador do Storage. Portanto, essa conta de serviço pode adicionar registros ao projeto pai com o primeiro push e enviar imagens para registros existentes no projeto pai.
• Se você usa o Docker ou outras ferramentas para criar e enviar imagens a um registro, considere adicionar registros ao seu projeto usando uma conta com o papel Administrador do Storage mais permissivo e, em seguida, conceda os papéis Gravador de bucket legados do Storage ou Leitor de objetos do Storage a outras contas que precisam enviar ou extrair imagens.

Para mais informações sobre papéis e permissões do Cloud Storage, consulte a documentação do Cloud Storage.

Conceder permissões do IAM

O Container Registry usa intervalos do Cloud Storage como armazenamento subjacente para imagens de contêiner. Você controla o acesso às imagens concedendo permissões ao bucket de um registro.

O primeiro envio de imagem para um nome de host adiciona o host do registro e o bucket de armazenamento dele a um projeto. Por exemplo, o primeiro push para gcr.io/my-project adiciona o host do registro gcr.io ao projeto com o ID do projeto my-project e cria um bucket de armazenamento para o registro. O nome do bucket tem um dos seguintes formatos:

• artifacts.PROJECT-ID.appspot.com para imagens armazenadas no host gcr.io
• STORAGE-REGION.artifacts.PROJECT-ID.appspot.com para imagens armazenadas em outros hosts de registro

Para realizar esse primeiro push de imagem, a conta que está fazendo o push precisa ter permissões no papel de administrador de armazenamento.

Depois do envio inicial da imagem para um host de registro, conceda permissões no bucket de armazenamento do registro para controlar o acesso às imagens no registro:

• Gravador de bucket legado do Storage para enviar e extrair
• Leitor de objetos do Storage para extrair apenas

Você pode conceder permissão para um bucket usando o Google Cloud console ou a Google Cloud CLI.

Limitações e restrições

Só é possível conceder permissões no nível do bucket de armazenamento para hosts do Container Registry.

• O Container Registry ignora as permissões definidas em objetos individuais em um bucket do Cloud Storage.
• Não é possível conceder permissões em repositórios dentro de um registro. Se você precisar de um controle de acesso mais granular, o Artifact Registry oferece controle de acesso no nível do repositório e pode ser mais adequado às suas necessidades.
• Se você ativar o acesso uniforme no nível do bucket para qualquer bucket de armazenamento do Container Registry, conceda permissões explicitamente a todos os usuários e contas de serviço que acessam seus registros. Nesse caso, os papéis Proprietário e Editor por si só podem não ser suficientes para conceder as permissões necessárias.

Conceder permissões

1. Se o host do registro ainda não existir no projeto, uma conta com permissões na função de administrador de armazenamento precisará enviar a primeira imagem para o registro. Isso cria o bucket de armazenamento para o host do registro.

   O Cloud Build tem as permissões necessárias para fazer o push inicial da imagem no mesmo projeto. Se você estiver enviando imagens com outra ferramenta, verifique as permissões da conta Google Cloud que você está usando para autenticar com o Container Registry.

   Para mais informações sobre como enviar a imagem inicial com o Docker, consulte Adicionar um registro.

2. No projeto com o Container Registry, conceda as permissões apropriadas no bucket do Cloud Storage usado pelo host do registro.

   Observação: não é possível conceder permissões de gravador de bucket legado do Storage no nível do projeto. Além disso, conceder permissões de leitor de objetos do Storage em um projeto inteiro dá acesso a todos os buckets de armazenamento, incluindo aqueles que não são usados pelo Container Registry.

   Console

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

   2. Clique no link artifacts.PROJECT-ID.appspot.com ou STORAGE-REGION.artifacts.PROJECT-ID.appspot.com para o bucket.

      Substitua PROJECT-ID pelo Google Cloud ID do projeto do projeto que hospeda o Container Registry e STORAGE-REGION pela multirregião (asia, eu ou us) do registro que hospeda a imagem.

   3. Selecione a guia Permissões.

   4. Clique em Adicionar.

   5. No campo Principais, insira os endereços de e-mail das contas que precisam de acesso, separados por vírgulas. O endereço de e-mail pode ser:

      • Uma Conta do Google (por exemplo, [e-mail])
      • um Grupo do Google (por exemplo, [e-mail]);

      • Uma conta de serviço do IAM.

        Consulte a lista de serviços do Google Cloud que geralmente acessam registros para encontrar o endereço de e-mail da conta de serviço associada. Se o serviço estiver sendo executado em um projeto diferente do Container Registry, use o endereço de e-mail da conta de serviço no outro projeto.

   6. No menu suspenso Selecionar um papel, selecione a categoria Cloud Storage e escolha a permissão adequada.

      • Leitor de objetos do Storage para extrair apenas imagens
      • Gravador de bucket legado do Storage para enviar e extrair imagens

   7. Clique em Adicionar.

   Observação: os endereços de e-mail e domínios precisam estar associados a uma conta ativa do Google ou do Google Apps.

   gcloud

   1. Execute o seguinte comando para listar os intervalos no projeto:

      gcloud storage ls
      

      A resposta terá esta aparência:

      gs://[BUCKET_NAME1]/
      gs://[BUCKET_NAME2]/
      gs://[BUCKET_NAME3]/ ...
      

      Encontre o bucket do host do registro na lista retornada. O bucket que armazena as imagens tem o nome BUCKET-NAME em um dos seguintes formatos:

      • artifacts.PROJECT-ID.appspot.com para imagens armazenadas no host gcr.io
      • STORAGE-REGION.artifacts.PROJECT-ID.appspot.com para imagens armazenadas em outros hosts de registro

      Onde

      • PROJECT-ID é o Google Cloud ID do projeto.
      • STORAGE-REGION é o local do bucket de armazenamento:
        • us para registros no host us.gcr.io
        • eu para registros no host eu.gcr.io
        • asia para registros no host asia.gcr.io

   2. Execute o seguinte comando no shell ou janela do terminal:

      gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
      --member=TYPE:EMAIL-ADDRESS \
      --role=ROLE
      

      Onde

      • BUCKET_NAME é o nome do intervalo do Cloud Storage no formato artifacts.PROJECT-ID.appspot.com ou STORAGE-REGION.artifacts.PROJECT-ID.appspot.com.
      • TYPE pode ser um dos seguintes:
        • serviceAccount, se EMAIL-ADDRESS especifica uma conta de serviço.
        • user, se EMAIL-ADDRESS for uma Conta do Google.
        • group, se EMAIL-ADDRESS for um Grupo do Google.

      • EMAIL-ADDRESS pode ser:

        • Uma Conta do Google (por exemplo, [e-mail])
        • um Grupo do Google (por exemplo, [e-mail]);

        • Uma conta de serviço do IAM.

          Consulte a lista de serviços do Google Cloud que geralmente acessam registros para encontrar o endereço de e-mail da conta de serviço associada. Se o serviço estiver sendo executado em um projeto diferente do Container Registry, use o endereço de e-mail da conta de serviço no outro projeto.

      • ROLE é o papel do Cloud Storage que você quer conceder.

        • objectViewer para extrair imagens
        • legacyBucketWriter enviar e extrair imagens

   Por exemplo, este comando concede à conta de serviço [e-mail] permissões para enviar e extrair imagens no bucket my-example-bucket:

   gcloud storage buckets add-iam-policy-binding gs://my-example-bucket \
     --member=serviceAccount:[e-mail] \
     --role=roles/storage.objectUser
   

   O comando gcloud storage buckets add-iam-policy-binding altera as permissões de IAM do bucket de armazenamento em que o registro está hospedado. Outros exemplos estão na documentação da CLI gcloud.

   Observação: os endereços de e-mail e domínios precisam estar associados a uma conta ativa do Google ou do Google Apps.

3. Se você estiver configurando o acesso para VMs do Compute Engine ou nós do GKE que vão enviar imagens para o Container Registry, consulte Configurar VMs e clusters para mais etapas de configuração.

Configurar o acesso público a imagens

O Container Registry é acessível publicamente se o bucket de armazenamento subjacente do local do host for acessível publicamente. Em um projeto, todas as imagens em cada local do host são públicas ou não. No host de um projeto, não é possível veicular publicamente apenas imagens específicas. Se você tiver imagens específicas que quer tornar públicas:

• tenha o cuidado de mantê-las em um local de host separado que você torna público ou
• Crie um novo projeto para manter as imagens acessíveis publicamente.

Para disponibilizar imagens de contêiner publicamente, torne o intervalo de armazenamento subjacente acessível publicamente seguindo estas etapas:

Aviso: quando o bucket de armazenamento subjacente de um projeto do Container Registry está acessível publicamente, qualquer pessoa pode extrair imagens desse local do host. Para instruções sobre como extrair imagens de um registro, consulte Como extrair imagens de um registro.

1. Você precisa ter enviado uma imagem ao Container Registry para que o bucket de armazenamento subjacente exista.

2. Encontre o nome do bucket do Cloud Storage para esse registro. Para fazer isso, liste os buckets:

   gcloud storage ls
   

   Seu URL de bucket do Container Registry será listado como gs://artifacts.PROJECT-ID.appspot.com ou gs://STORAGE-REGION.artifacts.PROJECT-ID.appspot.com, em que:

   • PROJECT-ID é o Google Cloud ID do projeto. Os projetos com escopo de domínio terão o nome de domínio como parte do ID do projeto.
   • STORAGE-REGION é o local do bucket de armazenamento:
     • us para registros no host us.gcr.io
     • eu para registros no host eu.gcr.io
     • asia para registros no host asia.gcr.io

3. Torne o bucket de armazenamento do Container Registry acessível ao público. Basta executar o comando a seguir, que disponibiliza ao público todas as imagens no bucket.

   gcloud storage buckets add-iam-policy-binding gs://BUCKET-NAME \
       --member=allUsers --role=roles/storage.objectViewer
   

   em que:

   • gs://BUCKET-NAME é o URL do bucket do Container Registry

Observação: o projeto será faturado com os custos de saída de rede pela disponibilização dos objetos de armazenamento. Leia Preços do Cloud Storage para saber mais sobre os custos do tráfego de saída.

Remover o acesso público às imagens

Console

1. Você precisa ter enviado uma imagem ao Container Registry para que o bucket de armazenamento subjacente exista.

2. Abra a página Container Registry no console Google Cloud .

   Abrir a página do Container Registry

3. No painel esquerdo, clique em Configurações.

4. Na página Configurações, em Acesso público, alterne a visibilidade para Particular. Essa configuração controla o acesso ao bucket de armazenamento subjacente.

gcloud storage

1. Encontre o nome do bucket do Cloud Storage para esse registro. Para fazer isso, liste os buckets:

   gcloud storage ls
   

   Seu URL de bucket do Container Registry será listado como gs://artifacts.PROJECT-ID.appspot.com ou gs://STORAGE-REGION.artifacts.PROJECT-ID.appspot.com, em que:

   • PROJECT-ID é o ID do projeto do seu console Google Cloud . Os projetos com escopo de domínio terão o nome de domínio como parte do ID do projeto.
   • STORAGE-REGION é o local do bucket de armazenamento:
     • us para registros no host us.gcr.io
     • eu para registros no host eu.gcr.io
     • asia para registros no host asia.gcr.io

2. Para remover o acesso público ao bucket de armazenamento, execute o seguinte comando no shell ou na janela de terminal:

   gcloud storage bucket remove-iam-policy-binding gs://BUCKET-NAME \
     --member=allUsers --role=roles/storage.objectViewer
   

em que:

• BUCKET-NAME é o nome do bucket desejado.

Revogar permissões

Siga as etapas abaixo para revogar as permissões do IAM.

Console

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

2. Clique no link artifacts.PROJECT-ID.appspot.com ou STORAGE-REGION.artifacts.PROJECT-ID.appspot.com para o bucket. Aqui, PROJECT-ID é o ID do projetoGoogle Cloud do projeto que hospeda o Container Registry e STORAGE-REGION é a multirregião (asia, eu ou us) do registro que hospeda a imagem.

3. Selecione a guia Permissões.

4. Clique no ícone da lixeira ao lado de qualquer principal que você quer remover.

gcloud

Execute o seguinte comando no shell ou janela do terminal:

gcloud storage bucket remove-iam-policy-binding gs://BUCKET-NAME \
    --member=PRINCIPAL --all

em que:

• BUCKET-NAME é o nome do bucket desejado.
• PRINCIPAL pode ser um dos seguintes:
  • user:EMAIL-ADDRESS para uma Conta do Google
  • serviceAccount:EMAIL-ADDRESS para uma conta de serviço do IAM
  • group:EMAIL-ADDRESS para um Grupo do Google.
  • allUsers para revogar o acesso público

Integrar com serviços do Google Cloud

Para a maioria das contas de serviço Google Cloud , configurar o acesso a um registro só exige conceder as permissões adequadas do IAM.

Permissões padrão para serviços do Google Cloud

Google Cloud serviços como o Cloud Build ou o Google Kubernetes Engine usam uma conta de serviço padrão ou um agente de serviço para interagir com recursos no mesmo projeto.

Você mesmo precisa configurar ou modificar permissões se:

• O serviço Google Cloud está em um projeto diferente do Container Registry.
• As permissões padrão não atendem às suas necessidades. Por exemplo, a conta de serviço padrão do Compute Engine tem acesso somente leitura ao armazenamento no mesmo projeto. Se você quiser enviar uma imagem da VM para um registro, modifique as permissões da conta de serviço da VM ou faça a autenticação no registro com uma conta que tenha acesso de gravação ao armazenamento.
• Você está usando uma conta de serviço personalizada para interagir com o Container Registry

As seguintes contas de serviço normalmente acessam o Container Registry. O endereço de e-mail da conta de serviço inclui o Google Cloud ID ou número do projeto em que o serviço está sendo executado.

Serviço	Conta de serviço	Endereço de e-mail	Permissões
Ambiente flexível do App Engine	Conta de serviço padrão do App Engine	[e-mail]	Função de editor, pode ler e gravar no armazenamento
Compute Engine	Conta de serviço padrão do Compute Engine	[e-mail]	Função de editor, limitada ao acesso somente leitura ao armazenamento
Cloud Build	Conta de serviço do Cloud Build	[e-mail]	As permissões padrão incluem a criação de buckets de armazenamento e acesso de leitura e gravação ao armazenamento.
Cloud Run	Conta de serviço padrão do Compute Engine A conta de serviço padrão do ambiente de execução para revisões.	[e-mail]	Função de editor, limitada ao acesso somente leitura ao armazenamento
GKE	Conta de serviço padrão do Compute Engine A conta de serviço padrão para nós.	[e-mail]	Função de editor, limitada ao acesso somente leitura ao armazenamento

Configurar VMs e clusters para enviar imagens

O Compute Engine e qualquer serviço Google Cloud que o use têm a conta de serviço padrão do Compute Engine como identidade padrão.

As permissões do IAM e os escopos de acesso afetam a capacidade das VMs de ler e gravar no armazenamento.

• As permissões do IAM determinam o acesso a um recurso.
• Os escopos de acesso determinam os escopos padrão do OAuth para solicitações feitas por meio da CLI gcloud e das bibliotecas de cliente em uma instância de VM. Como resultado, os escopos de acesso podem limitar ainda mais o acesso aos métodos da API ao autenticar com credenciais padrão do aplicativo.
  • Para extrair uma imagem particular, a conta de serviço da VM precisa ter a permissão read para o intervalo de armazenamento da imagem.
  • Para enviar uma imagem privada, a conta de serviço da VM precisa ter o escopo de acesso read-write, cloud-platform ou full-control para o bucket de armazenamento da imagem.

A conta de serviço padrão do Compute Engine tem o papel de editor por padrão, que inclui permissões para criar e atualizar recursos para a maioria dos serviços doGoogle Cloud . No entanto, para a conta de serviço padrão ou uma conta de serviço personalizada associada a uma VM, o escopo de acesso padrão para buckets de armazenamento é somente leitura. Isso significa que, por padrão, as VMs não podem enviar imagens.

Se você pretende implantar imagens apenas em ambientes como o Compute Engine e o GKE, não é necessário modificar o escopo de acesso. Se você quiser executar aplicativos nesses ambientes que enviam imagens para o registro, será necessário fazer outras configurações.

As configurações a seguir exigem mudanças nas permissões do IAM ou na configuração do escopo de acesso.

Como enviar imagens de uma VM ou cluster

Se você quiser enviar imagens por push, a conta de serviço da instância de VM precisará ter o escopo storage-rw em vez de storage-ro.

A VM e o Container Registry estão em projetos separados

Você precisa conceder à conta de serviço permissões do IAM para acessar o bucket de armazenamento usado pelo Container Registry.

Como executar comandos gcloud em VMs

A conta de serviço precisa ter o escopo cloud-platform. Esse escopo concede permissões para enviar e extrair imagens, bem como executar comandos gcloud.

As etapas para configurar escopos estão nas seções a seguir.

Configurar escopos para VMs

Para definir escopos de acesso ao criar uma VM, use a opção --scopes.

gcloud compute instances create INSTANCE --scopes=SCOPE

Em que

• INSTANCE é o nome da instância de VM;
• SCOPE é o escopo que você quer configurar para a conta de serviço da VM:
  • Solicitar imagens: storage-ro
  • Solicitar e enviar imagens: storage-rw
  • Solicitar e enviar imagens, executar comandos gcloud: cloud-platform

Para alterar os escopos de uma instância de VM existente:

Defina o escopo de acesso com a opção --scopes.

1. Pare a instância de VM. Consulte Como interromper uma instância.

2. Altere o escopo de acesso com o comando a seguir.

   gcloud compute instances set-service-account INSTANCE --scopes=SCOPE
   

   Em que

   • INSTANCE é o nome da instância de VM;
   • SCOPE é o escopo que você quer configurar para a conta de serviço da VM:
     • Solicitar imagens: storage-ro
     • Solicitar e enviar imagens: storage-rw
     • Solicitar e enviar imagens, executar comandos gcloud: cloud-platform

3. Reinicie a instância de VM. Consulte Como iniciar uma instância interrompida.

Se você quiser usar uma conta de serviço personalizada para VMs em vez da conta de serviço padrão, especifique a conta de serviço e os escopos de acesso a serem usados ao criar a VM ou modificar as configurações da VM.

Configurar escopos para clusters do Google Kubernetes Engine

Por padrão, novos clusters do GKE são criados com permissões somente leitura para intervalos do Cloud Storage.

Para definir o escopo de armazenamento read-write ao criar um cluster do Google Kubernetes Engine, use a opção --scopes. Por exemplo, o comando a seguir cria um cluster com os escopos bigquery, storage-rw e compute-ro:

gcloud container clusters create example-cluster \
--scopes=bigquery,storage-rw,compute-ro

Para mais informações sobre escopos que podem ser definidos ao criar um novo cluster, consulte a documentação do comando gcloud container clusters create.

Observação: a partir da versão 1.10 do Google Kubernetes Engine, os novos clusters e pools de nós não têm o escopo de acesso compute-rw por padrão. Além disso, o comando gcloud container create não adiciona mais silenciosamente os escopos de acesso compute-rw ou storage-ro quando você especifica a flag --scopes no comando. Para mais informações sobre essa mudança, consulte a documentação do GKE.

A conta de serviço do Container Registry

O agente de serviço do Container Registry atua em nome do Container Registry ao interagir com os serviços do Google Cloud . O agente de serviço tem o conjunto mínimo de permissões necessárias se você ativou a API Container Registry depois de 5 de outubro de 2020. Antes, o agente de serviço tinha o papel Editor. Para mais informações sobre o agente de serviço e como modificar as permissões dele, consulte Conta de serviço do Container Registry.

Faça um teste

Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho do Container Registry em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Teste o Container Registry sem custos financeiros