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.
This page is for audiences within the platform administrator group, such as IT admins or security engineers, who want to securely manage access to organizational resources. For more information, see Audiences for GDC air-gapped documentation.
Visit Predefined role descriptions and Role definitions for more information about roles.
Before you begin
Custom role access is managed at both organization and project levels. Access can only be granted within the same organization or project where the custom role 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.
View roles and their permissions
A custom role is made up of a group of permissions that you can assign to users. To create a custom role, select permissions from existing predefined roles and combine them to fit your needs. The permissions you can include in a custom role depend on the scope at which you create the role: organization or project.
This section explains how to list available roles (both predefined and custom) and view the permissions within them. You can use this information to do the following:
- Identify permissions for new custom roles: Discover the specific
permission strings required for the
--permissions
flag when using the gdcloud CLI to create a custom role. - Review existing roles: Examine the permissions associated with any predefined or custom role at the selected scope (organization or project).
List roles and examine their permissions 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.
Click a role name to view its details, including the assigned permissions.
The permissions listed for predefined roles at the current scope (organization or project) are the ones available to be included in a new custom role.
gdcloud
- Ensure you have the gdcloud CLI installed. For more information, see the gdcloud CLI Overview page.
List the roles available:
gdcloud iam roles list ROLE_TYPE \ --project=PROJECT
Replace the following:
ROLE_TYPE
: The type of roles to list. Valid values arepredefined
,custom
, orall
.PROJECT
: The project namespace where you want to view roles. Omit the--project
flag for organization-scoped roles.
View the specific permissions within a role:
gdcloud iam roles describe ROLE_NAME \ --project=PROJECT
Replace the following:
ROLE_NAME
: The Kubernetes resource name of the role.PROJECT
: The project namespace where you want to view role permissions. Omit the--project
flag for organization-scoped roles.
See gdcloud iam roles list and gdcloud iam roles describe for more command details and examples of usage.
Create a custom role
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. After you create a custom role, you can grant access to users.
Create a custom role using the GDC console, gdcloud CLI, or the API:
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 --stage=LAUNCH_STAGE
Replace the following:
ROLE_ID
: The unique identifier for your custom role. Custom role IDs can be up to 10 lowercase alphanumeric characters and can contain hyphens. 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 comma-separated list of permissions you want to grant for the custom role.For details about how to find the correct permission strings, see View roles and their permissions. Each permission string must be formatted according to the guidance in gdcloud iam roles create, where
iamRoleName
is the Kubernetes resource name of the predefined role containing the permission. You can find a role's Kubernetes resource name in the Role definitions page or by using the gdcloud iam roles list command.LAUNCH_STAGE
: Optional. The release stage of the custom role. Valid values areALPHA
,BETA
,GA
, orDISABLED
. Defaults toALPHA
if this flag is omitted.
See gdcloud iam roles create for a full list of required and optional flags, as well as examples of usage.
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.
API
Create and apply the CustomRole
custom resource using kubectl
:
kubectl apply -f - <<EOF
apiVersion: iam.global.gdc.goog/v1
kind: CustomRole
metadata:
name: ROLE_NAME
namespace: NAMESPACE
spec:
metadata:
description: DESCRIPTION
id: ROLE_ID
scope: SCOPE
stage: LAUNCH_STAGE
title: TITLE
RULES_TYPE:
- RULES_LIST
EOF
Replace the following:
ROLE_NAME
: The Kubernetes resource name of the role.NAMESPACE
: The namespace for the custom role. Useplatform
for organization-scoped roles and for multiple projects. Use the project namespace (such asmy-project
) for project-scoped roles and single projects.DESCRIPTION
: A description of the custom role's purpose.ROLE_ID
: The unique identifier for your custom role. Custom role IDs can be up to 10 lowercase alphanumeric characters and can contain hyphens. Custom role IDs can't change after role creation.SCOPE
: Useorganization
for roles created in theplatform
namespace. Useproject
for roles created in a project namespace.LAUNCH_STAGE
: Optional. The release stage of the custom role. Valid values areALPHA
,BETA
,GA
, orDISABLED
. Defaults toALPHA
if this field is omitted.TITLE
: A user-friendly title for the custom role.RULES_TYPE
: This field defines the scope of the rules. Replace with eitherglobalRules
(for permissions in the global API) orzonalRules
(for permissions in the zonal API). You can't use both in the sameCustomRole
resource.RULES_LIST
: An indented list of standard Kubernetes RBAC rule objects. Each object in the list grants permissions. You can determine the correctapiGroups
,resources
, andverbs
by examining the permissions within predefined roles usinggdcloud iam roles describe
, as shown in View roles and their permissions.The following example shows the structure of a single item within a
globalRules
object:globalRules: - apiGroups: ["storage.global.gdc.goog"] resources: ["buckettypes"] verbs: ["get", "list", "watch"]
You can include multiple items in the list, each defining a different set of permissions.
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. To view a list of all roles and their specific permissions, see View roles and their permissions.
Edit a custom role
Edit a custom role using the GDC console, gdcloud CLI, or the API:
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.
- Click Add permissions to select from the list of available permissions.
- 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 --stage=LAUNCH_STAGE
Replace the following:
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 comma-separated list of permissions you want to grant for the custom role.For details about how to find the correct permission strings, see View roles and their permissions. Each permission string must be formatted according to the guidance in gdcloud iam roles create, where
iamRoleName
is the Kubernetes resource name of the predefined role containing the permission. You can find a role's Kubernetes resource name in the Role definitions page or by using the gdcloud iam roles list command.LAUNCH_STAGE
: Optional. The release stage of the custom role. Valid values areALPHA
,BETA
,GA
, orDISABLED
. Defaults toALPHA
if this flag is omitted.
See gdcloud iam roles update for a full list of required and optional flags, as well as examples of usage.
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.
API
Edit a CustomRole
custom resource using kubectl
:
kubectl apply -f - <<EOF
apiVersion: iam.global.gdc.goog/v1
kind: CustomRole
metadata:
name: ROLE_NAME
namespace: NAMESPACE
spec:
metadata:
description: DESCRIPTION
id: ROLE_ID
scope: SCOPE
stage: LAUNCH_STAGE
title: TITLE
RULES_TYPE:
- RULES_LIST
EOF
Replace the following:
ROLE_NAME
: The Kubernetes resource name of the role.NAMESPACE
: The namespace for the custom role. Useplatform
for organization-scoped roles and for multiple projects. Use the project namespace (such asmy-project
) for project-scoped roles and single projects.DESCRIPTION
: A description of the custom role's purpose.ROLE_ID
: The unique identifier for your custom role. Custom role IDs can be up to 10 lowercase alphanumeric characters and can contain hyphens. Custom role IDs can't change after role creation.SCOPE
: Useorganization
for roles created in theplatform
namespace. Useproject
for roles created in a project namespace.LAUNCH_STAGE
: Optional. The release stage of the custom role. Valid values areALPHA
,BETA
,GA
, orDISABLED
. Defaults toALPHA
if this field is omitted.TITLE
: A user-friendly title for the custom role.RULES_TYPE
: This field defines the scope of the rules. Replace with eitherglobalRules
(for permissions in the global API) orzonalRules
(for permissions in the zonal API). You can't use both in the sameCustomRole
resource.RULES_LIST
: An indented list of standard Kubernetes RBAC rule objects. Each object in the list grants permissions. You can determine the correctapiGroups
,resources
, andverbs
by examining the permissions within predefined roles usinggdcloud iam roles describe
, as shown in View roles and their permissions.The following example shows the structure of a single item within a
globalRules
object:globalRules: - apiGroups: ["storage.global.gdc.goog"] resources: ["buckettypes"] verbs: ["get", "list", "watch"]
You can include multiple items in the list, each defining a different set of permissions.
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, gdcloud CLI, or the API:
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:
ROLE_ID
: The unique identifier for your custom role.
See gdcloud iam roles update for more information.
API
Disable a CustomRole
custom resource by changing the stage
field to
DISABLED
. Make sure all other fields match the current values for the
custom role you want to disable.
kubectl apply -f - <<EOF
apiVersion: iam.global.gdc.goog/v1
kind: CustomRole
metadata:
name: ROLE_NAME
namespace: NAMESPACE
spec:
metadata:
description: DESCRIPTION
id: ROLE_ID
scope: SCOPE
stage: DISABLED
title: TITLE
RULES_TYPE:
- RULES_LIST
EOF
Replace the following:
ROLE_NAME
: The Kubernetes resource name of the role.NAMESPACE
: The namespace for the custom role. Useplatform
for organization-scoped roles and for multiple projects. Use the project namespace (such asmy-project
) for project-scoped roles and single projects.DESCRIPTION
: A description of the custom role's purpose.ROLE_ID
: The unique identifier for your custom role. Custom role IDs can be up to 10 lowercase alphanumeric characters and can contain hyphens. Custom role IDs can't change after role creation.SCOPE
: Useorganization
for roles created in theplatform
namespace. Useproject
for roles created in a project namespace.TITLE
: A user-friendly title for the custom role.RULES_TYPE
: This field defines the scope of the rules. Replace with eitherglobalRules
(for permissions in the global API) orzonalRules
(for permissions in the zonal API). You can't use both in the sameCustomRole
resource.RULES_LIST
: An indented list of standard Kubernetes RBAC rule objects. Each object in the list grants permissions. You can determine the correctapiGroups
,resources
, andverbs
by examining the permissions within predefined roles usinggdcloud iam roles describe
, as shown in View roles and their permissions.The following example shows the structure of a single item within a
globalRules
object:globalRules: - apiGroups: ["storage.global.gdc.goog"] resources: ["buckettypes"] verbs: ["get", "list", "watch"]
You can include multiple items in the list, each defining a different set of permissions.
Delete a custom role
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 or the API:
gdcloud
- 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.
API
Delete a CustomRole
custom resource using kubectl
:
kubectl delete -f CUSTOM_ROLE
Replace CUSTOM_ROLE
with the path to your
CustomRole
YAML file. This is the same file that you used to create or
update the role.