Crea y administra funciones personalizadas

En esta página, se describe cómo crear y administrar una función personalizada.

Antes de comenzar

  • Lee Comprende las funciones personalizadas de IAM, que contiene información sobre los permisos necesarios para crear funciones personalizadas y recomendaciones.
  • Si estás usando la utilidad de línea de comandos de gcloud, asegúrate de estar usando la versión 188.0.0 o posterior. Para actualizar gcloud a la versión 188.0.0, ejecuta el siguiente comando: gcloud components update --version 188.0.0

Mira los permisos disponibles para un recurso

Antes de crear una función personalizada, es posible que desees saber qué permisos se pueden aplicar a un recurso. Puedes obtener todos los permisos que se pueden aplicar a un recurso y los recursos que se encuentran debajo de la jerarquía con la herramienta de línea de comandos de gcloud, Cloud Console o la API de IAM. Por ejemplo, puedes obtener todos los permisos que puedes aplicar en una organización y en proyectos en esa organización.

Console

  1. Dirígete a la página Funciones en GCP Console.

    Abrir la página Funciones

  2. Selecciona tu proyecto en el menú desplegable en la parte superior de la página.
  3. Selecciona la casilla de verificación de la función de administrador de un recurso para ver todos los permisos que puedes aplicar a ese recurso. Por ejemplo, cuando seleccionas la función Administrador de instancia de procesamiento, el panel del lado derecho muestra todos los permisos que puedes aplicar en una instancia de Compute Engine.

COMANDO DE GCLOUD

Usa el comando gcloud iam list-testable-permissions para obtener una lista de permisos que se pueden aplicar a un recurso de destino. Los permisos mostrados son los que se pueden usar para crear una función personalizada en este recurso y en cualquiera que se encuentre debajo en la jerarquía.

En el siguiente ejemplo, se muestra cómo enumerar los permisos comprobables para un recurso de proyecto:

gcloud iam list-testable-permissions [PROJECT-ID]

[PROJECT-ID] es el ID del proyecto en forma de un nombre de recurso completo: //cloudresourcemanager.googleapis.com/projects/PROJECT-ID, como //cloudresourcemanager.googleapis.com/projects/my-project-id.

El comando list-testable-permissions puede mostrar cientos de resultados. Para limitar los resultados, también puedes especificar una expresión de filtros. A continuación, se muestra un ejemplo truncado de posibles resultados:

---
name: appengine.applications.create
stage: GA
---
customRolesSupportLevel: TESTING
name: appengine.applications.disable
stage: GA
---
name: appengine.applications.get
stage: GA
---
customRolesSupportLevel: NOT_SUPPORTED
name: appengine.applications.list
onlyInPredefinedRoles: true
stage: GA
---
name: appengine.applications.update
stage: GA
---
name: appengine.instances.delete
stage: GA
---
name: appengine.instances.get
stage: GA
---

Ten en cuenta que cada permiso indica si se admite en una función personalizada. Para obtener una lista completa de permisos compatibles y no compatibles, consulta Compatibilidad para permisos de funciones personalizadas.

API de REST

QueryTestablePermissions muestra todos los permisos que se pueden aplicar a un recurso. Los permisos mostrados son los que se pueden usar para crear una función personalizada en este recurso y en cualquiera que se encuentre debajo en la jerarquía. La única entrada requerida para esta solicitud es el nombre completo del recurso, como //cloudresourcemanager.googleapis.com/projects/my-project.

De forma opcional, el emisor puede proporcionar asistencia para la paginación si el recurso tiene una lista larga de permisos.

Ejemplo

full_resource_name: '//cloudresourcemanager.googleapis.com/projects/my-project'`

Códigos de error

Código de error Mensaje de estado
INVALID_ARGUMENT debe estar entre 0 y 100
INVALID_ARGUMENT Codificación de token de paginación no válida
INVALID_ARGUMENT Token de paginación no válido
INVALID_ARGUMENT El token de paginación no es para el contenedor especificado
INVALID_ARGUMENT Punto de partida no válido en el token de paginación
INVALID_ARGUMENT Cookie de token de paginación no válida
INVALID_ARGUMENT Token de paginación vencido
INVALID_ARGUMENT {full_resource_name} debe estar especificado
INVALID_ARGUMENT {full_resource_name}, no concuerda con //[a-z0-9.-]/.a-z0-9.-]/.

C#

Antes de probar esta muestra, sigue las instrucciones de configuración de C# en el Inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.

public static IList<Permission> QueryTestablePermissions(
    string resource)
{
    var request = new QueryTestablePermissionsRequest
    {
        FullResourceName = resource
    };
    var permissions = s_service.Permissions.QueryTestablePermissions(
        request).Execute().Permissions;

    foreach (var p in permissions)
    {
        Console.WriteLine(p.Name);
    }
    return permissions;
}

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

def query_testable_permissions(resource):
    """Lists valid permissions for a resource."""

    # pylint: disable=no-member
    permissions = service.permissions().queryTestablePermissions(body={
        'fullResourceName': resource
    }).execute()['permissions']
    for p in permissions:
        print(p['name'])

Obtén los metadatos de la función

Antes de crear una función personalizada, es posible que desees obtener los metadatos para las funciones predefinidas y personalizadas. Los metadatos de función incluyen el ID de función y los permisos contenidos en la función. Puedes ver los metadatos con Google Cloud Platform Console o la API de IAM.

Para ver los metadatos de función, usa uno de los siguientes métodos:

Console

  1. Dirígete a la página Funciones en GCP Console.

    Abrir la página Funciones

  2. Selecciona tu organización o proyecto de la lista desplegable en la parte superior de la página.
  3. Selecciona la casilla de verificación de una o más funciones para ver los permisos de función. El panel lateral derecho muestra los permisos contenidos en las funciones, si los hay.

Los íconos junto a la función indican si es una función personalizada (ícono "fábrica") o una función predefinida (ícono hexágono).

Íconos de funciones

Si deseas buscar todas las funciones que incluyen un permiso específico, escribe el nombre del permiso en el cuadro Filtro en la parte superior de la lista de funciones.

COMANDO DE GCLOUD

Usa el comando gcloud iam roles describe para ver los metadatos de funciones predefinidas y funciones personalizadas.

Para ver los metadatos de una función predefinida, ejecuta el siguiente comando de gcloud:

gcloud iam roles describe [ROLE-NAME]

[ROLE-NAME] es el nombre de la función, como roles/viewer.

En el siguiente ejemplo, se demuestra la salida del comando describe cuando se ejecuta en la función predefinida roles/iam.roleViewer:

gcloud iam roles describe roles/iam.roleViewer

description: Read access to all custom roles in the project.
etag: AA==
includedPermissions:
- iam.roles.get
- iam.roles.list
- resourcemanager.projects.get
- resourcemanager.projects.getIamPolicy
name: roles/iam.roleViewer
stage: GA
title: Role Viewer

Para ver los metadatos de una función personalizada, primero determina si esta se creó a nivel de organización o de proyecto. Si la función personalizada se creó en el nivel de la organización, ejecuta el siguiente comando de gcloud:

gcloud iam roles describe --organization [ORGANIZATION-ID] [ROLE-NAME]

[ORGANIZATION-ID] es el ID de la organización en forma de: 1234567. [ROLE-NAME] es el nombre de la función personalizada, como myCustomRole.

Para ver los metadatos de una función personalizada a nivel de proyecto, ejecuta el siguiente comando de gcloud:

gcloud iam roles describe --project [PROJECT-ID] [ROLE-NAME]

[PROJECT-ID] es el ID del proyecto, como my-project-id. [ROLE-NAME] es el nombre de la función personalizada, como myCustomRole.

Si quieres obtener más información, consulta la documentación de referencia para la descripción de funciones de gcloud iam.

API de REST

Si conoces el nombre de la función que deseas ver, usa el método roles.get para obtener una función personalizada. Si no conoces el nombre de la función, usa el método roles.list para enumerar todas las funciones personalizadas en una organización o en un proyecto.

Para llamar a GetRole(), establece el siguiente campo en GetRoleRequest:

  • Nombre de la función, como roles/{ROLE-NAME} o organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}

Para llamar a ListRoles(), establece el siguiente campo en ListRolesRequest:

  • El superior para el que deseas obtener todas las funciones personalizadas, como organizations/{ORGANIZATION-ID} o projects/{PROJECT-ID}

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para obtener la función en {path}
NOT_FOUND No se encontró la función llamada {role}.
INVALID_ARGUMENT El nombre de la función deber estar como roles/{role}o organizations/{organization-id}/roles/{role}.
PERMISSION_DENIED No tienes permiso para enumerar funciones en {path}.
INVALID_ARGUMENT La {path} superior no es válida. El superior debe estar como organizations/{organization-id} o vacío.
INVALID_ARGUMENT La vista de funciones no es válida.

C#

Antes de probar esta muestra, sigue las instrucciones de configuración de C# en el Inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.

public static Role GetRole(string name)
{
    Role role = s_service.Roles.Get(name).Execute();
    Console.WriteLine(role.Name);
    Console.WriteLine(String.Join(", ", role.IncludedPermissions));
    return role;
}

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

def get_role(name):
    """Gets a role."""

    # pylint: disable=no-member
    role = service.roles().get(name=name).execute()
    print(role['name'])
    for permission in role['includedPermissions']:
        print(permission)

Crea una función personalizada

Para crear una función personalizada, un emisor debe poseer el permiso iam.roles.create. De forma predeterminada, el propietario de un proyecto o una organización tiene este permiso y puede crear y administrar funciones personalizadas.

A los usuarios que no son propietarios, incluidos los administradores de la organización, se les debe asignar la función de administrador de funciones organizativas o la función de administrador de funciones IAM.

Console

Para crear una nueva función personalizada desde cero:

  1. Dirígete a la página Funciones en GCP Console.

    Abrir la página Funciones

  2. Selecciona tu organización del menú desplegable Organización.
  3. Haz clic en Crear función.
  4. Ingresa un Nombre, un Título y una Descripción para la función.
  5. Haz clic en Agregar permisos.
  6. Selecciona los permisos que desees incluir en la función y haz clic en Agregar permisos. Usa los menús desplegables Todos los servicios y Todos los tipos para filtrar y seleccionar permisos por servicios y tipos.

Crea una función personalizada con base en una función seleccionada existente:

  1. Dirígete a la página Funciones en GCP Console.

    Abrir la página Funciones

  2. Selecciona tu organización del menú desplegable Organización.
  3. Selecciona las funciones en las que deseas basar la nueva función personalizada.
  4. Haz clic en Crear función de selección.
  5. Ingresa un Nombre, un Título y una Descripción para la función.
  6. Desmarca los permisos que deseas excluir de la función.
  7. Haz clic en Agregar permisos para incluir cualquier permiso.
  8. Haz clic en Crear.

COMANDO DE GCLOUD

Usa el comando gcloud iam roles create para crear funciones personalizadas nuevas. Puedes utilizar este comando de dos maneras:

  • Con un archivo YAML que contiene la definición de la función
  • Con marcas para especificar la definición de la función

Cuando crees una función personalizada, debes especificar si se aplica a nivel de la organización o a nivel del proyecto mediante las marcas --organization [ORGANIZATION-ID] o --project [PROJECT-ID]. En cada uno de los siguientes ejemplos, se crea una función personalizada a nivel del proyecto.

Para crear una función personalizada con un archivo YAML, haz lo siguiente:

Crea un archivo YAML que contenga la definición de tu función personalizada. El archivo debe estar estructurado de la siguiente manera:

title: [ROLE-TITLE]
description: [ROLE-DESCRIPTION]
stage: [LAUNCH-STAGE]
includedPermissions:
- [PERMISSION-1]
- [PERMISSION-2]

Cada uno de los valores de marcador de posición se describe a continuación:

  • [ROLE-TITLE] es un título descriptivo para la función, como "Role Viewer".
  • [ROLE-DESCRIPTION] es una descripción corta sobre la función, como "My custom role description".
  • [LAUNCH-STAGE] indica la etapa de una función en el ciclo de vida de lanzamiento, como ALPHA, BETA o GA.
  • includedPermissions especifica la lista de uno o más permisos para incluir en la función personalizada, como - iam.roles.get.

Guarda el archivo YAML y, luego ejecuta el siguiente comando de gcloud:

gcloud iam roles create [ROLE-ID] --project [PROJECT-ID] \
--file [YAML_FILE-PATH]

Cada uno de los valores de marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id.
  • [YAML_FILE-PATH] es la ruta a la ubicación de tu archivo YAML que contiene la definición de función personalizada.

En el siguiente archivo YAML de ejemplo, se muestra cómo crear una definición de función:

title: "Role Viewer"
description: "My custom role description."
stage: "ALPHA"
includedPermissions:
- iam.roles.get
- iam.roles.list

En el siguiente ejemplo, se muestra cómo crear una función mediante el archivo YAML:

gcloud iam roles create viewer --project my-project-id \
--file my-role-definition.yaml

Si la función se creó con éxito, se muestra la siguiente respuesta:

Created role [viewer].
description: My custom role description.
etag: BwVkBX0sQD0=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

Para crear una función personalizada mediante marcas, haz lo siguiente:

Ejecuta el siguiente comando de gcloud:

gcloud iam roles create [ROLE-ID] --project [PROJECT-ID] \
--title [ROLE-TITLE] --description [ROLE-DESCRIPTION] \
--permissions [PERMISSIONS-LIST] --stage [LAUNCH-STAGE]

Cada uno de los valores de marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id.
  • [ROLE-TITLE] es un título descriptivo para la función, como Role Viewer.
  • [ROLE-DESCRIPTION] es una descripción corta sobre la función, como "My custom role description.".
  • [PERMISSIONS-LIST] contiene una lista de permisos separada por comas que deseas incluir en la función personalizada. Por ejemplo: iam.roles.get,iam.roles.list.
  • [LAUNCH-STAGE] indica la etapa de una función en el ciclo de vida de lanzamiento, como ALPHA, BETA o GA.

En el siguiente ejemplo, se muestra cómo crear una función con marcas:

gcloud iam roles create viewer --project my-project-id \
--title "Role Viewer" --description "My custom role description." \
--permissions iam.roles.get,iam.roles.list --stage ALPHA

Si la función se creó con éxito, se muestra la siguiente respuesta:

Created role [viewer].
description: My custom role description.
etag: BwVkBX0sQD0=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

API de REST

Usa el método create para crear una nueva función personalizada.

Establece los siguientes parámetros requeridos en la solicitud:

  • El role_id que deseas usar para la función personalizada nueva, como appengine.myCustomStorageAuditor.
  • Una descripción de la función personalizada, como "Esta función otorga acceso a los recursos de almacenamiento de la lista, su capacidad y las políticas de acceso".
  • Una lista de los permisos que deseas asociar con esta función.
  • Ten en cuenta que establecer el campo de nombre en la función dará como resultado un error.

Recomendamos que también establezcas los siguientes parámetros opcionales:

  • Título para la función personalizada, como "Ejemplo de editor de funciones personalizadas".
  • Establece un valor para stage, como GA.

stage toma los siguientes valores: ALPHA, BETA, GA, DEPRECATED o DISABLED.

Algunas funciones predefinidas contienen permisos obsoletos o permisos que, de otra manera, no están permitidos en las funciones personalizadas. La creación de una función personalizada basada en una función predefinida que contenga permisos obsoletos o restringidos fallará.

Ejemplo

parent: '[PARENT-NAME]'
role_id: '[ROLE-ID]'
role {
    name: ''
    title: '[ROLE-TITLE]'
    description: '[ROLE-DESCRIPTION]'
    included_permissions: '[PERMISSION]'
    included_permissions: '[PERMISSION]'
})",

Donde:

  • [PARENT-NAME] es el nombre de la organización en la que estás creando la función personalizada, por ejemplo, organizations/0000000000000001 o el ID del proyecto en el que estás creando la función personalizada, por ejemplo, projects/my-project.
  • [ROLE-ID] es el ID de la función personalizada. Por ejemplo, appengine.myCustomStorageAuditor.
  • [ROLE-TITLE] es el título para la función. Por ejemplo, Storage Auditor.
  • [ROLE-DESCRIPTION] es la descripción de lo que hace la función.
  • [PERMISSION] es el permiso que deseas incluir en la función personalizada.

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para crear una función en {parent}.
ALREADY_EXISTS Ya existe una función llamada {role-id} en {parent}.
INVALID_ARGUMENT El superior {parent} no es válido El superior debe estar como organizations/{organization-id}.
INVALID_ARGUMENT El role_id {role-id} no es válido. No concuerda con {pattern}.
INVALID_ARGUMENT La cantidad de permisos en la función es mayor que el máximo de {max}.
INVALID_ARGUMENT La role.stage {stage} no es válida.

C#

Antes de probar esta muestra, sigue las instrucciones de configuración de C# en el Inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.

public static Role CreateRole(string name, string project,
    string title, string description, IList<string> permissions,
    string stage)
{
    Role role = new Role
    {
        Title = title,
        Description = description,
        IncludedPermissions = permissions,
        Stage = stage
    };
    var request = new CreateRoleRequest
    {
        Role = role,
        RoleId = name
    };

    role = s_service.Projects.Roles.Create(request,
        "projects/" + project).Execute();

    Console.WriteLine("Created role: " + role.Name);
    return role;
}

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

def create_role(name, project, title, description, permissions, stage):
    """Creates a role."""

    # pylint: disable=no-member
    role = service.projects().roles().create(
        parent='projects/' + project,
        body={
            'roleId': name,
            'role': {
                'title': title,
                'description': description,
                'includedPermissions': permissions,
                'stage': stage
            }
        }).execute()

    print('Created role: ' + role['name'])
    return role

Edita una función personalizada existente

Leer, modificar, escribir

Un patrón común para actualizar los metadatos de un recurso, como una función personalizada, es leer su estado actual, actualizar los datos de forma local y, luego, enviar los datos modificados para su escritura. Este patrón podría causar un conflicto si dos o más procesos independientes intentan la secuencia en simultáneo. Por ejemplo, si dos propietarios de un proyecto intentan realizar cambios conflictivos en una función al mismo tiempo, algunos cambios podrían fallar. Cloud IAM resuelve este problema mediante una propiedad etag en funciones personalizadas. Esta propiedad se usa para verificar si la función personalizada cambió desde la última solicitud. Cuando realizas una solicitud a Cloud IAM con un valor de etag, Cloud IAM compara el valor de etag en la solicitud con el valor de etag existente asociado con la función personalizada. Solo escribe el cambio si los valores de etag coinciden.

Cuando actualices una función, primero obtén la función con roles.get(), actualiza la función y, luego, escribe la función actualizada con roles.patch(). Usa el valor de etag cuando establezcas la función solo si la función correspondiente en roles.get() contiene un valor de etag.

Console

  1. Dirígete a la página Funciones en GCP Console.

    Abrir la página Funciones

  2. Selecciona tu organización del menú desplegable Organización.
  3. Haz clic en una función personalizada.
  4. Haz clic en Editar función.
  5. Haz clic en Agregar permisos para agregar permisos nuevos a la función.
  6. Desmarca permisos para quitarlos de la función.
  7. Haz clic en Actualizar para guardar la función editada.

COMANDO DE GCLOUD

Usa el comando gcloud iam roles update para actualizar las funciones personalizadas. Puedes utilizar este comando de dos maneras:

  • Con un archivo YAML que contiene la definición de función actualizada
  • Con marcas para especificar la definición de función actualizada

Cuando actualices una función personalizada, debes especificar si aplica al nivel de la organización o al nivel del proyecto mediante las marcas --organization [ORGANIZATION-ID] o --project [PROJECT-ID]. En cada uno de los siguientes ejemplos, se crea una función personalizada a nivel del proyecto.

Para actualizar una función personalizada con un archivo YAML, haz lo siguiente:

Ejecuta el siguiente comando de gcloud a fin de obtener la definición actual para la función:

gcloud iam roles describe [ROLE-ID] --project [PROJECT-ID]

Cada uno de los valores de marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función a actualizar, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id.

El comando describe muestra la definición de la función y, además, incluye un valor etag que identifica de forma única la versión actual de la función. El valor etag debe proporcionarse en la definición de función actualizada para garantizar que cualquier cambio de función simultáneo no se sobrescriba.

El comando describe muestra el siguiente resultado:

description: [ROLE-DESCRIPTION]
etag: [ETAG-VALUE]
includedPermissions:
- [PERMISSION-1]
- [PERMISSION-2]
name: [ROLE-ID]
stage: [LAUNCH-STAGE]
title: [ROLE-TITLE]

Cada uno de los valores de marcador de posición se describe a continuación:

  • [ROLE-DESCRIPTION] es una descripción corta sobre la función, como "My custom role description".
  • [ETAG-VALUE] es el identificador único para la versión actual de la función, como BwVkBkbfr70=.
  • includedPermissions especifica la lista de uno o más permisos para incluir en la función personalizada, como - iam.roles.get.
  • [ROLE-ID] es el ID jerárquico para la función, el cual depende de si se creó a nivel de organizacón o proyecto. Por ejemplo: projects/my-project-id/roles/viewer
  • [LAUNCH-STAGE] indica la etapa de una función en el ciclo de vida de lanzamiento, como ALPHA, BETA o GA.
  • [ROLE-TITLE] es un título descriptivo para la función, como "Role Viewer".

Para actualizar la función, incluye la definición de función generada en un archivo YAML o actualiza el archivo original YAML con el valor etag generado.

Considera el siguiente archivo YAML de ejemplo, que contiene el resultado del comando describe y agrega dos permisos de Cloud Storage:

description: My custom role description.
etag: BwVkBkbfr70=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

Guarda el archivo YAML y, luego ejecuta el siguiente comando de gcloud:

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--file [YAML_FILE-PATH]

Cada uno de los valores de marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función a actualizar, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id.
  • [YAML_FILE-PATH] es la ruta a la ubicación de tu archivo YAML que contiene la definición de función personalizada actualizada.

En el siguiente ejemplo, se muestra cómo actualizar una función con el archivo YAML:

gcloud iam roles update viewer --project my-project-id \
--file my-role-definition.yaml

Si la función se actualizó con éxito, se muestra la siguiente respuesta:

description: My custom role description.
etag: BwVkBwDN0lg=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

Para actualizar una función personalizada mediante marcas, haz lo siguiente:

Cada parte de la definición de una función se puede actualizar con una marca correspondiente. Consulta el tema actualización de funciones de gcloud iam para obtener una lista de todas las marcas posibles.

Puedes usar las siguientes marcas para agregar o quitar permisos:

  • --add-permissions [PERMISSIONS]: agrega uno o más permisos separados por comas a la función.
  • --remove-permissions [PERMISSIONS]: quita uno o más permisos separados por comas de la función.

De manera alternativa, puedes simplemente especificar los permisos nuevos con la marca --permissions [PERMISSIONS] y proporcionar una lista de permisos separados por comas para reemplazar la lista de permisos existente.

Para actualizar otros aspectos de la definición de función, ejecuta el siguiente comando de gcloud:

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--title [ROLE-TITLE] --description [ROLE-DESCRIPTION] \
--stage [LAUNCH-STAGE]

Cada uno de los valores de marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id.
  • [ROLE-TITLE] es un título descriptivo para la función, como Role Viewer.
  • [ROLE-DESCRIPTION] es una descripción corta sobre la función, como "My custom role description.".
  • [LAUNCH-STAGE] indica la etapa de una función en el ciclo de vida de lanzamiento, como ALPHA, BETA o GA.

En el siguiente ejemplo, se muestra cómo agregar permisos a una función con marcas:

gcloud iam roles update viewer --project my-project-id \
--add-permissions storage.buckets.get,storage.buckets.list

Si la función se actualizó con éxito, se muestra la siguiente respuesta:

description: My custom role description.
etag: BwVkBwDN0lg=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

API de REST

Usa el método Role UpdateRole(UpdateRoleRequest) para editar una función personalizada existente.

Si conoces el ID de función de la función personalizada que deseas editar, obtén la función con el método roles.get() y luego actualízala con roles.patch().

Si no conoces el ID de función de la función personalizada que deseas editar, enumera todas las funciones con ListRoles() para identificar la función. roles.list() muestra una lista de todas las funciones que hacen referencia al recurso. Luego, actualiza la función con roles.patch().

Establece el siguiente parámetro obligatorio en roles.patch():

  • Nombre de la función, como organizations/{ORGANIZATION-ID}/roles/{ROLE-ID}.

De manera opcional, establece el campo update_mask para especificar los campos que se pueden actualizar en el futuro.

Ejemplo

name: '[ROLE-NAME]'
role {
    name: '[ROLE-NAME]'
    title: '[ROLE-TITLE]'`
    description: '[ROLE-DESCRIPTION]'
    included_permissions: '[PERMISSION]'
    included_permissions: '[PERMISSION]'
})"

Donde:

  • [ROLE-NAME] es el nombre de la función. Por ejemplo, organizations/123456/roles/appengine.customRoleEditor. Puede estar en la forma de roles/{ROLE-NAME}, organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME} o projects/{PROJECT-ID}/roles/{ROLE-NAME}

  • [ROLE-TITLE] es el título para la función. Por ejemplo: New custom editor.

  • [ROLE-DESCRIPTION] es una descripción para la función. Por ejemplo: "Mi nueva descripción larga de editor".

  • [PERMISSION] es el permiso que deseas incluir en la función. Por ejemplo: storage.objects.update.

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para actualizar la función.
INVALID_ARGUMENT No se pueden actualizar las funciones predefinidas.
INVALID_ARGUMENT El nombre en la solicitud ([ROLE-NAME]) y el nombre en la función ([ROLE-NAME]) deben coincidir.
INVALID_ARGUMENT El permiso [PERMISSION] no es válido.
ABORTED Hubo cambios de política simultáneos dado que el etag no coincidió. Vuelve a intentar todo el proceso de leer, modificar, escribir con retirada exponencial.

Algunas funciones predefinidas contienen permisos obsoletos o permisos que, de otra manera, no están permitidos en las funciones personalizadas. La creación de una función personalizada basada en una función predefinida que contenga permisos obsoletos o restringidos fallará.

C#

Antes de probar esta muestra, sigue las instrucciones de configuración de C# en el Inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.

public static Role EditRole(string name, string project,
    string newTitle, string newDescription,
    IList<string> newPermissions, string newStage)
{
    string resource = $"projects/{project}/roles/{name}";

    Role role = s_service.Projects.Roles.Get(resource).Execute();

    role.Title = newTitle;
    role.Description = newDescription;
    role.IncludedPermissions = newPermissions;
    role.Stage = newStage;

    role = s_service.Projects.Roles.Patch(role, resource).Execute();
    Console.WriteLine("Updated role: " + role.Name);
    return role;
}

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

def edit_role(name, project, title, description, permissions, stage):
    """Creates a role."""

    # pylint: disable=no-member
    role = service.projects().roles().patch(
        name='projects/' + project + '/roles/' + name,
        body={
            'title': title,
            'description': description,
            'includedPermissions': permissions,
            'stage': stage
        }).execute()

    print('Updated role: ' + role['name'])
    return role

Inhabilita una función personalizada

Puedes inhabilitar una función personalizada. Cuando una función está inhabilitada, todos los enlaces de políticas relacionados con ella se desactivan, lo que significa que no se concederán los permisos en la función, incluso si concedes la función a un usuario.

Console

  1. Dirígete a la página Funciones en GCP Console.

    Abrir la página Funciones

  2. Haz clic en el menú desplegable "Seleccionar un proyecto" en la parte superior de la página.
  3. Selecciona tu organización o proyecto.
  4. Selecciona una función personalizada y haz clic en Inhabilitar.

COMANDO DE GCLOUD

Usa el comando gcloud iam roles update para inhabilitar una función personalizada y establece su etapa de lanzamiento como DISABLED. Como se describe en la pestaña gcloud de la sección Editar una función personalizada existente, puedes actualizar una función personalizada existente de las dos maneras siguientes:

  • Con un archivo YAML que contiene la definición de función actualizada
  • Con marcas para especificar la definición de función actualizada

La forma más fácil de inhabilitar una función personalizada existente es usar la marca --stage y establecerla como DISABLED. Ejecuta el siguiente comando de gcloud:

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--stage DISABLED

Cada uno de los valores de marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id. También puedes usar la marca --organization [ORGANIZATION-ID] si la función se creó a nivel de la organización, como 1234567.

En el siguiente ejemplo, se muestra cómo inhabilitar una función:

gcloud iam roles update viewer --project my-project-id \
--stage DISABLED

Si la función se actualizó con éxito, se muestra la siguiente respuesta:

description: My custom role description.
etag: BwVkB5NLIQw=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: DISABLED
title: Role Viewer

API de REST

Usa el método roles.patch() para inhabilitar una función personalizada.

Si conoces el ID de función de la función personalizada que deseas inhabilitar, obtén la función con el método roles.get(). Cambia la propiedad stage de la función a DISABLED y, luego, llama al método roles.patch() para actualizar la función.

Si no conoces el ID de función de la función personalizada que deseas inhabilitar, enumera todas las funciones mediante roles.list() para identificar la función. roles.list() muestra una lista de todas las funciones que hacen referencia al recurso. Identifica la función que deseas inhabilitar, cambia su propiedad rolelaunchstage a DISABLED, y, luego, llama al método roles.patch() para actualizar la función.

Para inhabilitar una función, establece los siguientes campos:

  • En el nombre, establece el nombre completo de la función, organizations/{organization-id}/roles/{role}.
  • En Role, establece stage a DISABLED.
  • Establece update_mask a “paths: stage”.

Para volver a habilitar la función, sigue el mismo proceso anterior como inhabilitar la función, pero establece la propiedad stage de la función a ALPHA, BETA o GA.

Ejemplo

name: 'organizations/123456/roles/appengine.customRoleEditor'
role {
    name: 'organizations/123456/roles/appengine.customRoleEditor'`
    stage: 'DISABLED'
}
update_mask {
    paths:  stage
}

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para actualizar la función.
INVALID_ARGUMENT No se pueden actualizar las funciones seleccionadas.
INVALID_ARGUMENT El nombre en la solicitud ([ROLE-NAME]) y el nombre en la función ([ROLE-NAME]) deben coincidir.
INVALID_ARGUMENT El permiso [PERMISSION] no es válido.
ABORTED Hubo cambios de política simultáneos. Vuelve a intentar el proceso completo de leer, modificar, escribir con retirada exponencial.

C#

Antes de probar esta muestra, sigue las instrucciones de configuración de C# en el Inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.

public static Role DisableRole(string name, string project)
{
    string resource = $"projects/{project}/roles/{name}";

    Role role = s_service.Projects.Roles.Get(resource).Execute();
    role.Stage = "DISABLED";

    role = s_service.Projects.Roles.Patch(new Role
    {
    }, $"projects/{project}/roles/{name}").Execute();

    Console.WriteLine("Disabled role: " + role.Name);
    return role;
}

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

def disable_role(name, project):
    """Disables a role."""

    # pylint: disable=no-member
    role = service.projects().roles().patch(
        name='projects/' + project + '/roles/' + name,
        body={
            'stage': 'DISABLED'
        }).execute()

    print('Disabled role: ' + role['name'])
    return role

Enumera las funciones

Console

  1. Dirígete a la página Funciones en GCP Console.

    Abrir la página Funciones


    Todas las funciones personalizadas para el proyecto se enumeran en la página.

COMANDO DE GCLOUD

Usa el comando gcloud iam roles list a fin de enumerar las funciones personalizadas y las funciones predefinidas para una organización o proyecto.

Ejecuta el siguiente comando de gcloud para enumerar funciones personalizadas y especifica las funciones a nivel de proyecto o a nivel de organización:

gcloud iam roles list --project [PROJECT-ID]

[PROJECT-ID] es el nombre del proyecto, como my-project-id. También puedes usar la marca --organization [ORGANIZATION-ID] si la función se creó a nivel de la organización, como 1234567.

Para enumerar funciones borradas, también puedes especificar la marca --show-deleted.

Ejecuta el siguiente comando de gcloud para enumerar funciones predefinidas:

gcloud iam roles list

API de REST

El método roles.list() se puede usar para enumerar todas las funciones personalizadas definidas en una organización o en un proyecto, también se puede usar para enumerar las funciones predefinidas si estableces el campo superior en la solicitud como "".

Para llamar a roles.list(), establece el siguiente campo en la solicitud:

  • El superior que deseas usar para obtener todas las funciones personalizadas, como los siguientes
    • projects/{PROJECT-ID}
    • organizations/{ORGANIZATION-ID}

Si deseas que el resultado contenga los permisos de cada función, establece el campo view a RoleView::FULL.

Si deseas que el resultado contenga las funciones que se borraron recientemente, establece el campo show_deleted a verdadero.

Si deseas enumerar todas las funciones seleccionadas, establece el superior a '' (string vacía).

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para enumerar funciones en {path}.
INVALID_ARGUMENT El superior {path} no es válido. El superior debe estar como organizations/{organization-id}, projects/{project-id} o vacío.
INVALID_ARGUMENT La vista de funciones no es válida.

C#

Antes de probar esta muestra, sigue las instrucciones de configuración de C# en el Inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.

public static IList<Role> ListRoles(string projectId)
{
    ListRolesResponse response = s_service.Projects.Roles
        .List("projects/" + projectId).Execute();
    foreach (var role in response?.Roles)
    {
        Console.WriteLine(role.Name);
    }
    return response.Roles;
}

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

def list_roles(project_id):
    """Lists roles."""

    # pylint: disable=no-member
    roles = service.roles().list(
        parent='projects/' + project_id).execute()['roles']
    for role in roles:
        print(role['name'])

Borra una función personalizada

Console

  1. Dirígete a la página Funciones en GCP Console.

    Abrir la página Funciones

  2. Selecciona la función que deseas borrar y haz clic en el ícono de la papelera en la parte superior de la página.

COMANDO DE GCLOUD

Usa el comando gcloud iam roles delete para borrar una función personalizada. La función está suspendida y no se puede usar para crear nuevos enlaces de políticas de IAM.

Ejecuta el siguiente comando de gcloud para borrar una función personalizada:

gcloud iam roles delete [ROLE-ID] --project [PROJECT-ID]

Cada uno de los valores de marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id. También puedes usar la marca --organization [ORGANIZATION-ID] si la función se creó a nivel de la organización, como 1234567.

La función no se incluirá en gcloud iam roles list, a menos que se incluya la marca --show_deleted. Las funciones borradas se indican mediante el bloque deleted: true en una respuesta de list, como:

---
deleted: true
description: My custom role description.
etag: BwVkB5NLIQw=
name: projects/my-project-id/roles/viewer
title: Role Viewer
---

API de REST

roles.delete borra una función. La función está suspendida y no se puede usar para crear nuevos enlaces de políticas de IAM.

El name puede estar en los siguientes formatos

  • organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}
  • projects/{PROJECT-ID}/roles/{ROLE-NAME}

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para borrar la función a {path}.
FAILED_PRECONDITION No puedes borrar la función {ROLE-NAME} porque ya se borró.
FAILED_PRECONDITION No puedes borrar una función {ROLE-NAME} que está reservada.
INVALID_ARGUMENT Las funciones seleccionadas no pueden estar en un estado borrado.

C#

Antes de probar esta muestra, sigue las instrucciones de configuración de C# en el Inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.

public static void DeleteRole(string name, string project)
{
    s_service.Projects.Roles.Delete(
        $"projects/{project}/roles/{name}").Execute();
    Console.WriteLine("Deleted role: " + name);
}

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

def delete_role(name, project):
    """Deletes a role."""

    # pylint: disable=no-member
    role = service.projects().roles().delete(
        name='projects/' + project + '/roles/' + name).execute()

    print('Deleted role: ' + name)
    return role

Cuando se borra una función, sus enlaces permanecen, pero están inactivos. Puedes recuperar una función dentro de un plazo de 7 días. Durante este período de 7 días, la función se mostrará como Borrada en GCP Console y no aparecerá en comandos programáticos list (a menos que show_deleted se establezca en la solicitud).

Después de 7 días, la función está programada para borrarse permanentemente. Este proceso lleva 30 días. Durante el período de 30 días, la función y todos los enlaces asociados se quitan de forma permanente, y no puedes crear una nueva función con el mismo ID de función.

Una vez que la función se haya borrado de forma permanente, 37 días después de la solicitud de eliminación inicial, puedes crear una nueva función con el mismo ID de función.

Recupera una función personalizada

Console

  1. Dirígete a la página Funciones en GCP Console.

    Abrir la página Funciones

  2. Encuentra la función que deseas recuperar, haz clic en el ícono más al final de la fila y luego en Recuperar.

La función solo se puede recuperar dentro de los 7 días posteriores a la eliminación. Después de 7 días, la función se borra de forma permanente y se quitan todos los enlaces asociados con esta.

COMANDO DE GCLOUD

Usa el comando gcloud iam roles undelete para recuperar una función personalizada. Cuando recuperas una función, esta vuelve a su estado anterior.

La función solo se puede recuperar dentro de los 7 días posteriores a la eliminación. Después de 7 días, la función se borra de forma permanente y se quitan todos los enlaces asociados con esta.

Ejecuta el siguiente comando de gcloud para recuperar una función personalizada:

gcloud iam roles undelete [ROLE-ID] --project [PROJECT-ID]

Cada uno de los valores de marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id. También puedes usar la marca --organization [ORGANIZATION-ID] si la función se creó a nivel de la organización, como 1234567.

En el siguiente ejemplo, se muestra cómo recuperar una función personalizada:

gcloud iam roles undelete viewer --project my-project-id

Si la función se recuperó con éxito, se muestra la siguiente respuesta:

description: My custom role description.
etag: BwVkCAx9W6w=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

API de REST

roles.undelete recupera una función a su estado anterior.

El name puede estar en los siguientes formatos

  • organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}
  • projects/{PROJECT-ID}/roles/{ROLE-NAME}

La función solo se puede recuperar dentro de los 7 días posteriores a la eliminación. Después de 7 días, la función se borra de forma permanente y se quitan todos los enlaces asociados con esta.

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para recuperar la función en {path}.
FAILED_PRECONDITION No se puede recuperar una función que no está borrada.
FAILED_PRECONDITION No puedes recuperar una función {ROLE-NAME} que está reservada.
INVALID_ARGUMENT Las funciones predefinidas no se pueden recuperar.

C#

Antes de probar esta muestra, sigue las instrucciones de configuración de C# en el Inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.

public static Role UndeleteRole(string name, string project)
{
    string resource = $"projects/{project}/roles/{name}";
    Role role = s_service.Projects.Roles.Undelete(
        new UndeleteRoleRequest(), resource).Execute();

    Console.WriteLine("Undeleted role: " + role.Name);
    return role;
}

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

def undelete_role(name, project):
    """Undeletes a role."""

    # pylint: disable=no-member
    role = service.projects().roles().patch(
        name='projects/' + project + '/roles/' + name,
        body={
            'stage': 'DISABLED'
        }).execute()

    print('Disabled role: ' + role['name'])
    return role

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Documentación de Cloud Identity and Access Management