Create a custom role

This page describes how to create and manage custom roles in Google Distributed Cloud (GDC) air-gapped. Custom roles let you manage access beyond the standard permission sets available in predefined roles, enabling you to configure permissions to meet your specific criteria.

Custom roles follow the principle of least privilege and are useful for granting the least access required for sensitive tasks, mitigating security risks and preventing conflicts of interest.

Creating a custom role lets you:

Define the scope of access: Choose to apply permissions across your organization, across all projects, or restrict them to specific projects.
Tailor granular access: Select one or more permissions already available through predefined roles to customize access to specific tasks or responsibilities.

See Predefined role descriptions and Role definitions for more information.

Before you begin

Custom role access is managed at both organization and project levels. Custom role access can only be granted within the same organization or project where it was created.

To have the necessary permissions to create and manage custom roles, ask your administrator to grant you one of the following roles:

Custom Role Org Admin

Creates and manages custom roles within an organization or project. This role includes the ability to update, list, view, disable, and delete custom roles.

Organization IAM Admin users can grant this role.
Custom Role Project Admin

Creates and manages custom roles within a project. This role includes the ability to update, list, view, disable, and delete custom roles.

Project IAM Admin users can grant this role.

Learn more about assigning role permissions for organizations and projects.

Create a custom role

A custom role is a group of permissions that you can assign to users. You can create a new custom role by grouping permissions from predefined roles together. Custom roles inherit the IAM multi-zone capabilities of the predefined roles they are built upon.

Create a custom role using the GDC console or gdcloud CLI:

Console

Sign in to the GDC console.
In the project selector, select the organization or project in which you want to create a custom role.
In the navigation menu, click Identity & Access > Roles.
Click Create Custom Role.
In the Title field, enter your custom role's title.
In the Description field, provide a description of your custom role's purpose.
In the ID field, enter the unique identifier for your custom role.

Custom role IDs can be up to 10 lowercase alphanumeric characters and can't change after role creation.
Select a Launch stage.
Select the scope of your custom role.

If you select Organization, the custom role applies to all resources across the organization. If you select Projects, the custom role applies to all current and future projects in the organization. You can select Limit to selected projects if you want to specify which projects can access the custom role.
Click Add Permissions.
Select the checkbox next to one or more of the supported permissions that you want to assign to your custom role.

Available permissions are limited to your selected scope. If you change scope after adding permissions, you must confirm that all previously assigned permissions reset.
Click Save.
Click Create.

Your new custom role appears on the Roles page.

gdcloud

Ensure you have the gdcloud CLI installed. For more information, see the gdcloud CLI Overview page.
Create a custom role:
```
gdcloud iam roles create ROLE_ID \
  --title=TITLE \
  --description=DESCRIPTION \
  --permissions=PERMISSIONS
```
Replace the following required elements:
- ROLE_ID: The unique identifier for your custom role. Custom role IDs can be up to 10 lowercase alphanumeric characters, and can contain hyphens and periods. Custom role IDs can't change after role creation.
- TITLE: A user-friendly title for the custom role.
- DESCRIPTION: A description of the custom role's purpose.
- PERMISSIONS: A list of supported permissions granted for the custom role.
Alternatively, you can define the custom role in a YAML file and use the --file flag:
```
gdcloud iam roles create ROLE_ID --file=YAML_FILE_PATH
```
Replace YAML_FILE_PATH with the path to the YAML file containing the required and optional flags. If you use the --file flag, all other flags such as --title, --description, and --permissions are ignored.

See gdcloud iam roles create for a full list of required and optional flags, as well as examples of usage.

Manage a custom role

You are responsible for managing the lifecycle of your custom roles. When Distributed Cloud adds new permissions, features, or services, it updates predefined roles. Updates like deleting a predefined role or removing permissions from a predefined role can render the custom roles that rely on those permissions non-functional. You must monitor these updates and manually adjust affected custom roles to ensure they continue to work as expected.

You can edit, disable, or delete a custom role; however, you cannot edit, disable, or delete a predefined role.

View a list of roles

View a list of available predefined and custom roles using the GDC console or gdcloud CLI:

Console

Sign in to the GDC console.
In the project selector, select the organization or project in which you want to view roles.
In the navigation menu, click Identity & Access > Roles.

A list of available predefined and custom roles appears.

gdcloud

Ensure you have the gdcloud CLI installed. For more information, see the gdcloud CLI Overview page.
List roles:
```
gdcloud iam roles list ROLE_TYPE \
  --project=PROJECT
```
Replace the following elements:
- ROLE_TYPE: Either predefined, custom, or all.
- PROJECT: The project namespace where you want to view roles. If the --project flag isn't specified, organization-scoped roles are listed.
See gdcloud iam roles list for more information and examples of usage.

Edit a custom role

Edit a custom role using the GDC console or gdcloud CLI:

Console

Sign in to the GDC console.
In the project selector, select the organization or project in which you want to edit a custom role.
In the navigation menu, click Identity & Access > Roles.
From the list of roles, select the custom role you want to edit.
From the custom role details page, click Edit.
Edit your custom role details such as title, description, ID, or launch stage.
Optionally add or remove assigned permissions.
1. Click Add permissions to select from the list of available permissions.
2. To remove an assigned permission, select the checkbox next to the permission you want to remove and click Remove.
Click Save.

A message appears confirming your saved changes.

gdcloud

Ensure you have the gdcloud CLI installed. For more information, see the gdcloud CLI Overview page.
Edit a custom role:
```
gdcloud iam roles update ROLE_ID \
  --title=TITLE \
  --description=DESCRIPTION \
  --permissions=PERMISSIONS
```
Replace the following required elements:
- ROLE_ID: The unique identifier for your custom role.
- TITLE: A user-friendly title for the custom role.
- DESCRIPTION: A description of the custom role's purpose.
- PERMISSIONS: A list of supported permissions granted for the custom role.
Alternatively, you can update the custom role in its YAML file and use the --file flag:
```
gdcloud iam roles update ROLE_ID --file=YAML_FILE_PATH
```
Replace YAML_FILE_PATH with the path to the YAML file containing the updated required and optional flags. If you use the --file flag, all other flags such as --title, --description, and --permissions are ignored.

See gdcloud iam roles update for a full list of required and optional flags, as well as examples of usage.

Disable a custom role

Disabled custom roles remain in your list of roles and can still be assigned to users; however, the role has no effect. You can re-enable the custom role at any time.

Disable a custom role using the GDC console or gdcloud CLI:

Console

Sign in to the GDC console.
In the project selector, select the organization or project in which you want to disable a custom role.
In the navigation menu, click Identity & Access > Roles.
In the list of roles, select the custom role you want to disable.
On the custom role details page, click Disable.

gdcloud

Ensure you have the gdcloud CLI installed. For more information, see the gdcloud CLI Overview page.
Disable a custom role:
```
gdcloud iam roles update ROLE_ID --stage=DISABLED
```
Replace the following required element:
- ROLE_ID: The unique identifier for your custom role.
See gdcloud iam roles update for more information.

Delete a custom role

Deleting a custom role is only supported using the gdcloud CLI. Deleted roles are permanently removed from the system; however, you can create a new role with the same name.

Delete a custom role using the gdcloud CLI:

Ensure you have the gdcloud CLI installed. For more information, see the gdcloud CLI Overview page.
Delete a custom role:
```
gdcloud iam roles delete ROLE_ID --project=PROJECT
```
Replace the following:
- ROLE_ID: The unique identifier for your custom role.
- PROJECT: The project namespace where you want to delete the custom role. If the --project flag isn't specified, the organization-scoped role is deleted.
See gdcloud iam roles delete for more information and examples of usage.