Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Criar e conceder papéis a agentes de serviço

No Google Cloud, os agentes de serviço para envolvidos no projeto, pasta e organização são criados automaticamente à medida que você ativa e usa os serviços doGoogle Cloud . Às vezes, esses agentes de serviço também recebem automaticamente papéis que permitem criar e acessar recursos em seu nome.

Se necessário, também é possível pedir ao Google Cloud para criar agentes de serviço para envolvidos no projeto, no nível da pasta e da organização antes de usar o serviço. Pedir ao Google Cloud para criar agentes de serviço permite que você conceda papéis a eles antes de usar um serviço. Se um agente de serviço ainda não tiver sido criado, não será possível conceder papéis a ele.

Essa opção é útil se você usa uma das seguintes estratégias para gerenciar as políticas de permissão:

Um framework declarativo, como o Terraform. Se a configuração do Terraform não incluir os papéis dos agentes de serviço, eles serão revogados quando você aplicar a configuração. Ao criar agentes de serviço e conceder papéis a eles na configuração do Terraform, você garante que esses papéis não sejam revogados.
Um sistema de políticas como código que armazena cópias das políticas de permissão atuais em um repositório de código. Se você permitir que o Google Cloud conceda papéis aos agentes de serviço automaticamente, eles vão aparecer na política de permissões real, mas não na cópia armazenada. Para resolver essa inconsistência, revogue esses papéis incorretamente. Ao criar agentes de serviço e conceder a eles papéis de maneira proativa, é possível evitar desvios entre o repositório de código e as políticas de permissão reais.

Depois de acionar a criação do agente de serviço, conceda a ele os papéis que normalmente são concedidos automaticamente. Se você não fizer isso, alguns serviços poderão não funcionar corretamente. Isso ocorre porque os agentes de serviço criados na solicitação de um usuário não recebem papéis automaticamente.

Antes de começar

Ative as APIs Resource Manager e Workload Identity.
Funções necessárias para ativar APIs
Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.
Ativar as APIs
Entenda os agentes de serviço.

Funções exigidas

Para receber as permissões necessárias para criar e conceder acesso aos agentes de serviço, peça ao administrador para conceder a você os seguintes papéis do IAM nos projetos, pastas e organizações em que você está criando agentes de serviço e concedendo acesso:

Listar os serviços disponíveis e os endpoints deles: Leitor do Service Usage (roles/serviceusage.serviceUsageViewer)
Ativar agentes de serviço: Administrador da API Workload Identity (roles/workloadidentity.admin)
Conceder aos agentes de serviço acesso a um projeto: Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin)
Conceder aos agentes de serviço acesso a uma pasta: Administrador de pastas (roles/resourcemanager.folderAdmin)
Conceder aos agentes de serviço acesso a projetos, pastas e organizações: Administrador da organização (roles/resourcemanager.organizationAdmin)

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 criar e conceder acesso a agentes de serviço. 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 criar e conceder acesso a agentes de serviço:

Liste os serviços disponíveis e os endpoints deles: serviceusage.services.list
Ativar agentes de serviço: workloadidentity.serviceAgents.create
Ver operações de longa duração: workloadidentity.operations.get
Conceder aos agentes de serviço acesso a um projeto:
- resourcemanager.projects.getIamPolicy
- resourcemanager.projects.setIamPolicy
Conceder aos agentes de serviço acesso a uma pasta:
- resourcemanager.folders.getIamPolicy
- resourcemanager.folders.setIamPolicy
Conceder aos agentes de serviço acesso a uma organização:
- resourcemanager.organizations.getIamPolicy
- resourcemanager.organizations.setIamPolicy

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

Identificar os agentes de serviço a serem criados

Para identificar os agentes de serviço e os recursos que você precisa criar, faça o seguinte:

Faça uma lista dos serviços que você usa e dos endpoints de API correspondentes. Para ver todos os serviços disponíveis e os endpoints, use um dos seguintes métodos:
Console

Acesse a página Biblioteca de APIs no Google Cloud console.

Acessar a biblioteca de APIs

O endpoint da API é o Nome do serviço listado na seção Detalhes adicionais.
gcloud

O comando gcloud services list lista todos os serviços disponíveis para um projeto.

Antes de usar os dados do comando abaixo, faça estas substituições:
- EXPRESSION: opcional. Uma expressão para filtrar os resultados. Por exemplo, a expressão a seguir filtra todos os serviços com nomes que contenham googleapis.com, mas não sandbox:
  name ~ googleapis.com AND name !~ sandbox
  Para uma lista de expressões de filtro, consulte gcloud topic filters.
- LIMIT: opcional. O número máximo de resultados a serem listados. O padrão é unlimited.
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
Windows (PowerShell)
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
Windows (cmd.exe)

Observação: se esse comando usar ' para citar conteúdo, substitua essas aspas simples por aspas duplas. Se as aspas estiverem aninhadas, use \" para escapar das aspas internas.
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
A resposta contém os nomes e os títulos de todos os serviços disponíveis. O endpoint da API é o valor no campo NAME.
REST

O método services.list da API Service Usage lista todos os serviços disponíveis para um projeto.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- RESOURCE_TYPE: o tipo de recurso para listar os serviços disponíveis. Use projects, folders ou organizations.
- RESOURCE_ID: o ID do projeto, da pasta ou da organização do Google Cloud para listar os serviços disponíveis. Os IDs do projeto são strings alfanuméricas, como my-project. Os IDs de pastas e organizações são numéricos, como 123456789012.
- PAGE_SIZE: opcional. O número de serviços a serem incluídos na resposta. O valor padrão é 50, e o valor máximo é 200. Se o número de serviços for maior que o tamanho da página, a resposta conterá um token de paginação que pode ser usado para recuperar a próxima página de resultados.
- NEXT_PAGE_TOKEN: opcional. O token de paginação retornado em uma resposta anterior desse método. Se especificado, a lista de serviços começará onde a solicitação anterior foi finalizada.
Método HTTP e URL:
GET https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN
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.

Execute o seguinte comando:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN"
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.

execute o seguinte comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN" | Select-Object -Expand Content
A resposta contém os nomes e títulos de todos os serviços disponíveis para o recurso. Se o número de serviços disponíveis for maior que o tamanho da página, a resposta também conterá um token de paginação.

O endpoint da API é o valor no campo name.

Para cada endpoint de API que você vai usar, faça uma lista dos recursos em que é necessário criar os agentes de serviço desse endpoint:

Na página de referência do agente de serviço, pesquise cada endpoint de API para encontrar todos os agentes de serviço dele.

Alguns endpoints podem não ter agentes de serviço associados. Você pode pular a criação de agente de serviço para esses endpoints.

Para cada um dos agentes de serviço do endpoint, use o endereço de e-mail do agente de serviço para determinar onde você precisa criar o agente de serviço.

O marcador de posição no endereço de e-mail de um agente de serviço indica onde é necessário criar o agente de serviço:

Placeholder	Onde criar o agente de serviço
`PROJECT_NUMBER`	Cada projeto em que você usará o serviço
`FOLDER_NUMBER`	Cada pasta em que você usará o serviço
`ORGANIZATION_NUMBER`	Cada organização em que você usará o serviço

Para cada endpoint, registre cada recurso exclusivo em que você precisa criar agentes de serviço para esse endpoint.

Acionar a criação do agente de serviço

Depois de saber quais agentes de serviço você precisa criar, peça aoGoogle Cloud para criá-los.

Ao pedir para o Google Cloud criar agentes de serviço, você fornece a ele um serviço e um recurso. Em seguida,o Google Cloud cria todos os agentes de serviço para esse serviço e esse recurso.

Durante esta etapa, se você estiver usando a CLI gcloud ou a API REST, também poderá criar uma lista das funções que precisam ser concedidas a cada agente de serviço. Você vai usar essas informações para conceder papéis aos agentes de serviço. Se você estiver usando o Terraform, não precisará manter o controle manual dos papéis necessários porque é possível referenciar os papéis de maneira programática.

gcloud

Use o comando gcloud workload-identity service-agents generate para criar agentes de serviço para cada endpoint e recurso identificados em Identificar agentes de serviço a serem criados.

Cada vez que você executar o comando, revise a resposta. Para cada papel na resposta, registre o endereço de e-mail do agente de serviço a que o papel deve ser concedido. Você vai usar essas informações para conceder papéis aos agentes de serviço.

Antes de usar os dados do comando abaixo, faça estas substituições:

ENDPOINT: o endpoint da API em que você quer criar agentes de serviço, por exemplo, aiplatform.googleapis.com.
RESOURCE_TYPE: o tipo de recurso em que você quer criar agentes de serviço. Use project, folder ou organization.
RESOURCE_ID: o ID numérico do projeto, da pasta ou da organização do Google Cloud para o qual você quer criar agentes de serviço. Por exemplo, 123456789012.

É possível criar agentes de serviço para um recurso por vez. Se você precisar criar agentes de serviço para vários recursos, execute o comando uma vez para cada recurso.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud workload-identity service-agents generate --service="ENDPOINT" \
    --location="global" --RESOURCE_TYPE="RESOURCE_ID"

Windows (PowerShell)

gcloud workload-identity service-agents generate --service="ENDPOINT" `
    --location="global" --RESOURCE_TYPE="RESOURCE_ID"

Windows (cmd.exe)

gcloud workload-identity service-agents generate --service="ENDPOINT" ^
    --location="global" --RESOURCE_TYPE="RESOURCE_ID"

A resposta contém uma lista de todos os agentes de serviço criados. Para cada agente de serviço, a resposta lista o recurso para o qual ele foi criado, o endereço de e-mail do agente, o serviço a que ele está associado e o estado do agente. Se o agente de serviço normalmente receber uma função específica, a resposta também vai listar essa função.

O papel listado não é concedido automaticamente ao agente de serviço. Para cada função na resposta, registre o endereço de e-mail do agente de serviço a quem a função deve ser concedida. Você vai usar essas informações para conceder papéis aos agentes de serviço.

Confira a seguir um exemplo truncado da resposta para a criação de agentes de serviço para aiplatform.googleapis.com.

Provisioned service agents for aiplatform.googleapis.com under projects/123456789012:

container: projects/123456789012
principal: serviceAccount:service-123456789012@gcp-sa-aiplatform.iam.gserviceaccount.com
role: roles/aiplatform.serviceAgent
serviceProducer: aiplatform.googleapis.com
state: ACTIVE
----
container: projects/123456789012
principal: serviceAccount:service-123456789012@gcp-ri-aiplatform.iam.gserviceaccount.com
serviceProducer: aiplatform.googleapis.com
state: ACTIVE
----
...
----
container: projects/123456789012
principal: serviceAccount:service-123456789012@gcp-sa-vertex-vtc.iam.gserviceaccount.com
role: roles/aiplatform.trainingClusterServiceAgent
serviceProducer: aiplatform.googleapis.com
state: ACTIVE
----

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform. Para mais informações, consulte a documentação de referência do provedor Terraform.

Use o recurso google_workload_identity_service_agent para acionar a criação de agentes de serviço para cada endpoint e recurso identificado em Identificar agentes de serviço a serem criados.

Por exemplo, se você quiser criar todos os agentes de serviço para envolvidos no projeto para o BigQuery no projeto padrão, adicione o seguinte código à configuração do Terraform:

data "google_project" "default" {
}

# Create all project-level bigquery.googleapis.com service agents
resource "google_workload_identity_service_agent" "primary" {
  parent = "projects/${data.google_project.default.number}/locations/global/serviceProducers/bigquery.googleapis.com"
}

REST

Para cada endpoint em que você precisa criar agentes de serviço, faça o seguinte:

Crie agentes de serviço para cada recurso identificado em Identificar agentes de serviço a serem criados:

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- RESOURCE_TYPE: o tipo de recurso em que você quer criar agentes de serviço. Use projects, folders ou organizations.
- RESOURCE_NUMERIC_ID: o ID numérico do Google Cloud projeto, da pasta ou da organização para o qual você quer criar agentes de serviço. Por exemplo, 123456789012.
  
  É possível criar agentes de serviço para um recurso por vez. Se você precisar criar agentes de serviço para vários recursos, envie uma solicitação para cada recurso.
- ENDPOINT: o endpoint da API em que você quer criar um agente de serviço, por exemplo, aiplatform.googleapis.com.
Método HTTP e URL:
```
POST https://workloadidentity.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUMERIC_ID/locations/global/serviceProducers/ENDPOINT:generateServiceAgents
```
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.

Execute o seguinte comando:
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://workloadidentity.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUMERIC_ID/locations/global/serviceProducers/ENDPOINT:generateServiceAgents"
```
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.

execute o seguinte comando:
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://workloadidentity.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUMERIC_ID/locations/global/serviceProducers/ENDPOINT:generateServiceAgents" | Select-Object -Expand Content
```
A resposta contém um Operation que indica o status da solicitação. Exemplo:
```
{
  "name": "projects/123456789012/locations/global/operations/operation-1775250941060-64e94d1baa76d-1aa958f3-07b2ea9c",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.OperationMetadata",
    "createTime": "2026-04-03T21:15:41.367155118Z",
    "target": "projects/123456789012/locations/global/serviceProducers/bigquery.googleapis.com",
    "verb": "passthroughLro",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}
```
Receba a resposta da operação concluída. Para cada papel na resposta, registre o endereço de e-mail do agente de serviço a quem o papel deve ser concedido. Você vai usar essas informações para conceder papéis aos agentes de serviço.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- OPERATION_NAME: o nome de uma operação generateServiceAgents. Copie esse valor do campo name de uma resposta serviceProducers.generateServiceAgents. Por exemplo, projects/123456789012/locations/global/operations/operation-1775250941060-64e94d1baa76d-1aa958f3-07b2ea9c.
- PROJECT_ID: o ID do projeto do Google Cloud . Os IDs do projeto são strings alfanuméricas, como my-project.
Método HTTP e URL:
```
GET https://workloadidentity.googleapis.com/v1/OPERATION_NAME
```
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.

Execute o seguinte comando:
```
curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://workloadidentity.googleapis.com/v1/OPERATION_NAME"
```
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.

execute o seguinte comando:
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://workloadidentity.googleapis.com/v1/OPERATION_NAME" | Select-Object -Expand Content
```
APIs Explorer (navegador)

Abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Preencha todos os campos obrigatórios e clique em Executar.

As operações em andamento retornam uma resposta como esta:
```
{
  "name": "projects/123456789012/locations/global/operations/operation-1775258415970-64e968f44b91a-28fcf2f5-38367cfe",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.OperationMetadata",
    "createTime": "2026-04-03T23:20:15.982631253Z",
    "target": "projects/123456789012/locations/global/serviceProducers/aiplatform.googleapis.com",
    "verb": "passthroughLro",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}
```
As operações concluídas retornam uma resposta que contém uma lista de agentes de serviço criados. Para cada agente de serviço, a resposta lista o recurso para o qual ele foi criado, o endereço de e-mail do agente, o serviço a que ele está associado e o estado do agente. Se o agente de serviço normalmente receber uma função específica, a resposta também vai listar essa função.

O papel listado não é concedido automaticamente ao agente de serviço. Para cada função na resposta, registre o endereço de e-mail do agente de serviço a quem a função deve ser concedida. Você vai usar essas informações para conceder papéis aos agentes de serviço.

Confira a seguir um exemplo truncado da resposta para a criação de agentes de serviço para aiplatform.googleapis.com.
```
{
  "name": "projects/123456789012/locations/global/operations/operation-1775258415970-64e968f44b91a-28fcf2f5-38367cfe",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.OperationMetadata",
    "createTime": "2026-04-03T23:20:15.982631253Z",
    "endTime": "2026-04-03T23:20:17.315225515Z",
    "target": "projects/123456789012/locations/global/serviceProducers/aiplatform.googleapis.com",
    "verb": "passthroughLro",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.GenerateServiceAgentsResponse",
    "serviceAgents": [
      {
        "container": "projects/123456789012",
        "serviceProducer": "aiplatform.googleapis.com",
        "principal": "serviceAccount:service-123456789012@gcp-sa-aiplatform.iam.gserviceaccount.com",
        "role": "roles/aiplatform.serviceAgent",
        "state": "ACTIVE"
      },
      {
        "container": "projects/123456789012",
        "serviceProducer": "aiplatform.googleapis.com",
        "principal": "serviceAccount:service-123456789012@gcp-ri-aiplatform.iam.gserviceaccount.com",
        "state": "ACTIVE"
      },
      ...
      {
        "container": "projects/123456789012",
        "serviceProducer": "aiplatform.googleapis.com",
        "principal": "serviceAccount:service-123456789012@gcp-sa-vertex-vtc.iam.gserviceaccount.com",
        "role": "roles/aiplatform.trainingClusterServiceAgent",
        "state": "ACTIVE"
      }
    ]
  }
}
```

Conceder papéis a agentes de serviço

Depois que o Google Cloud criar os agentes de serviço necessários para projetos, pastas e organizações, use os endereços de e-mail deles para conceder papéis.

Se você pediu ao Google Cloud para criar agentes de serviço, conceda a eles os papéis que normalmente são concedidos automaticamente. Se você não fizer isso, alguns serviços poderão não funcionar corretamente. Isso ocorre porque os agentes de serviço criados na solicitação de um usuário não recebem papéis automaticamente.

Console

Use a lista de papéis e agentes de serviço que você criou em Acionar a criação do agente de serviço para identificar quais agentes precisam receber papéis. Para cada agente de serviço que precisa de uma função, faça o seguinte:

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

Acesse IAM
Selecione um projeto, uma pasta ou uma organização em que você criou o agente de serviço.
Clique em Conceder acesso e insira o endereço de e-mail do agente de serviço.
Clique em Selecionar um papel e insira o nome de um papel ou permissão para filtrar um papel a ser concedido. Para seguir o princípio de privilégio mínimo, escolha um papel que inclua apenas as permissões necessárias ao principal.
Clique em Salvar. O agente de serviço recebe o papel no recurso.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

RESOURCE_TYPE: o tipo de recurso ao qual você quer gerenciar o acesso. Use projects, resource-manager folders ou organizations.
RESOURCE_ID: o ID do seu Google Cloud projeto, pasta ou organização. Os IDs de projeto são alfanuméricos, como my-project. Os IDs de pastas e organizações são numéricos, como 123456789012.
PRINCIPAL: o endereço de e-mail do agente de serviço a quem você quer conceder acesso, precedido por serviceAccount:. Por exemplo, serviceAccount:service-0123456789012@gcp-sa-aiplatform-cc.iam.gserviceaccount.com.
ROLE_NAME: o nome da função que você quer conceder ao agente de serviço.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
    --member=PRINCIPAL --role=ROLE_NAME \
    --condition=CONDITION

Windows (PowerShell)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID `
    --member=PRINCIPAL --role=ROLE_NAME `
    --condition=CONDITION

Windows (cmd.exe)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID ^
    --member=PRINCIPAL --role=ROLE_NAME ^
    --condition=CONDITION

A resposta contém a política de permissão do IAM atualizada.

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform. Para mais informações, consulte a documentação de referência do provedor Terraform.

Para conceder papéis a agentes de serviço, faça o seguinte:

Para cada recurso google_workload_identity_service_agent, conceda todos os papéis associados aos agentes de serviço.

Por exemplo, se você quiser conceder papéis a todos os agentes de serviço do recurso google_workload_identity_service_agent.primary, adicione o seguinte código à configuração do Terraform:

# Grant roles to BigQuery service agents for project
resource "google_project_iam_member" "service_agents" {
  for_each = {
    for i, agent in google_workload_identity_service_agent.primary.service_agents :
    i => agent if try(agent.role, "") != ""
  }
  project = data.google_project.default.project_id
  role    = each.value.role
  member  = each.value.principal
}

Execute um comando terraform apply direcionado para o recurso google_workload_identity_service_agent que você adicionou na seção Acionar a criação do agente de serviço desta página.
Por exemplo, se você adicionou um recurso chamado google_workload_identity_service_agent.primary, execute o seguinte comando:
```
terraform apply target="google_workload_identity_service_agent.primary"
```
A execução desse comando garante que o recurso google_project_iam_member possa referenciar recursos do agente de serviço sem receber erros Known After Apply.
Execute o comando terraform plan para sua configuração do Terraform. Esse comando mostra o plano de execução para conceder papéis aos agentes de serviço. Se o plano de execução estiver bom, execute terraform apply para aplicá-lo.

REST

Use a lista de papéis e agentes de serviço que você criou em Acionar a criação do agente de serviço para identificar quais agentes precisam receber papéis. Para conceder papéis aos agentes de serviço, use o padrão read-modify-write para atualizar a política de permissão do recurso:

Leia a política de permissão atual chamando getIamPolicy.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- API_VERSION: a versão da API a ser usada. Para projetos e organizações, use v1. Para pastas, use v2.
- RESOURCE_TYPE: o tipo de recurso com a política que você quer gerenciar. Use o valor projects, folders ou organizations.
- RESOURCE_ID: o ID do seu Google Cloud projeto, organização ou pasta. Os IDs do projeto são strings alfanuméricas, como my-project. Os IDs de pastas e organizações são numéricos, como 123456789012.
- POLICY_VERSION: a versão da política a ser retornada. As solicitações precisam especificar a versão mais recente da política, que é a versão 3 da política. Para saber mais detalhes, consulte Como especificar uma versão da política ao receber uma política.
Método HTTP e URL:
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy
```
Corpo JSON da solicitação:
```
{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}
```
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://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy"
```
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 a seguir:
```
$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://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy" | Select-Object -Expand Content
```
APIs Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

A resposta contém a política de permissão do projeto. Exemplo:
```
{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:my-user@example.com"
      ]
    }
  ]
}
```
Para cada agente de serviço a quem você quer conceder um papel, crie uma vinculação de papel que conceda ao agente o papel necessário. Por exemplo, a vinculação de função a seguir concede ao agente de serviço de código personalizado da AI Platform a função de agente de serviço de código personalizado da Vertex AI (roles/aiplatform.customCodeServiceAgent):
```
  {
    "role": "roles/aiplatform.customCodeServiceAgent",
    "members": [
      "serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com",
    ]
  }
```
Se a política de permissão já tiver uma vinculação de função para o papel necessário, adicione o agente de serviço à lista members para essa vinculação.
Grave a política de permissão atualizada chamando setIamPolicy.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- API_VERSION: a versão da API a ser usada. Para projetos e organizações, use v1. Para pastas, use v2.
- RESOURCE_TYPE: o tipo de recurso com a política que você quer gerenciar. Use o valor projects, folders ou organizations.
- RESOURCE_ID: o ID do seu Google Cloud projeto, organização ou pasta. Os IDs do projeto são strings alfanuméricas, como my-project. Os IDs de pastas e organizações são numéricos, como 123456789012.
- POLICY: uma representação JSON da política que você quer definir. Para mais informações sobre o formato de uma política, consulte a referência da política.
Método HTTP e URL:
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy
```
Corpo JSON da solicitação:
```
{
  "policy": POLICY
}
```
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://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy"
```
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 a seguir:
```
$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://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy" | Select-Object -Expand Content
```
APIs Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

A resposta contém a política de permissão atualizada.

Observação: se você tratar as políticas do IAM como código e armazená-las em um sistema de controle de versões, armazene a política retornada, não a política que você enviou na solicitação.

A seguir

Veja uma lista de todos os agentes de serviço.
Conheça outras maneiras de atribuir papéis a principais.
Saiba como criar contas de serviço gerenciadas pelo usuário, que podem agir como identidades para suas cargas de trabalho.
Saiba mais sobre as práticas recomendadas para usar o Terraform no Google Cloud.
Confira todos os exemplos do Terraform.Google Cloud

Criar e conceder papéis a agentes de serviço Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Funções exigidas

Permissões necessárias

Identificar os agentes de serviço a serem criados

Console

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Acionar a criação do agente de serviço

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

APIs Explorer (navegador)

Conceder papéis a agentes de serviço

Console

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

APIs Explorer (navegador)

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

APIs Explorer (navegador)

A seguir

Criar e conceder papéis a agentes de serviço