Como configurar o controle de acesso

Observação: o Artifact Registry é a evolução do Container Registry e aceita vários formatos de artefatos, repositórios regionais e controle de acesso mais granular. Saiba mais sobre a transição para o Artifact Registry.

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 Container Analysis para trabalhar com metadados de contêiner, como vulnerabilidades descobertas por imagens, veja a documentação do Container Analysis e saiba como conceder acesso para visualizar ou gerenciar metadados.

Requisitos gerais de acesso

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 armazenamento do Cloud Storage.

Para a conta de serviço usada pelas VMs do Compute Engine, incluindo VMs nos clusters do Google Kubernetes Engine, o acesso é baseado em permissões do IAM e escopos de acesso.

Permissões para a conta de serviço do Container Registry

O agente de serviço do Container Registry é uma conta de serviço gerenciada pelo Google que atua em nome do Container Registry ao interagir com os serviços do Google Cloud.

Para impor o princípio de segurança do menor privilégio, essa conta de serviço recebe o papel de Agente de serviço do Container Registry em projetos em que a API Container Registry foi ativada após 5 de outubro de 2020. Esse papel tem as seguintes permissões:

• Publicar tópicos: pubsub.topics.publish
• Ler ACLs de objeto de armazenamento: storage.objects.getIamPolicy
• Ler dados e metadados do objeto de armazenamento: storage.objects.get
• Listar objetos de armazenamento em um bucket e ler metadados de objeto: storage.objects.list

Anteriormente, a conta de serviço do Container Registry tinha o papel Editor. Como o papel de Editor concede permissões para criar e excluir a maioria dos recursos em um projeto, recomendamos restringir as permissões se sua conta de serviço do Container Registry tiver esse papel.

Para verificar as permissões atuais da conta de serviço do Container Registry, execute o comando:

gcloud projects get-iam-policy PROJECT-ID  \
--flatten="bindings[].members" \
--format='table(bindings.role)' \
--filter="bindings.members:[e-mail]"

Onde

• PROJECT-ID é o ID do projeto do Google Cloud;
• PROJECT-NUMBER é o número do projeto do Google Cloud;

É possível conseguir o ID e o número do projeto no Console do Google Cloud ou com os seguintes comandos:

PROJECT=$(gcloud config get-value project)
echo $PROJECT && gcloud projects list --filter="$PROJECT" --format="value(PROJECT_NUMBER)"

Para conceder o papel de Agente de serviço do Container Registry e revogar o papel de editor:

1. Conceda o papel Agente de serviço do Container Registry com o seguinte comando:

   gcloud projects add-iam-policy-binding PROJECT-ID \
   --member=serviceAccount:[e-mail] --role=roles/containerregistry.ServiceAgent
   

2. Revogue o papel de editor com o seguinte comando:

   gcloud projects remove-iam-policy-binding PROJECT-ID \
   --member=serviceAccount:[e-mail] --role=roles/editor
   

Permissões IAM

As permissões do IAM determinam quem pode acessar os recursos. Todos os usuários, contas de serviço e outras identidades que interagem com o Container Registry precisam ter as permissões apropriadas do Cloud Storage.

Por padrão, o Google Cloud usa contas de serviço padrão para interagir com recursos dentro do mesmo projeto. Por exemplo, a conta de serviço do Cloud Build pode enviar e extrair imagens quando o Container Registry está no mesmo projeto.

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

• Você está usando uma conta de serviço em um projeto para acessar o Container Registry em um projeto diferente
• Você está usando uma conta de serviço padrão com acesso somente leitura ao armazenamento, mas quer extrair e enviar imagens
• Você está usando uma conta de serviço personalizada para interagir com o Container Registry

Escopos de acesso para VMs e clusters

Para contas de serviço associadas a VMs do Compute Engine, incluindo VMs em clusters do GKE, o acesso ao armazenamento é baseado nas permissões do IAM e no escopo de acesso de armazenamento configurado.

A conta de serviço padrão do Compute Engine está configurada para extrair imagens no mesmo projeto que a VM. Se você precisar de um cluster de VM ou GKE para extrair imagens ou interagir com o Container Registry em um projeto diferente, consulte Como usar o Container Registry com o Google Cloud.

Como configurar 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 apropriadas do Cloud Storage a um usuário, grupo, conta de serviço ou outra identidade.

As permissões do Cloud Storage concedidas no nível do projeto se aplicam a todos os intervalos de armazenamento no projeto, não apenas aos intervalos usados pelo Container Registry. Para configurar permissões específicas para o Container Registry, conceda permissões no intervalo de armazenamento usado pelo registro. O Container Registry ignora as permissões definidas em objetos individuais no intervalo de armazenamento.

Embora também seja possível usar os papéis no nível do projeto Owner, Editor e Viewer para conceder acesso, os papéis do Cloud Storage permitem aplicar o princípio de segurança de menor privilégio para que os usuários e as contas de serviço ter apenas as permissões necessárias.

Os produtos e aplicativos do Google Cloud que interagem com o Google Cloud usam contas de serviço para interagir com o Container Registry. As considerações a seguir se aplicam ao acesso à conta de serviço:

• Por padrão, as contas de serviço de algumas integrações comuns são configuradas com acesso ao Container Registry no mesmo projeto. Por exemplo, por padrão, a conta de serviço do Cloud Build pode enviar e extrair imagens no mesmo projeto.
• Se a conta de serviço precisar acessar o Container Registry em outro projeto, será preciso conceder as permissões necessárias no projeto com o Container Registry.
• As instâncias de VM, incluindo aquelas nos clusters do Google Kubernetes Engine, precisam ter os escopos de acesso de armazenamento corretos para enviar ou extrair imagens. Por padrão, as VMs podem extrair imagens quando o Container Registry está no mesmo projeto.

Permissões e papéis

A tabela abaixo explica as permissões e os papéis necessários para realizar as ações do Container Registry.

Observação: se você ativar o acesso uniforme no nível do intervalo para qualquer intervalo de armazenamento, verifique se todos os usuários e contas de serviço do Container Registry têm papéis do Cloud Storage explicitamente definido. Nesse caso, os papéis Proprietário e Editor por si só podem não ser suficientes para conceder as permissões necessárias.

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

Ação	Permissões	Papel	Título do papel
Enviar (leitura e gravação)	storage.buckets.create storage.buckets.delete storage.buckets.get storage.buckets.list storage.buckets.update storage.objects.create storage.objects.delete storage.objects.get storage.objects.list storage.objects.update	roles/storage.admin	Administrador do Storage
Extrair (somente leitura)	storage.objects.get storage.objects.list	roles/storage.objectViewer	Leitor de objetos do Storage

Como conceder permissões do IAM

Conceda permissões no intervalo de armazenamento que o Container Registry usa.

Cuidado: o Container Registry só reconhece as permissões definidas no bucket do Cloud Storage. O Container Registry ignora as permissões definidas em objetos individuais em um intervalo do Cloud Storage.

Como conceder permissões

1. Se o local do host do Container Registry (gcr.io, asia.gcr.io, eu.gcr.io, us.gcr.io) ainda não existir no projeto, um usuário com permissões de proprietário, editor ou administrador de armazenamento precisará criar o intervalo de armazenamento enviando uma imagem para o host.

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

   O intervalo que armazena as imagens tem o nome BUCKET-NAME do formulário:

   • artifacts.PROJECT-ID.appspot.com para imagens enviadas para um registro no host gcr.io ou
   • STORAGE-REGION.artifacts.PROJECT-ID.appspot.com

   Em que

   • PROJECT-ID é o ID do projeto do seu Console do Google Cloud.
   • 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

   Você pode conceder permissão para um intervalo usando o Console do Google Cloud ou a ferramenta de linha de comando gsutil.

   Console

   1. Visite a página do Cloud Storage no Console do Cloud.

   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 projeto do Google 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 em Adicionar membros.

   5. No menu exibido, preencha o campo Membros com os endereços de e-mail dos usuários que precisam de permissão, 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.
      • a conta de serviço padrão do Compute Engine de outro projeto. Essa conta é usada pelo Google Kubernetes Engine para extrair clusters de imagens de contêiner por padrão. Ele está no formato [e-mail], em que PROJECT-NUMBER é o número do projeto do Google Cloud do projeto que executa o cluster do Google Kubernetes Engine.

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

      • Visualizador de objetos do Storage para extrair apenas imagens
      • Administrador do Storage para enviar e extrair imagens

   7. Clique em Add.

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

   gsutil

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

      gsutil ls
      

      A resposta terá esta aparência:

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

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

      gsutil iam ch TYPE:EMAIL-ADDRESS:ROLE gs://BUCKET_NAME
      

      Em que

      • 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 um dos seguintes:
        • uma Conta do Google (por exemplo, [e-mail]);
        • um Grupo do Google (por exemplo, [e-mail]);
        • uma conta de serviço do IAM.
        • a conta de serviço padrão do Compute Engine de outro projeto. Essa conta é usada pelo Google Kubernetes Engine para extrair clusters de imagens de contêiner por padrão. Ele está no formato [e-mail], em que PROJECT_NUMBER é o número do projeto do Google Cloud do projeto que executa o cluster do Google Kubernetes Engine.
      • ROLE é o papel do Cloud Storage que você quer conceder.
        • objectViewer para extrair imagens
        • objectAdmin para enviar e extrair imagens
      • BUCKET_NAME é o nome do intervalo do Cloud Storage no formato artifacts.PROJECT-ID.appspot.com ou STORAGE-REGION.artifacts.PROJECT-ID.appspot.com.

   O comando gsutil iam ch altera as permissões de IAM do bucket de armazenamento em que o registro está hospedado. Você pode executar pull de imagens do registro com uma conta que tenha permissões de objectViewer.

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

   Consulte a documentação do gsutil iam para mais informações sobre o comando.

3. O Compute Engine e o Google Kubernetes Engine são configurados com permissões para extrair imagens por padrão do Container Registry no mesmo projeto. Se você tiver outros requisitos para essas integrações, consulte Integração com os serviços do Google Cloud.

Como 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:

Console

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

2. Abra a página do Container Registry no Console do 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 Público ou Particular. Essa configuração controla o acesso ao bucket de armazenamento subjacente.

   Quando a visibilidade do host é pública, todas as imagens em seu projeto do Google Cloud que estão nesse local de host podem ser acessadas publicamente.

gsutil

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:

   gsutil 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 do 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

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.

   gsutil iam ch allUsers:objectViewer gs://BUCKET-NAME
   

   em que:

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

Quando o Container Registry é acessível publicamente, qualquer pessoa pode extrair suas imagens. Para instruções, consulte Como extrair imagens de um registro.

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.

Como revogar permissões

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

Console

1. Visite a página do Cloud Storage no Console do Cloud.

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 projeto do Google 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 membro que você quer remover.

gsutil

Execute o seguinte comando no shell ou janela de terminal:

gsutil iam ch -d MEMBER gs://BUCKET-NAME

em que:

• MEMBER 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
• BUCKET-NAME é o nome do bucket desejado.

Integração com os serviços do Google Cloud

Por padrão, as contas de serviço de algumas integrações comuns são configuradas para acesso pull ou pull e push dentro do mesmo projeto. O acesso é baseado nas permissões do IAM, e você só precisa configurar permissões se a conta de serviço estiver se conectando ao Container Registry em um projeto diferente.

A conta de serviço associada às instâncias de VM do Compute Engine, incluindo VMs em clusters do GKE, tem um requisito adicional. O acesso da VM ao armazenamento é baseado em permissões do IAM concedidas e em escopos de acesso.

• As permissões do IAM determinam quem pode acessar um recurso.
• Os escopos de acesso determinam os escopos padrão do OAuth para solicitações feitas por meio da ferramenta 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 a permissão read-write, cloud-platform ou full-control para o intervalo de armazenamento da imagem.

Por padrão, a conta de serviço padrão do Compute Engine tem permissão de editor para recursos no mesmo projeto e no escopo de acesso de armazenamento read-only. O escopo read-only limita uma VM a extrair apenas imagens. A conta de serviço padrão tem o sufixo @developer.gserviceaccount.com.

As seguintes configurações exigem que você altere a permissão padrão ou a configuração do escopo.

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 com 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 permissões e escopos estão nas seções a seguir.

Como configurar permissões do IAM para VMs

Por padrão, as VMs do Compute Engine só podem acessar o armazenamento no mesmo projeto. Se a VM precisar acessar o Container Registry em um projeto diferente, conceda permissões à conta de serviço da VM.

1. No projeto com sua instância de VM, consiga o nome da conta de serviço padrão do Compute Engine ou a conta de serviço associada à instância de VM. A conta de serviço padrão tem o sufixo @developer.gserviceaccount.com.

2. No projeto com o Container Registry, conceda permissões para que a conta de serviço possa acessar o Container Registry.

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

Como 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 do Google Kubernetes Engine versão 1.10, gcloud e do Cloud Console não concede mais o escopo de acesso compute-rw em novos clusters e pools de nós por padrão. Além disso, se --scopes for especificado em gcloud container create, a gcloud não adicionará silenciosamente compute-rw nem storage-ro. Para mais informações sobre essa alteração, consulte a documentação do GKE.