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

Crea y otorga roles a los agentes de servicio

En Google Cloud, los agentes de servicio a nivel del proyecto, la carpeta y la organización se crean automáticamente a medida que habilitas y usas los servicios deGoogle Cloud . A veces, a estos agentes de servicio también se les otorgan automáticamente roles que les permiten crear recursos y acceder a ellos en tu nombre.

Si es necesario, también puedes solicitar Google Cloud que se creen agentes de servicio a nivel del proyecto, la carpeta y la organización para un servicio antes de usarlo. Solicitar Google Cloud la creación de agentes de servicio te permite otorgarles roles antes de usar un servicio. Si aún no se creó un agente de servicio, no puedes otorgarle roles.

Esta opción es útil si usas una de las siguientes estrategias para administrar tus políticas de permiso:

Un framework declarativo como Terraform Si tu configuración de Terraform no incluye los roles de los agentes de servicio, esos roles se revocarán cuando apliques la configuración. Si creas agentes de servicio y les otorgas roles en tu configuración de Terraform, te aseguras de que estos roles no se revoquen.
Un sistema de políticas como código que almacena copias de tus políticas de permiso actuales en un repositorio de código Si permites que Google Cloud otorgue roles a los agentes de servicio automáticamente, esos roles aparecerán en tu política de permisos real, pero no en la copia almacenada de la política de permisos. Para resolver esta incoherencia, es posible que revoques estos roles de forma incorrecta. Si creas agentes de servicio y les otorgas roles de forma proactiva, puedes ayudar a evitar la desviación entre tu repositorio de código y tus políticas de permiso reales.

Después de activar la creación del agente de servicio, debes otorgarles los roles que suelen recibir automáticamente. De lo contrario, es posible que algunos servicios no funcionen correctamente. Esto se debe a que los agentes de servicio que se crean a pedido del usuario no se les otorgan roles automáticamente.

Antes de comenzar

Habilita las APIs de Resource Manager y Workload Identity.
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.
Habilitar las API
Comprende cómo funcionan los agentes de servicio.

Roles obligatorios

Para obtener los permisos que necesitas para crear agentes de servicio y otorgarles acceso, pídele a tu administrador que te otorgue los siguientes roles de IAM en los proyectos, las carpetas y las organizaciones para los que creas agentes de servicio y a los que les otorgas acceso:

Enumera los servicios disponibles y sus extremos: Visualizador de Service Usage (roles/serviceusage.serviceUsageViewer)
Habilita los agentes de servicio: Administrador de la API de Workload Identity (roles/workloadidentity.admin)
Otorga a los agentes de servicio acceso a un proyecto: Administrador de IAM de proyecto (roles/resourcemanager.projectIamAdmin)
Otorga a los agentes de servicio acceso a una carpeta: Administrador de carpetas (roles/resourcemanager.folderAdmin)
Otorga a los agentes de servicio acceso a proyectos, carpetas y organizaciones: Administrador de la organización (roles/resourcemanager.organizationAdmin)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para crear agentes de servicio y otorgarles acceso. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear agentes de servicio y otorgarles acceso:

Enumera los servicios disponibles y sus extremos: serviceusage.services.list
Habilita los agentes de servicio: workloadidentity.serviceAgents.create
Ver operaciones de larga duración: workloadidentity.operations.get
Otorga a los agentes de servicio acceso a un proyecto:
- resourcemanager.projects.getIamPolicy
- resourcemanager.projects.setIamPolicy
Otorga a los agentes de servicio acceso a una carpeta:
- resourcemanager.folders.getIamPolicy
- resourcemanager.folders.setIamPolicy
Otorga a los agentes de servicio acceso a una organización:
- resourcemanager.organizations.getIamPolicy
- resourcemanager.organizations.setIamPolicy

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Identifica los agentes de servicio que deseas crear

Para identificar los agentes de servicio que necesitas crear y los recursos para los que debes crearlos, haz lo siguiente:

Haz una lista de los servicios que usas y sus extremos de API. Para ver todos los servicios disponibles y sus extremos, usa uno de los siguientes métodos:
Console

Ve a la página Biblioteca de APIs en la consola de Google Cloud .

Ir a la biblioteca de la API

El extremo de API es el Nombre del servicio que se indica en la sección Detalles adicionales.
gcloud

El comando gcloud services list enumera todos los servicios disponibles para un proyecto.

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:
- EXPRESSION: Opcional Es una expresión para filtrar los resultados. Por ejemplo, la siguiente expresión filtra todos los servicios cuyos nombres contienen googleapis.com, pero no contienen sandbox:
  name ~ googleapis.com AND name !~ sandbox
  Para obtener una lista de expresiones de filtro, consulta gcloud topic filters.
- LIMIT: Opcional La cantidad máxima de resultados que se mostrarán. El puerto predeterminado es unlimited.
Ejecuta el siguiente comando:
Linux, macOS o Cloud Shell
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
Windows (PowerShell)
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
Windows (cmd.exe)

Nota: Si este comando usa ' para el contenido de comillas, reemplaza estas comillas simples con comillas dobles. Si las comillas están anidadas, usa \" para escapar las comillas internas.
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
La respuesta contiene los nombres y títulos de todos los servicios disponibles. El extremo de API es el valor del campo NAME.
REST

El método services.list de la API de Service Usage enumera todos los servicios disponibles para un proyecto.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- RESOURCE_TYPE: Es el tipo de recurso para el que deseas enumerar los servicios disponibles. Usa projects, folders o organizations.
- RESOURCE_ID: El ID del proyecto, la carpeta o la organización de Google Cloud para el que deseas enumerar los servicios disponibles. Los IDs de proyecto son cadenas alfanuméricas, como my-project. Los IDs de carpeta y organización son numéricos, como 123456789012.
- PAGE_SIZE: Opcional Es la cantidad de servicios que se deben incluir en la respuesta. El valor predeterminado es 50 y el valor máximo es 200. Si la cantidad de servicios es mayor que el tamaño de la página, la respuesta contiene un token de paginación que puedes usar para consultar la siguiente página de resultados.
- NEXT_PAGE_TOKEN: Opcional Es el token de paginación que se mostró en una respuesta anterior de este método. Si se especifica, la lista de servicios comenzará desde el punto en que finalizó la solicitud anterior.
Método HTTP y URL:
GET https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN
Para enviar tu solicitud, expande una de estas opciones:
curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente 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)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente 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
La respuesta contiene los nombres y títulos de todos los servicios disponibles para el recurso. Si la cantidad de servicios disponibles es mayor que el tamaño de la página, la respuesta también contiene un token de paginación.

El extremo de API es el valor del campo name.

Para cada extremo de API que usarás, haz una lista de los recursos en los que necesitas crear los agentes de servicio de ese endpoint:

En la página referencia del agente de servicio, busca cada extremo de API para encontrar todos los agentes de servicio de ese endpoint.

Es posible que algunos extremos no tengan agentes de servicio asociados, por lo que puedes omitir la activación de la creación de agente de servicio para estos extremos.

Para cada uno de los agentes de servicio del extremo, usa la dirección de correo electrónico del agente de servicio para determinar dónde debes crear el agente de servicio.

El marcador de posición en la dirección de correo electrónico de un agente de servicio indica dónde debes crear el agente de servicio:

Marcador de posición	Dónde crear el agente de servicio
`PROJECT_NUMBER`	Cada proyecto en el que usarás el servicio
`FOLDER_NUMBER`	Cada carpeta en la que usarás el servicio
`ORGANIZATION_NUMBER`	Cada organización en la que usarás el servicio

Para cada extremo, registra cada recurso único en el que necesites crear agentes de servicio para ese extremo.

Activa la creación del agente de servicio

Después de saber qué agentes de servicio necesitas crear, puedes pedirle aGoogle Cloud que los cree.

Cuando le pides a Google Cloud que cree agentes de servicio, le proporcionas un servicio y un recurso. Luego, Google Cloud crea todos los agentes de servicio para ese servicio y ese recurso.

Durante este paso, si usas la gcloud CLI o la API de REST, también puedes crear una lista de los roles que se deben otorgar a cada agente de servicio. Usarás esta información para otorgar roles a los agentes de servicio. Si usas Terraform, no necesitas hacer un seguimiento manual de los roles requeridos, ya que puedes hacer referencia a los roles de forma programática.

gcloud

Usa el comando gcloud workload-identity service-agents generate para crear agentes de servicio para cada extremo y recurso que identificaste en Identifica los agentes de servicio que se deben crear.

Cada vez que ejecutes el comando, revisa la respuesta. Para cada rol en la respuesta, registra la dirección de correo electrónico del agente de servicio al que se le debe otorgar el rol. Usarás esta información para otorgar roles a los agentes de servicio.

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

ENDPOINT: Es el extremo de la API para la que deseas crear agentes de servicio, por ejemplo, aiplatform.googleapis.com.
RESOURCE_TYPE: Es el tipo de recurso para el que deseas crear agentes de servicio. Usa project, folder o organization.
RESOURCE_ID: Es el ID numérico del proyecto, la carpeta o la organización para los que deseas crear agentes de servicio. Google CloudPor ejemplo, 123456789012.

Puedes crear agentes de servicio para un recurso a la vez. Si necesitas crear agentes de servicio para varios recursos, ejecuta el comando una vez para cada recurso.

Ejecuta el siguiente comando:

Linux, macOS o 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"

La respuesta contiene una lista de todos los agentes de servicio que se crearon. Para cada agente de servicio, la respuesta enumera el recurso para el que se creó, la dirección de correo electrónico del agente de servicio, el servicio con el que está asociado y el estado del agente de servicio. Si al agente de servicio se le suele otorgar un rol específico, la respuesta también lo incluye.

El rol que se indica no se otorga automáticamente al agente de servicio. Para cada rol en la respuesta, registra la dirección de correo electrónico del agente de servicio al que se le debe otorgar el rol. Usarás esta información para otorgar roles a los agentes de servicio.

A continuación, se muestra un ejemplo truncado de la respuesta para crear agentes de servicio 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

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform. Para obtener más información, consulta la documentación de referencia del proveedor de Terraform.

Usa el recurso google_workload_identity_service_agent para activar la creación de agentes de servicio para cada extremo y recurso que identificaste en Identifica los agentes de servicio que deseas crear.

Por ejemplo, si deseas crear todos los agentes de servicio a nivel del proyecto para BigQuery en el proyecto predeterminado, puedes agregar el siguiente código a tu configuración de 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

Sigue estos pasos para cada extremo en el que necesites crear agentes de servicio:

Crea agentes de servicio para cada recurso que identificaste en Identifica los agentes de servicio que deseas crear:

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- RESOURCE_TYPE: Es el tipo de recurso para el que deseas crear agentes de servicio. Usa projects, folders o organizations.
- RESOURCE_NUMERIC_ID: Es el ID numérico del Google Cloud proyecto, la carpeta o la organización para los que deseas crear agentes de servicio. Por ejemplo, 123456789012.
  
  Puedes crear agentes de servicio para un recurso a la vez. Si necesitas crear agentes de servicio para varios recursos, envía una solicitud para cada recurso.
- ENDPOINT: Es el extremo de la API para la que deseas crear un agente de servicio, por ejemplo, aiplatform.googleapis.com.
Método HTTP y URL:
```
POST https://workloadidentity.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUMERIC_ID/locations/global/serviceProducers/ENDPOINT:generateServiceAgents
```
Para enviar tu solicitud, expande una de estas opciones:
curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente 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)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente 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
```
La respuesta contiene un Operation que indica el estado de tu solicitud. Por ejemplo:
```
{
  "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
}
```
Obtén la respuesta de la operación completada. Para cada rol en la respuesta, registra la dirección de correo electrónico del agente de servicio al que se le debe otorgar el rol. Usarás esta información para otorgar roles a los agentes de servicio.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- OPERATION_NAME: Es el nombre de una operación de generateServiceAgents. Copia este valor del campo name de una respuesta serviceProducers.generateServiceAgents. Por ejemplo: projects/123456789012/locations/global/operations/operation-1775250941060-64e94d1baa76d-1aa958f3-07b2ea9c
- PROJECT_ID: Es el ID de tu proyecto de Google Cloud . Los IDs de proyecto son cadenas alfanuméricas, como my-project.
Método HTTP y URL:
```
GET https://workloadidentity.googleapis.com/v1/OPERATION_NAME
```
Para enviar tu solicitud, expande una de estas opciones:
curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:
```
curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://workloadidentity.googleapis.com/v1/OPERATION_NAME"
```
PowerShell (Windows)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente 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
```
Explorador de APIs (navegador)

Abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Completa los campos obligatorios y haz clic en Ejecutar.

Las operaciones en curso muestran una respuesta como la que se muestra a continuación:
```
{
  "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
}
```
Las operaciones completadas devuelven una respuesta que contiene una lista de los agentes de servicio que se crearon. Para cada agente de servicio, la respuesta enumera el recurso para el que se creó, la dirección de correo electrónico del agente de servicio, el servicio con el que está asociado el agente de servicio y el estado del agente de servicio. Si al agente de servicio se le suele otorgar un rol específico, la respuesta también lo incluye en la lista.

El rol que se indica no se otorga automáticamente al agente de servicio. Para cada rol en la respuesta, registra la dirección de correo electrónico del agente de servicio al que se le debe otorgar el rol. Usarás esta información para otorgar roles a los agentes de servicio.

A continuación, se muestra un ejemplo truncado de la respuesta para crear agentes de servicio 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"
      }
    ]
  }
}
```

Otorga roles a los agentes de servicio

Después de que Google Cloud crea los agentes de servicio necesarios para tus proyectos, carpetas y organizaciones, usas las direcciones de correo electrónico de los agentes de servicio para otorgarles roles.

Si solicitaste Google Cloud que se crearan agentes de servicio, debes otorgarles los roles que suelen recibir automáticamente. De lo contrario, es posible que algunos servicios no funcionen correctamente, ya que los agentes de servicio que se crean a pedido del usuario no reciben roles automáticamente.

Console

Usa la lista de roles y agentes de servicio que creaste en Activa la creación del agente de servicio para identificar a qué agentes de servicio se les deben otorgar roles. Para cada agente de servicio que necesite un rol, haz lo siguiente:

En la consola de Google Cloud , dirígete a la página IAM.

Ir a IAM
Selecciona un proyecto, una carpeta o una organización para los que creaste el agente de servicio.
Haz clic en Otorgar acceso y, luego, ingresa la dirección de correo electrónico del agente de servicio.
Haz clic en Seleccionar un rol y, luego, ingresa el nombre de un rol o permiso para filtrar un rol que se pueda otorgar. Para seguir el principio de privilegio mínimo, elige un rol que incluya solo los permisos que necesita tu principal.
Haz clic en Guardar. Al agente de servicio se le otorga el rol en el recurso.

gcloud

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

RESOURCE_TYPE: Es el tipo de recurso en el que deseas administrar el acceso. Usa projects, resource-manager folders o organizations.
RESOURCE_ID: Tu ID de la organización, carpeta o Google Cloud proyecto. Los IDs de proyecto son alfanuméricos, como my-project. Los IDs de carpeta y organización son numéricos, como 123456789012.
PRINCIPAL: La dirección de correo electrónico del agente de servicio al que deseas otorgar acceso, precedida por serviceAccount:. Por ejemplo, serviceAccount:service-0123456789012@gcp-sa-aiplatform-cc.iam.gserviceaccount.com.
ROLE_NAME: Es el nombre del rol que deseas otorgar al agente de servicio.

Ejecuta el siguiente comando:

Linux, macOS o 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

La respuesta contiene la política de permisos de IAM actualizada.

Terraform

Para otorgar roles a los agentes de servicio, haz lo siguiente:

Para cada recurso google_workload_identity_service_agent, otorga los roles asociados a los agentes de servicio.

Por ejemplo, si deseas otorgar roles a todos los agentes de servicio para el recurso google_workload_identity_service_agent.primary, puedes agregar el siguiente código a tu configuración de 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
}

Ejecuta un comando terraform apply segmentado para el recurso google_workload_identity_service_agent que agregaste en la sección Activa la creación del agente de servicio de esta página.
Por ejemplo, si agregaste un recurso llamado google_workload_identity_service_agent.primary, ejecutarías el siguiente comando:
```
terraform apply target="google_workload_identity_service_agent.primary"
```
La ejecución de este comando garantiza que el recurso google_project_iam_member pueda hacer referencia a los recursos del agente de servicio sin recibir errores de Known After Apply.
Ejecuta el comando terraform plan para tu configuración de Terraform. Este comando muestra el plan de ejecución para otorgar roles a los agentes de servicio. Si el plan de ejecución se ve bien, ejecuta terraform apply para aplicarlo.

REST

Usa la lista de roles y agentes de servicio que creaste en Cómo activar la creación de agentes de servicio para identificar a qué agentes de servicio se les deben otorgar roles. Para otorgar roles a los agentes de servicio, usa el patrón de lectura-modificación-escritura para actualizar la política de permisos del recurso:

Para leer la política de permisos actual, llama a getIamPolicy.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- API_VERSION: La versión de la API que se usará. Para los proyectos y las organizaciones, usa v1. Para las carpetas, usa v2.
- RESOURCE_TYPE: El tipo de recurso cuya política deseas administrar. Usa el valor projects, folders o organizations.
- RESOURCE_ID: Tu ID de proyecto, organización o carpeta de Google Cloud. Los IDs de proyecto son cadenas alfanuméricas, como my-project. Los IDs de carpeta y organización son numéricos, como 123456789012.
- POLICY_VERSION: Es la versión de la política que se mostrará. Las solicitudes deben especificar la versión de política más reciente, que es la versión de política 3. Consulta Especifica una versión de política cuando obtienes una política para obtener más detalles.
Método HTTP y URL:
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy
```
Cuerpo JSON de la solicitud:
```
{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}
```
Para enviar tu solicitud, expande una de estas opciones:
curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:
```
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)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:
```
$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
```
Explorador de APIs (navegador)

Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

La respuesta contiene la política de permisos del recurso. Por ejemplo:
```
{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:my-user@example.com"
      ]
    }
  ]
}
```
Para cada agente de servicio al que quieras otorgarle un rol, crea una vinculación de rol que le otorgue el rol requerido. Por ejemplo, la siguiente vinculación de roles otorga al agente de servicio del código personalizado de AI Platform el rol de agente de servicio del código personalizado de Vertex AI (roles/aiplatform.customCodeServiceAgent):
```
  {
    "role": "roles/aiplatform.customCodeServiceAgent",
    "members": [
      "serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com",
    ]
  }
```
Si la política de permisos ya tiene una vinculación de rol para el rol requerido, agrega el agente de servicio a la lista de members para esa vinculación de rol.
Para escribir la política de permisos actualizada, llama a setIamPolicy.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- API_VERSION: La versión de la API que se usará. Para los proyectos y las organizaciones, usa v1. Para las carpetas, usa v2.
- RESOURCE_TYPE: El tipo de recurso cuya política deseas administrar. Usa el valor projects, folders o organizations.
- RESOURCE_ID: Tu ID de proyecto, organización o carpeta de Google Cloud. Los IDs de proyecto son cadenas alfanuméricas, como my-project. Los IDs de carpeta y organización son numéricos, como 123456789012.
- POLICY: Una representación JSON de la política que deseas establecer. Para obtener más información sobre el formato de una política, consulta la Referencia de políticas.
Método HTTP y URL:
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy
```
Cuerpo JSON de la solicitud:
```
{
  "policy": POLICY
}
```
Para enviar tu solicitud, expande una de estas opciones:
curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:
```
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)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:
```
$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
```
Explorador de APIs (navegador)

Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

La respuesta contiene la política de permisos actualizada:

Nota: Si tratas las políticas como código y las almacenas en un sistema de control de versión, debes almacenar la política que se muestra y no la que enviaste en la solicitud.

¿Qué sigue?

Consulta una lista de todos los agentes de servicio.
Explora otras formas en las que puedes otorgar roles a los principales.
Obtén información para crear cuentas de servicio administradas por el usuario, que pueden actuar como identidades para tus cargas de trabajo.
Obtén más información sobre las prácticas recomendadas para usar Terraform enGoogle Cloud.
Explora todas las Google Cloud muestras de Terraform.

Crea y otorga roles a los agentes de servicio Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Roles obligatorios

Permisos necesarios

Identifica los agentes de servicio que deseas crear

Console

gcloud

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS o Cloud Shell)

PowerShell (Windows)

Activa la creación del agente de servicio

gcloud

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

curl (Linux, macOS o Cloud Shell)

PowerShell (Windows)

curl (Linux, macOS o Cloud Shell)

PowerShell (Windows)

Explorador de APIs (navegador)

Otorga roles a los agentes de servicio

Console

gcloud

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

curl (Linux, macOS o Cloud Shell)

PowerShell (Windows)

Explorador de APIs (navegador)

curl (Linux, macOS o Cloud Shell)

PowerShell (Windows)

Explorador de APIs (navegador)

¿Qué sigue?

Crea y otorga roles a los agentes de servicio