Crea y otorga roles a los agentes de servicio

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

Si es necesario, también puedes pedirle a Google Cloud que cree agentes de servicio a nivel del proyecto, a nivel de la carpeta y a nivel de la organización para un servicio antes de usarlo. Pedirle a Google Cloud que cree agentes de servicio te permite otorgar roles a los agentes de servicio 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. Cuando 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 permisos 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 inconsistencia, 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 el desvío 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 a los agentes de servicio que se crean a pedido del usuario no se les otorgan roles automáticamente.

Antes de comenzar

Enable the Resource Manager API.
Enable the API
Comprende los agentes de servicio.

Roles obligatorios

Activar la creación de agentes de servicio no requiere ningún permiso de IAM. Sin embargo, necesitas permisos de IAM específicos para otras tareas de esta página:

Para obtener el permiso que necesitas a fin de enumerar los servicios disponibles y sus extremos, pídele a tu administrador que te otorgue el rol de IAM visualizador de Service Usage (roles/serviceusage.serviceUsageViewer) en el proyecto, organización o carpeta para la que deseas enumerar los servicios disponibles. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el permiso serviceusage.services.list, que es necesario para enumerar los servicios disponibles y sus extremos.
También puedes obtener este permiso con roles personalizados o con otros roles predefinidos.
Para obtener los permisos que necesitas a fin de otorgar acceso a los agentes de servicio, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto, la carpeta o la organización a los que otorgas acceso:
- 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 otorgar acceso a los agentes de servicio. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:
Permisos necesarios

Se requieren los siguientes permisos para otorgar acceso a los agentes de servicio:
- 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 a nivel del proyecto, de la carpeta y de la organización que debes pedirle a Google Cloud que cree, 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

En la consola de Google Cloud, ve a la página Biblioteca de API.

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 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 los títulos de todos los servicios disponibles. El extremo de la 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 strings 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 la CLI de gcloud 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 la CLI de gcloud. 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 la CLI de gcloud con tu cuenta de usuario mediante 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.
En la página referencia del agente de servicio, busca cada extremo de API.

Si el extremo aparece en la tabla, busca todos los agentes de servicio para ese extremo. Ignora los agentes de servicio cuya dirección de correo electrónico contenga el marcador de posición IDENTIFIER, ya que esos agentes de servicio son para recursos específicos del servicio, no para proyectos, carpetas ni organizaciones.

Para cada agente de servicio a nivel del proyecto, de la carpeta y de la organización, registra lo siguiente:
- Es el formato de la dirección de correo electrónico del agente de servicio.
- El rol que se le otorga al agente de servicio, si corresponde

Activa la creación del agente de servicio

Una vez que sepas qué agentes de servicio debes crear, puedes pedirle a Google 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.

gcloud

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

Revisa las direcciones de correo electrónico del agente de servicio del servicio. Usa los marcadores de posición en las direcciones de correo electrónico para determinar para qué recursos debes crear agentes de servicio:

Marcador de posición	Dónde crear agentes 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

Crea agentes de servicio para cada recurso.

El comando gcloud beta services identity create crea todos los agentes de servicio para la API y el recurso especificados.

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:
- ENDPOINT: Es el extremo de la API para el que deseas crear un agente de servicio, por ejemplo, aiplatform.googleapis.com.
- RESOURCE_TYPE: Es el tipo de recurso para el que deseas crear un agente de servicio. Usa project, folder o organization.
- RESOURCE_ID: El ID del proyecto, la carpeta o la organización de Google Cloud para el que deseas crear un agente de servicio. Los IDs de proyecto son strings alfanuméricas, como my-project. Los IDs de carpeta y organización son numéricos, como 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 beta services identity create --service=ENDPOINT \
    --RESOURCE_TYPE=RESOURCE_ID
```
Windows (PowerShell)
```
gcloud beta services identity create --service=ENDPOINT `
    --RESOURCE_TYPE=RESOURCE_ID
```
Windows (cmd.exe)
```
gcloud beta services identity create --service=ENDPOINT ^
    --RESOURCE_TYPE=RESOURCE_ID
```
La respuesta contiene la dirección de correo electrónico del agente de servicio principal del servicio. Esta dirección de correo electrónico incluye el ID numérico del proyecto, la carpeta o la organización para la que creaste los agentes de servicio.

Si el servicio no tiene un agente de servicio principal, la respuesta no contiene una dirección de correo electrónico.

El siguiente es un ejemplo de una respuesta para un servicio que tiene un agente de servicio principal.
```
Service identity created: service-232332569935@gcp-sa-aiplatform.iam.gserviceaccount.com
```
Opcional: Si corresponde, registra la dirección de correo electrónico del agente de servicio en la respuesta. Esta dirección de correo electrónico identifica el agente de servicio principal del servicio. Puedes usar este identificador para otorgar roles al agente de servicio principal.

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.

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

Marcador de posición	Dónde crear agentes 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

Crea agentes de servicio para cada recurso. Por ejemplo, el siguiente código crea todos los agentes de servicio a nivel de proyecto para AI Platform:

Nota: Terraform solo admite activar la creación de agentes de servicio a nivel del proyecto. Para activar la creación de agentes de servicio a nivel de las carpetas y de la organización, usa Google Cloud CLI o la API de REST.

data "google_project" "default" {
}

# Create all project-level aiplatform.googleapis.com service agents
resource "google_project_service_identity" "default" {
  provider = google-beta

  project = data.google_project.default.project_id
  service = "aiplatform.googleapis.com"
}

REST

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

Marcador de posición	Dónde crear agentes 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

Crea agentes de servicio para cada recurso.

El método services.generateServiceIdentity de la API de Service Usage crea todos los agentes de servicio para la API y el recurso especificados.

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 un agente de servicio. Usa projects, folders o organizations.
- RESOURCE_ID: El ID del proyecto, la carpeta o la organización de Google Cloud para el que deseas crear agentes de servicio. Los IDs de proyecto son strings alfanuméricas, como my-project. Los IDs de carpeta y organización son numéricos, como 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 el que deseas crear un agente de servicio, por ejemplo, aiplatform.googleapis.com.
Método HTTP y URL:
```
POST https://serviceusage.googleapis.com/v1beta1/RESOURCE_TYPE/RESOURCE_ID/services/ENDPOINT:generateServiceIdentity
```
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 la CLI de gcloud 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 la CLI de gcloud. 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://serviceusage.googleapis.com/v1beta1/RESOURCE_TYPE/RESOURCE_ID/services/ENDPOINT:generateServiceIdentity"
```
PowerShell (Windows)

Nota: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante 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://serviceusage.googleapis.com/v1beta1/RESOURCE_TYPE/RESOURCE_ID/services/ENDPOINT:generateServiceIdentity" | Select-Object -Expand Content
```
La respuesta contiene un Operation que indica el estado de tu solicitud. Para comprobar el estado de la operación, usa el método operations.get:

Las operaciones finalizadas contienen la dirección de correo electrónico del agente de servicio principal del servicio. Esta dirección de correo electrónico incluye el ID numérico del proyecto, la carpeta o la organización para la que creaste los agentes de servicio.

Si el servicio no tiene un agente de servicio principal, la respuesta no contiene una dirección de correo electrónico.

El siguiente es un ejemplo de una operación finalizada para un servicio que tiene un agente de servicio primario.
```
{
  "name": "operations/finished.DONE_OPERATION",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.serviceusage.v1beta1.ServiceIdentity",
    "email": "service-232332569935@gcp-sa-aiplatform.iam.gserviceaccount.com",
    "uniqueId": "112245693826560101651"
  }
}
```
Opcional: Si corresponde, registra la dirección de correo electrónico del agente de servicio en la respuesta. Esta dirección de correo electrónico identifica el agente de servicio principal del servicio. Puedes usar este identificador para otorgar roles al agente de servicio principal.

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, puedes usar las direcciones de correo electrónico de los agentes de servicio para otorgarles roles.

Si le pediste a Google Cloud que creara agentes de servicio, debes otorgarles a esos agentes de servicio 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 de un usuario no reciben roles automáticamente.

Para obtener información sobre cómo identificar los roles otorgados automáticamente, consulta Cómo identificar los agentes de servicio que se crearán.

Busca la dirección de correo electrónico del agente de servicio

Para encontrar la dirección de correo electrónico de un agente de servicio, haz lo siguiente:

gcloud

Si aún no lo has hecho, busca el formato de la dirección de correo electrónico del agente de servicio. Este formato se documenta en la referencia del agente de servicio.
Reemplaza los marcadores de posición en la dirección de correo electrónico por el proyecto, la carpeta o el número de organización correspondientes.

Como alternativa, si el agente de servicio es un agente de servicio principal, puedes obtener su dirección de correo electrónico activando la creación del agente de servicio para el servicio. El comando para activar la creación del agente de servicio muestra la dirección de correo electrónico del agente de servicio principal.

Terraform

Si aún no lo has hecho, busca el formato de la dirección de correo electrónico del agente de servicio. Este formato se documenta en la referencia del agente de servicio.
Reemplaza los marcadores de posición en la dirección de correo electrónico por expresiones que hagan referencia al proyecto, la carpeta o el número de organización adecuados.

Por ejemplo, considera la siguiente situación:
- El formato de la dirección de correo electrónico es service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com
- El agente de servicio es para un proyecto etiquetado como default.
En este caso, la dirección de correo electrónico del agente de servicio es la siguiente:
```
service-${data.google_project.default.number}@gcp-sa-aiplatform-cc.iam.gserviceaccount.com
```

Como alternativa, si un agente de servicio es el agente de servicio principal de un servicio, puedes obtener su dirección de correo electrónico del atributo email del recurso google_project_service_identity.

Por ejemplo, si tienes un bloque google_project_service_identity etiquetado como default, puedes obtener la dirección de correo electrónico del agente de servicio principal del servicio con la siguiente expresión:

${google_project_service_identity.default.email}

REST

Si aún no lo has hecho, busca el formato de la dirección de correo electrónico del agente de servicio. Este formato se documenta en la referencia del agente de servicio.
Reemplaza los marcadores de posición en la dirección de correo electrónico por el proyecto, la carpeta o el número de organización correspondientes.

Otorga un rol al agente de servicio

Después de encontrar la dirección de correo electrónico del agente de servicio, puedes otorgarle un rol, al igual que lo harías con cualquier otra principal.

Console

En la consola de Google Cloud, ve a la página IAM.

Ir a IAM
Selecciona un proyecto, una carpeta o una organización.
Haz clic en Otorgar acceso y, luego, ingresa la dirección de correo electrónico del agente de servicio.
Selecciona una función para otorgar de la lista desplegable.
Opcional: Agrega una condición a la función.
Haz clic en Guardar. Al agente de servicio se le otorga el rol en el recurso.

gcloud

El comando add-iam-policy-binding te permite otorgar un rol a una principal con rapidez.

Antes de usar cualquiera de los datos de comando a continuación, realiza 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 y proyecto de Google Cloud. Los ID de proyecto son alfanuméricos, como my-project. Los IDs de carpeta y organización son numéricos, como 123456789012.
PRINCIPAL: Un identificador para la principal o el miembro, que suele tener el siguiente formato: PRINCIPAL_TYPE:ID. Por ejemplo, user:my-user@example.com. Si deseas obtener una lista completa de los valores que PRINCIPAL puede tener, consulta la referencia sobre la vinculación de políticas.

Para el tipo de principal user, el nombre de dominio en el identificador debe ser un dominio de Google Workspace o de Cloud Identity. Para obtener información sobre cómo configurar un dominio de Cloud Identity, consulta la descripción general de Cloud Identity.
ROLE_NAME: El nombre del rol que deseas revocar. Usa uno de los siguientes formatos:
- Roles predefinidos: roles/SERVICE.IDENTIFIER
- Roles personalizados a nivel de proyecto: projects/PROJECT_ID/roles/IDENTIFIER
- Roles personalizados a nivel de la organización: organizations/ORG_ID/roles/IDENTIFIER
Para obtener una lista de roles predefinidos, consulta Cómo entender los roles.
CONDITION: La condición que se agregará a la vinculación de función. Si no quieres agregar una condición, usa el valor None. Para obtener más información sobre las condiciones, consulta la descripción general de las condiciones.

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 IAM actualizada.

Terraform

# Grant the AI Platform Custom Code Service Account the Vertex AI Custom
# Code Service Agent role (roles/aiplatform.customCodeServiceAgent)
resource "google_project_iam_member" "custom_code" {
  project = data.google_project.default.project_id
  role    = "roles/aiplatform.customCodeServiceAgent"
  member  = "serviceAccount:service-${data.google_project.default.number}@gcp-sa-aiplatform-cc.iam.gserviceaccount.com"
}

# Grant the primary aiplatform.googleapis.com service agent (AI Platform
# Service Agent) the Vertex AI Service Agent role
# (roles/aiplatform.serviceAgent)
resource "google_project_iam_member" "primary" {
  project = data.google_project.default.project_id
  role    = "roles/aiplatform.serviceAgent"
  member  = "serviceAccount:${google_project_service_identity.default.email}"
}

REST

Para otorgar un rol con la API de REST, usa el patrón de lectura, modificación y escritura:

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

El método getIamPolicy de la API de Resource Manager obtiene la política de permisos de un proyecto, una carpeta o una organización.

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: El proyecto ID de la carpeta, la organización o el proyecto de Google Cloud. Los ID de proyecto son strings 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 la CLI de gcloud 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 la CLI de gcloud. 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 la CLI de gcloud con tu cuenta de usuario mediante 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:owner@example.com"
      ]
    }
  ]
}
```
Edita la política de permisos del recurso, ya sea mediante el uso de un editor de texto o de manera programática, para agregar o quitar vinculaciones de roles o principales. Por ejemplo, puedes agregar una vinculación de rol nueva, quitar una vinculación de rol existente o agregar o quitar principales de una vinculación de rol existente.
Para escribir la política de permisos actualizada, llama a setIamPolicy().

El método setIamPolicy de la API de Resource Manager establece la política en la solicitud como la política de permisos nueva para el proyecto, la carpeta o la organización.

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: El proyecto ID de la carpeta, la organización o el proyecto de Google Cloud. Los ID de proyecto son strings 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 la CLI de gcloud 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 la CLI de gcloud. 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 la CLI de gcloud con tu cuenta de usuario mediante 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 en Google Cloud.
Explora todos los ejemplos de Terraform de Google Cloud.

Crea y otorga roles a los agentes de servicio

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)

Otorga roles a los agentes de servicio

Busca la dirección de correo electrónico del agente de servicio

gcloud

Terraform

REST

Otorga un rol al agente 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?