Receber sugestões de papéis predefinidos com a ajuda do Gemini

Nesta página, descrevemos como encontrar e conceder papéis predefinidos do Identity and Access Management (IAM) aos seus principais com a ajuda do Gemini.

Com o seletor de papéis do IAM, você pode perguntar ao Gemini quais papéis conceder aos seus principais. Normalmente, para encontrar os papéis predefinidos certos a serem concedidos, é necessário pesquisar no índice de papéis e permissões do IAM ou na página Papéis no Google Cloud console. Com o seletor de papéis do IAM, você pode descrever as ações que quer que o principal execute e os recursos que ele precisa para isso. Com base na sua entrada, o Gemini sugere os papéis predefinidos que considera adequados.

O Gemini pode sugerir papéis predefinidos para principais individuais. Se o Gemini sugerir conceder uma função no nível do projeto, use o seletor de funções do IAM para fazer isso.

Não é possível usar o seletor de papéis do IAM para receber sugestões sobre o seguinte:

• Papéis personalizados
• Funções para vários principais (com um único comando)
• Funções para produtos do Google Workspace, como o Google Planilhas e o Google Docs

Observação: o Gemini não pode sugerir papéis personalizados no seletor de papéis do IAM, mas você ainda pode receber sugestões de papéis personalizados do Gemini usando a API Policy Assist (prévia) ou o painel de chat do Gemini Cloud Assist. Para instruções, consulte Usar o Gemini Cloud Assist no console Google Cloud na documentação do Gemini Cloud Assist.

Saiba como e quando o Gemini para Google Cloud usa seus dados.

Antes de começar

Antes de receber sugestões de papéis predefinidos do Gemini, verifique se você concluiu os seguintes pré-requisitos.

Console

Você pode usar o seletor de papéis do IAM no console do Google Cloud sem ativar nenhuma API.

REST

Visualizar

Este produto ou recurso está sujeito aos "Termos das Soluções Pré-GA" na seção "Termos Gerais de Serviço" dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para receber sugestões de papéis com a API REST do Policy Assist, ative a API Policy Assist no seu projeto no console do Google Cloud :

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

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Se este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissões necessárias.

Ative a API Policy Assist:

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

gcloud services enable policyassist.googleapis.com

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Se este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissões necessárias.

Ative a API Policy Assist:

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

gcloud services enable policyassist.googleapis.com

Funções exigidas

Para receber as permissões necessárias para usar o seletor de papéis do IAM, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

• Receber sugestões de papéis no console: Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin)
• Receba sugestões de papéis personalizados com a API: Leitor do IAM (roles/iam.viewer)

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

Esses papéis predefinidos contêm as permissões necessárias para usar o seletor de papéis do IAM. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para usar o seletor de papéis do IAM:

• Receber sugestões de função no console:
  • resourcemanager.projects.get
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.setIamPolicy
• Receba sugestões de papéis personalizados com a API: iam.roles.list

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Receber sugestões de papéis com a ajuda do Gemini

Você pode pedir sugestões de papéis ao Gemini usando o console doGoogle Cloud ou a API REST do Policy Assist.

Como uma tecnologia em estágio inicial, os produtos do Gemini para Google Cloudpodem gerar uma saída plausível, mas que é factualmente incorreta. Recomendamos que você valide todas as saídas dos produtos do Gemini para Google Cloud antes de usá-las. Para mais informações, consulte Gemini para Google Cloud e IA responsável.

Console

Para receber sugestões de papéis do Gemini no console do Google Cloud , acesse o seletor de papéis do IAM em páginas que permitem conceder acesso no nível do projeto. Por exemplo, o seletor de papéis do IAM está disponível nas seguintes páginas do console do Google Cloud :

• A página IAM
• A página Contas de serviço
• A página Painel do console Google Cloud

O procedimento a seguir usa a página do IAM como o principal ponto de entrada.

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

   Acesse IAM

2. Selecione um projeto.

3. Selecione um principal para receber sugestões de papéis:

   • Para receber sugestões de papéis para um principal que já tenha outros papéis no recurso, encontre uma linha contendo o principal e clique em Editar principal nessa linha.

     Para conceder um papel a um agente de serviço, marque a caixa de seleção Incluir concessões de papel fornecidas peloGoogle para ver o endereço de e-mail dele.

     Observação: não é possível editar papéis herdados ao gerenciar o acesso a um recurso. Para editar os papéis herdados, acesse o recurso em que o papel foi concedido.

   • Para receber sugestões de papéis para um principal que ainda não tem papéis no recurso, clique em Conceder acesso e insira um identificador principal, por exemplo, [e-mail] ou //iam.googleapis.com/locations/global/workforcePools/example-pool/group/[e-mail].

4. Para abrir a caixa de diálogo do seletor de papéis do IAM, clique em Ajude-me a escolher papéis.

5. Descreva, com suas próprias palavras, a ação que você quer que o principal execute e o recurso no projeto que ele precisa para fazer isso.

6. Clique em Sugerir funções. Com base na sua entrada, o Gemini sugere os papéis predefinidos que considera adequados.

   Para mais informações sobre as funções e por que o Gemini as sugeriu, clique em Mostrar justificativa. Também recomendamos usar a referência de papéis e permissões para validar os papéis sugeridos pelo Gemini antes de concedê-los ao principal.

7. Opcional: se o Gemini não sugerir as funções certas, você pode refinar o comando.

   1. Para modificar o comando, clique em Editar.
   2. Edite a descrição e clique em Atualizar. O Gemini atualiza as sugestões de função com base na nova descrição.

8. Para aceitar as sugestões, clique em Adicionar funções.

9. Opcional: adicione uma condição ao papel.

10. Clique em Salvar. O principal recebe o papel no recurso.

É possível conceder papéis no nível do projeto sugeridos pelo Gemini diretamente no seletor de papéis do IAM. Para sugestões de papéis no nível da organização, pasta ou recurso, anote os papéis sugeridos e conceda-os ao principal no nível adequado usando o processo típico no console Google Cloud . Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Se você não tiver as permissões para conceder as funções nos níveis da organização, pasta ou recurso, entre em contato com o administrador.

REST

Visualizar

Este produto ou recurso está sujeito aos "Termos das Soluções Pré-GA" na seção "Termos Gerais de Serviço" dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para receber sugestões de papéis com a API REST do Policy Assist, chame o método recommendIamRoles.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• PROJECT_ID: o ID do projeto do Google Cloud . Os IDs de projeto são alfanuméricos, como my-project.
• USER_INSTRUCTIONS: o comando em linguagem natural que descreve as permissões necessárias. Por exemplo, "Sugira uma função que me permita ver buckets de armazenamento".

Método HTTP e URL:

POST https://policyassist.googleapis.com/v1/projects/PROJECT_ID/locations/global:recommendIamRoles

Corpo JSON da solicitação:

{
  "prompt": {
    "userInstructions": "USER_INSTRUCTIONS"
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://policyassist.googleapis.com/v1/projects/PROJECT_ID/locations/global:recommendIamRoles"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://policyassist.googleapis.com/v1/projects/PROJECT_ID/locations/global:recommendIamRoles" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "summary": "",
  "recommendations": [
    {
      "type": "RECOMMENDATION_TYPE_PREDEFINED_ROLES",
      "roles": [
        {
          "name": "roles/storage.objectViewer",
          "roleType": "ROLE_TYPE_PREDEFINED",
          "grantableScopes": [
            "Projects",
            "Buckets"
          ]
        },
        {
          "name": "roles/storage.legacyBucketReader",
          "roleType": "ROLE_TYPE_PREDEFINED",
          "grantableScopes": [
            "Projects"
          ]
        }
      ],
      "intro": "The following roles match your description:"
      "detailedReasoning": "The roles/storage.objectViewer role grants permissions to view objects and their metadata. The roles/storage.legacyBucketReader grants broader read access to buckets and objects. Choose the one that best fits the principle of least privilege for your use case."
    }
  ]
}

Para saber como conceder os papéis sugeridos ao principal no nível adequado, consulte Gerenciar o acesso a projetos, pastas e organizações. Se você não tiver permissão para conceder as funções, entre em contato com o administrador.

Exemplos de casos de uso

A tabela a seguir ilustra alguns exemplos de casos de uso para o seletor de papéis do IAM. Por padrão, o Gemini sugere papéis projetados para abranger jornadas comuns do usuário em um serviço. Por exemplo, o Gemini costuma sugerir os papéis de administrador, editor ou leitor de um serviço.

Se você quiser que o Gemini sugira as funções mais granulares e com menos privilégios, especifique essa preferência no comando usando palavras-chave específicas. Para conferir uma lista de palavras-chave que você pode usar, consulte Palavras-chave para funções com privilégios mínimos. No entanto, é importante lembrar que os papéis com menos privilégios podem não ser suficientes para as necessidades futuras de um usuário.

Caso de uso	Exemplos de prompt
Identificar papéis para o gerenciamento geral de serviços	"Quais permissões preciso ter para gerenciar nossa configuração do AlloyDB para PostgreSQL?" "Quais papéis preciso ter para trabalhar com o BigQuery?" "Como conceder acesso a alguém para executar e depurar serviços do Cloud Run?" "Preciso provisionar uma identidade de agente da Vertex AI para executar chamadas básicas de ferramentas."
Identificar as funções necessárias para realizar tarefas específicas	"Qual função é necessária para criar, iniciar e parar VMs?" "Preciso permitir que um usuário crie e gerencie conjuntos de dados e tabelas do BigQuery." "Preciso conceder a uma conta de serviço acesso para invocar funções do Cloud Run." "Quero que meu agente acione um servidor MCP local que implantei no Cloud Run." Comandos que geram sugestões de papéis com privilégios mínimos: "Qual é a função mínima necessária para criar, iniciar e parar VMs?" "Quais são os papéis do IAM com privilégios mínimos necessários para criar políticas do IAM?" "Preciso conceder a uma conta de serviço acesso para invocar funções do Cloud Run. Qual é o acesso mais restrito necessário?" "Qual é o papel menos permissivo que meu agente precisa para acionar um servidor MCP local implantado no Cloud Run?"
Identificar os papéis necessários para executar comandos da Google Cloud CLI	"Qual papel do IAM é necessário para executar: gcloud compute instances create instance-1?" Comando que gera sugestões de papéis com privilégios mínimos: "Qual é a menor função que uma conta de serviço precisa para executar: gcloud datastore instances describe?"
Identificar papéis para uma tarefa que inclui dependências transitivas	"Preciso configurar uma instância do Compute Engine para escalonar automaticamente com base na utilização da CPU. Quais papéis do IAM devo conceder à conta de serviço?" Comando que gera sugestões de papéis com privilégios mínimos: "Preciso configurar uma instância do Compute Engine para escalonar automaticamente com base na utilização da CPU. Quais são as permissões mínimas que preciso conceder a uma conta de serviço usada por um escalonador automático de instâncias do Compute Engine?"
Identificar papéis para uma tarefa que pode exigir uma combinação de vários papéis granulares	"Conceda aos usuários acesso apenas a um conjunto de dados específico no BigQuery. Não é possível criar ou excluir conjuntos de dados." Comando que gera sugestões de papéis com privilégios mínimos: "Qual é a função mais segura para dar aos usuários acesso somente leitura a um único conjunto de dados no BigQuery, sem permitir ações de criação ou exclusão em nenhum conjunto de dados?"

Práticas recomendadas

Para ajudar o Gemini a dar as sugestões mais precisas para seu caso de uso, recomendamos que você siga as práticas recomendadas ao criar seu comando.

• Descreva claramente seu caso de uso. Evite usar linguagem vaga nos comandos. Seja o mais claro possível sobre as ações que você quer que o principal execute em quais serviços e tipos de recursos. Se quiser que o Gemini sugira os papéis com privilégio mínimo, crie um comando com palavras-chave específicas que descrevam sua intenção de seguir o princípio de privilégio mínimo.

  O que fazer	O que não fazer	Detalhes
  "Qual função é necessária para executar consultas SQL em uma tabela do BigQuery e ler os dados dela?"	"Qual função é necessária para executar instruções SQL?"	O SQL é uma linguagem genérica usada em vários serviços do Google Cloud . Sem especificar o serviço ou as ações, o Gemini não consegue sugerir uma função precisa.
  "Preciso de papéis para iniciar, interromper e reiniciar instâncias de máquina virtual do Compute Engine."	"Preciso gerenciar minhas máquinas virtuais."	O termo gerenciar é muito vago. Gerenciar pode significar criar, excluir, atualizar ou visualizar VMs. Listar claramente as ações específicas a serem realizadas (iniciar, parar, reiniciar) e o tipo de recurso exato (instâncias de máquina virtual do Compute Engine) gera sugestões mais precisas.
  "Preciso fazer upload e download de objetos de um bucket do Cloud Storage chamado example-bucket."	"Me dê acesso ao armazenamento."	O termo Storage sozinho pode se referir a vários serviços, como Cloud Storage, Filestore ou Persistent Disk. Além disso, não há ações especificadas. Sem especificar o serviço (Cloud Storage), o nome do tipo de recurso (example-bucket) ou as ações (upload e download de objetos), o Gemini não tem informações suficientes para sugerir as funções certas.
  "Preciso da função menos permissiva que ofereça acesso somente de lista ao Secret Manager."	"Preciso de acesso limitado para gerenciar meus segredos."	A frase acesso limitado não define claramente as restrições necessárias. Gerenciar meus secrets abrange uma ampla variedade de ações (criar, listar, atualizar, excluir, acessar versões). Sem usar palavras-chave explícitas, como privilégio mínimo, o Gemini sugere papéis mais gerais de administrador, editor ou leitor específicos do serviço.

• Use nomes oficiais. Use os nomes oficiais dos serviços, tipos de recursos e operações de API do Google Cloud no seu comando. Se você não tiver certeza sobre os nomes oficiais de serviços, tipos de recursos ou operações de API, consulte a documentação oficial do produto.

  O que fazer	O que não fazer	Detalhes
  "Qual função preciso ter para atualizar conjuntos de dados do BigQuery?"	"Qual função preciso ter para atualizar conjuntos de dados do BigQuery?"	BigQuery é o nome oficial do produto, não Big query.
  "Qual função é necessária para criar um bucket do Cloud Storage no meu projeto?"	"Qual função é necessária para criar um bucket do Storage no meu projeto?"	Bucket de armazenamento pode se referir a diferentes tipos de recursos de serviços como Cloud Storage, Filestore ou Persistent Disk. Especificar o nome do produto e o tipo de recurso associado gera sugestões mais precisas.

Palavras-chave para papéis com privilégio mínimo

Se você precisar de sugestões de papéis do Gemini que sigam o princípio de privilégio mínimo, use palavras-chave específicas no comando. Confira abaixo uma lista não exaustiva de palavras-chave que podem ser usadas para solicitar funções com menos privilégios:

• menos permissiva
• mais seguro
• menor função
• privilégio mínimo
• permissões mínimas
• estritamente granular
• acesso mais restrito
• apenas o mínimo absoluto
• somente com as permissões exatas

Solução de problemas

Esta seção descreve soluções para problemas comuns com o seletor de papéis do IAM.

O Gemini sugere papéis que não podem ser concedidos no nível do projeto

O Gemini pode sugerir papéis em todos os níveis de recursos, mas só é possível usar o seletor de papéis do IAM para conceder os papéis no nível do projeto sugeridos. Quando o Gemini sugere papéis no nível da organização, da pasta ou do recurso, o seletor de papéis do IAM indica que há papéis sugeridos que não podem ser concedidos, e o botão Adicionar papéis fica desativado.

Quando isso acontecer, copie os papéis sugeridos e conceda-os ao principal no nível adequado usando o processo típico no consoleGoogle Cloud . Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Se você não tiver as permissões para conceder as funções nos níveis da organização, pasta ou recurso, entre em contato com o administrador.

A seguir

• Leia a visão geral do Gemini para Google Cloud.
• Saiba como o Gemini para Google Cloud usa seus dados.
• Saiba como encontrar manualmente os papéis predefinidos certos.
• Use o servidor MCP remoto do Policy Assist para dar aos agentes externos acesso ao seletor de papéis do IAM.