Create and manage custom roles
Stay organized with collections
Save and categorize content based on your preferences.
This page describes how to create and manage Identity and Access Management (IAM)
custom roles. Managing roles includes modifying, disabling, listing, deleting,
and undeleting roles.
Before you begin
Enable the IAM API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the serviceusage.services.enable permission. If you
created the project, then you likely already have this permission through the
Owner role (roles/owner). Otherwise, you can get this permission through the
Service Usage Admin role (roles/serviceusage.serviceUsageAdmin).
Learn how to grant roles.
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
C#
To use the .NET samples on this page in a local development environment, install and
initialize the gcloud CLI, and then set up Application Default Credentials with
your user credentials.
To use the C++ samples on this page in a local development environment, install and
initialize the gcloud CLI, and then set up Application Default Credentials with
your user credentials.
To use the Go samples on this page in a local development environment, install and
initialize the gcloud CLI, and then set up Application Default Credentials with
your user credentials.
To use the Java samples on this page in a local development environment, install and
initialize the gcloud CLI, and then set up Application Default Credentials with
your user credentials.
To use the Python samples on this page in a local development environment, install and
initialize the gcloud CLI, and then set up Application Default Credentials with
your user credentials.
To get the permissions that
you need to create and manage custom roles,
ask your administrator to grant you the
following IAM roles:
To manage roles for a project:
Role Administrator (roles/iam.roleAdmin)
on the project that you want to manage roles for
To manage roles for an organization:
Organization Role Administrator (roles/iam.organizationRoleAdmin)
on the organization that you want to manage roles for
View available permissions for projects, folders, and organizations
You can create custom roles for an entire organization, or for a specific
project in that organization. The permissions that are available for custom
roles depend on where you create the role. For example, if a permission can only
be used at the organization level, then you can't include that permission in a
project-level custom role.
To check which permissions are available for organization-level and
project-level custom roles, you can use the gcloud CLI or the
Identity and Access Management API to list the permissions that are available in a specific
organization or project. For example, you can get all permissions that are
available for custom roles that are created in your project.
Some permissions might not be visible to you or usable in a custom role, even if they are supported
in custom roles. For example, a permission might not be available for use in custom roles if you
have not enabled the API for the service.
To learn more about the permissions that you can add to custom roles, see
Supported permissions.
gcloud
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
Use the gcloud iam list-testable-permissions command to get a list of permissions that are available for custom roles in a
specific project or organization. The response lists the permissions that you
can use in custom roles for that project or organization.
To list permissions that are available in custom roles for a project or
organization, run this command:
gcloud iam list-testable-permissions FULL_RESOURCE_NAME \
--filter="customRolesSupportLevel!=NOT_SUPPORTED"
Replace FULL_RESOURCE_NAME with one of the following
values:
Project: //cloudresourcemanager.googleapis.com/projects/PROJECT_ID
(for example, //cloudresourcemanager.googleapis.com/projects/my-project)
Organization: //cloudresourcemanager.googleapis.com/organizations/NUMERIC_ID
(for example, //cloudresourcemanager.googleapis.com/organizations/123456789012)
The results indicate whether each permission is supported in custom roles.
Permissions that do not have a customRolesSupportLevel field are fully
supported.
The list-testable-permissions command might return hundreds of results. This
partial example shows the format of each result:
---
name: appengine.applications.create
stage: GA
---
customRolesSupportLevel: TESTING
name: appengine.applications.disable
stage: GA
---
name: appengine.applications.get
stage: GA
---
name: appengine.applications.update
stage: GA
---
name: appengine.instances.delete
stage: GA
---
name: appengine.instances.get
stage: GA
---
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.cloud.iam.admin.v1.IAMClient.QueryTestablePermissionsPagedResponse;importcom.google.iam.admin.v1.QueryTestablePermissionsRequest;importjava.io.IOException;/** View available permissions in a project. */publicclassQueryTestablePermissions{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variable before running the sample.// Full resource names can take one of the following forms:// cloudresourcemanager.googleapis.com/projects/PROJECT_ID// cloudresourcemanager.googleapis.com/organizations/NUMERIC_IDStringfullResourceName="your-full-resource-name";queryTestablePermissions(fullResourceName);}publicstaticvoidqueryTestablePermissions(StringfullResourceName)throwsIOException{QueryTestablePermissionsRequestqueryTestablePermissionsRequest=QueryTestablePermissionsRequest.newBuilder().setFullResourceName(fullResourceName).build();try(IAMClientiamClient=IAMClient.create()){QueryTestablePermissionsPagedResponsequeryTestablePermissionsPagedResponse=iamClient.queryTestablePermissions(queryTestablePermissionsRequest);queryTestablePermissionsPagedResponse.iterateAll().forEach(permission->System.out.println(permission.getName()));}}}
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
importosfromtypingimportListfromgoogle.cloudimportresourcemanager_v3fromgoogle.iam.v1importiam_policy_pb2,policy_pb2defquery_testable_permissions(project_id:str,permissions:List[str])-> policy_pb2.Policy:"""Tests IAM permissions of the caller. project_id: ID or number of the Google Cloud project you want to use. permissions: List of permissions to get. """client=resourcemanager_v3.ProjectsClient()request=iam_policy_pb2.TestIamPermissionsRequest()request.resource=f"projects/{project_id}"request.permissions.extend(permissions)permissions_reponse=client.test_iam_permissions(request)print(permissions_reponse)returnpermissions_reponse.permissions
Before using any of the request data,
make the following replacements:
FULL_RESOURCE_NAME: A URI consisting of
the service name and the path to the resource. For examples, see
Full resource names.
PAGE_SIZE: Optional. The number of permissions to include in the
response. The default value is 100, and the maximum value is 1,000. If the number of permissions
is greater than the page size, the response contains a pagination token that you can use to
retrieve the next page of results.
NEXT_PAGE_TOKEN: Optional. The pagination token returned in an earlier
response from this method. If specified, the list of testable permissions
will start where the previous response ended.
HTTP method and URL:
POST https://iam.googleapis.com/v1/permissions:queryTestablePermissions
Copy the request body and open the
method reference page.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Paste the request body in this tool, complete any other required fields, and click Execute.
Before you create a custom role, you might want to get the metadata for both
predefined and custom roles. Role metadata includes the role ID and permissions
contained in the role. You can view the metadata using the
Google Cloud console or the IAM API.
To view the role metadata, use one of the methods below:
Select your organization or project from the drop-down list at the top of
the page.
Click the tab for the type of role that you want to view metadata for:
To view metadata for predefined roles, stay on the Predefined tab.
To view metadata for custom roles, click the Custom tab.
To view the role permissions, select the checkbox for the roles whose
permissions you want to view, then click Details. The panel displays the
permissions contained in the roles.
If you want to find all the roles that include a specific permission, type the
permission name in the Filter box at the top of the list of roles.
gcloud
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
To view the metadata for a predefined role, execute the following command:
gcloud iam roles describe ROLE_ID
ROLE_ID is the ID of the role. Predefined roles include
the role prefix in their IDs, for example, roles/iam.roleViewer.
The following example demonstrates the output of the describe command
when executed on the predefined role 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.getIamPolicyname:roles/iam.roleViewerstage:GAtitle:Role Viewer
To view the metadata for a custom role, execute one of the following commands:
To view the metadata for a custom role created at the organization level,
execute the following command:
gcloud iam roles describe --organization=ORGANIZATION_IDROLE_ID
To view the metadata for a custom role created at the project level,
execute the following command:
gcloud iam roles describe --project=PROJECT_IDROLE_ID
Each placeholder value is described below:
ORGANIZATION_ID is the numeric ID of the organization,
such as 123456789012.
PROJECT_ID is the name of the project, such as
my-project.
ROLE_ID is the ID of the role, excluding any prefixes
like projects/, organizations/, or roles/. For example,
myCompanyAdmin.
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.iam.admin.v1.GetRoleRequest;importcom.google.iam.admin.v1.Role;importjava.io.IOException;/** Get role metadata. Specifically, printing out role permissions. */publicclassGetRole{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variable before running the sample.StringroleId="a unique identifier (e.g. testViewer)";getRole(roleId);}publicstaticvoidgetRole(StringroleId)throwsIOException{GetRoleRequestgetRoleRequest=GetRoleRequest.newBuilder().setName(roleId).build();// Initialize client for sending requests. This client only needs to be created// once, and can be reused for multiple requests.try(IAMClientiamClient=IAMClient.create()){Rolerole=iamClient.getRole(getRoleRequest);role.getIncludedPermissionsList().forEach(permission->System.out.println(permission));}}}
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
fromgoogle.api_core.exceptionsimportNotFoundfromgoogle.cloud.iam_admin_v1importGetRoleRequest,IAMClient,Roledefget_role(project_id:str,role_id:str)-> Role:client=IAMClient()name=f"projects/{project_id}/roles/{role_id}"request=GetRoleRequest(name=name)try:role=client.get_role(request)print(f"Retrieved role: {role_id}: {role}")returnroleexceptNotFoundasexc:raiseNotFound(f"Role with id [{role_id}] not found, take some actions")fromexc
REST
The
roles.get
method gets the definition of a role.
Before using any of the request data,
make the following replacements:
ROLE_NAME: The full role name, including any
organizations/, projects/, or roles/ prefixes. For example,
organizations/123456789012/roles/myCompanyAdmin.
HTTP method and URL:
GET https://iam.googleapis.com/v1/ROLE_NAME
To send your request, expand one of these options:
Open the
method reference page.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Complete any required fields and click Execute.
The response contains the role definition.
{
"name": "projects/my-project/roles/customRole",
"title": "My Custom Role",
"description": "My custom role description.",
"includedPermissions": [
"storage.buckets.get",
"storage.buckets.list"
],
"etag": "BwWiPg2fmDE="
}
Create a custom role
You can create a custom role at the project or organization level.
An organization-level custom role can include any of the IAM
permissions that are supported in custom
roles. A project-level custom role can
contain any supported permission except for permissions that can only be used
at the organization or folder level, such as
resourcemanager.organizations.get. If you try to add these permissions to a
project-level custom role, you see an error message:
Each custom role can contain up to 3,000
permissions. Also, the maximum total size of the title, description, and
permission names for a custom role is 64 KB. If you
need to create a larger custom role, you can split the permissions across
multiple custom roles. Choose role titles that show the relationship between the
custom roles, such as Custom Admin (1 of 2) and Custom Admin (2 of 2).
Each custom role can have a launch stage. Most launch stages are informational,
and help you keep track of whether each role is ready for widespread use.
Additionally, the DISABLED launch stage lets you disable a custom
role. For more information about launch stages, see
Testing and deploying.
Console
Some predefined roles contain deprecated permissions or permissions that are
otherwise not permitted in custom roles. If you try to create a custom role
based on one of these predefined roles, the custom role will omit the deprecated
and restricted permissions.
To create a new custom role from scratch, do the following:
In the Google Cloud console, go to the Roles page.
Using the drop-down list at the top of the page, select the organization or
project in which you want to create a role.
Click Create custom role.
Enter a Title, Description, ID, and Role launch stage
for the role. The role ID cannot be changed after the role is created.
Click Add Permissions.
Select the permissions you want to include in the role and click Add
Permissions. Use the All Services and All Types drop-down lists to
filter and select permissions by services and types.
To create a custom role based on an existing predefined role, do the following:
In the Google Cloud console, go to the Roles page.
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
Use the gcloud iam roles create
command to create new custom roles. You can use this command in two ways:
By providing a YAML file that contains the role definition
By using flags to specify the role definition
When creating a custom role, you must specify whether it applies to the
organization level or project level by using the
--organization=ORGANIZATION_ID or
--project=PROJECT_ID flags. Each example below creates a
custom role at the project level.
ROLE_TITLE is a friendly title for the role, such as
"My Company Admin".
ROLE_DESCRIPTION is a short description of the
role, such as "My custom role description".
LAUNCH_STAGE indicates the stage of a role in the
launch lifecycle, such as ALPHA, BETA, or GA.
PERMISSION_1 and PERMISSION_2
are permissions to include in the custom role, such as iam.roles.get. You
can't use wildcard characters (*) in permission names.
Save the YAML file, and then execute one of the following commands:
To create a custom role at the organization level, execute the following
command:
gcloud iam roles create ROLE_ID--organization=ORGANIZATION_ID \
--file=YAML_FILE_PATH
To create a custom role at the project level, execute the following command:
gcloud iam roles create ROLE_ID --project=PROJECT_ID \
--file=YAML_FILE_PATH
Each placeholder value is described below:
ROLE_ID is the name of the role, such as myCompanyAdmin.
ORGANIZATION_ID is the numeric ID of the organization, such as
123456789012.
PROJECT_ID is the name of the project, such as my-project.
YAML_FILE_PATH is the path to the location of your YAML file that
contains the custom role definition.
Examples
The following example YAML file demonstrates how to create a role definition:
The following example demonstrates how to create a role at the organization
level using the YAML file:
gcloud iam roles create myCompanyAdmin --organization=123456789012 \
--file=my-role-definition.yaml
If the role was created successfully, the command's output is similar to the
following:
Created role [myCompanyAdmin].description:My custom role description.etag:BwVkBX0sQD0=includedPermissions:-iam.roles.get-iam.roles.listname:organizations/123456789012/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin
The following example demonstrates how to create a role at the project level
using the YAML file:
gcloud iam roles create myCompanyAdmin --project=my-project \
--file=my-role-definition.yaml
If the role was created successfully, the command's output is similar to the
following:
Created role [myCompanyAdmin].description:My custom role description.etag:BwVkBX0sQD0=includedPermissions:-iam.roles.get-iam.roles.listname:projects/my-project/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin
To create a custom role using flags:
Execute one of the following commands:
To create a custom role at the organization level, execute the following
command:
ROLE_ID is the name of the role, such as
myCompanyAdmin.
ORGANIZATION_ID is the numeric ID of the organization,
such as 123456789012.
PROJECT_ID is the name of the project, such as
my-project.
ROLE_TITLE is a friendly title for the role, such as
"My Company Admin".
ROLE_DESCRIPTION is a short description of the role,
such as "My custom role description.".
PERMISSIONS_LIST contains a comma-separated list of
permissions you want to include in the custom role. For example:
iam.roles.get,iam.roles.list. You can't use wildcard characters (*) in
permission names.
LAUNCH_STAGE indicates the stage of a role in the
launch lifecycle, such as ALPHA, BETA, or GA.
Examples
The following example demonstrates how to create a role at the organization
level using flags:
gcloud iam roles create myCompanyAdmin --organization=123456789012 \
--title="My Company Admin" --description="My custom role description." \
--permissions="iam.roles.get,iam.roles.list" --stage=ALPHA
If the role was created successfully, the command's output is similar to the
following:
Created role [myCompanyAdmin].description:My custom role description.etag:BwVkBX0sQD0=includedPermissions:-iam.roles.get-iam.roles.listname:organizations/123456789012/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin
The following example demonstrates how to create a role at the project
level using flags:
gcloud iam roles create myCompanyAdmin --project=my-project \
--title="My Company Admin" --description="My custom role description." \
--permissions="iam.roles.get,iam.roles.list" --stage=ALPHA
If the role was created successfully, the command's output is similar to the
following:
Created role [myCompanyAdmin].description:My custom role description.etag:BwVkBX0sQD0=includedPermissions:-iam.roles.get-iam.roles.listname:projects/my-project/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.iam.admin.v1.CreateRoleRequest;importcom.google.iam.admin.v1.Role;importcom.google.iam.admin.v1.Role.RoleLaunchStage;importjava.io.IOException;importjava.util.Arrays;/** Create role. */publicclassCreateRole{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variables before running the sample.StringprojectId="your-project-id";StringroleId="a unique identifier (e.g. testViewer)";Stringtitle="a title for your role (e.g. IAM Role Viewer)";Stringdescription="a description of the role";Iterable<String>includedPermissions=Arrays.asList("roles/iam.roleViewer","roles/logging.viewer");createRole(projectId,title,description,includedPermissions,roleId);}publicstaticvoidcreateRole(StringprojectId,Stringtitle,Stringdescription,Iterable<String>includedPermissions,StringroleId)throwsIOException{Role.BuilderroleBuilder=Role.newBuilder().setTitle(title).setDescription(description).addAllIncludedPermissions(includedPermissions)// See launch stage enums at// https://cloud.google.com/iam/docs/reference/rpc/google.iam.admin.v1#rolelaunchstage.setStage(RoleLaunchStage.BETA);CreateRoleRequestcreateRoleRequest=CreateRoleRequest.newBuilder().setParent("projects/"+projectId).setRoleId(roleId).setRole(roleBuilder).build();// Initialize client for sending requests. This client only needs to be created// once, and can be reused for multiple requests.try(IAMClientiamClient=IAMClient.create()){Roleresult=iamClient.createRole(createRoleRequest);System.out.println("Created role: "+result.getName());}}}
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
fromtypingimportList,Optionalfromgoogle.api_core.exceptionsimportAlreadyExists,FailedPreconditionfromgoogle.cloud.iam_admin_v1importCreateRoleRequest,IAMClient,Roledefcreate_role(project_id:str,role_id:str,permissions:List[str],title:Optional[str]=None)-> Role:"""Creates iam role with given parameters. Args: project_id: GCP project id role_id: id of GCP iam role permissions: list of iam permissions to assign to role. f.e ["iam.roles.get", "iam.roles.list"] title: title for iam role. role_id will be used in case of None Returns: google.cloud.iam_admin_v1.Role object """client=IAMClient()parent=f"projects/{project_id}"request=CreateRoleRequest(parent=parent,role_id=role_id,role=Role(title=title,included_permissions=permissions),)try:role=client.create_role(request)print(f"Created iam role: {role_id}: {role}")returnroleexceptAlreadyExists:print(f"Role with id [{role_id}] already exists, take some actions")exceptFailedPrecondition:print(f"Role with id [{role_id}] already exists and in deleted state, take some actions")
REST
The
roles.create
method creates a custom role in a project or organization.
Before using any of the request data,
make the following replacements:
RESOURCE_TYPE: The resource type whose
custom roles you want to manage. Use the value projects or organizations.
RESOURCE_ID: The project ID or
organization ID whose custom roles you want to manage. Project IDs are alphanumeric strings, like
my-project. Organization IDs are numeric, like 123456789012.
ROLE_ID: The name of the role, such as
myCompanyAdmin.
ROLE_TITLE: The human-readable title for the
role. For example, My Company Admin.
ROLE_DESCRIPTION: A description for the
role. For example, "The company admin role allows company admins to access important
resources".
PERMISSION_1 and
PERMISSION_2: The permissions that you want to include in the role. For
example, storage.objects.update. You can't use wildcard characters (*) in
permission names.
Copy the request body and open the
method reference page.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Paste the request body in this tool, complete any other required fields, and click Execute.
The response contains the role you created.
{
"name": "projects/myProject/roles/myCompanyAdmin",
"title": "My Company Admin",
"description": "My custom role description.",
"includedPermissions": [
"iam.roles.get",
"iam.roles.list"
],
"etag": "BwWox/JbaZw="
}
Edit an existing custom role
A common pattern for updating a resource's metadata, such as a custom role, is
the read-modify-write pattern. With this pattern, you read the role's current
state, update the data locally, and then send the modified data for writing.
The read-modify-write pattern can cause a conflict if two or more independent
processes attempt the sequence simultaneously. For example, if two owners for a
project try to make conflicting changes to a role at the same time, some changes
could fail. IAM solves this problem using an etag property in
custom roles. This property is used to verify if the custom role has changed
since the last request. When you make a request to IAM with an
etag value, IAM compares the etag value in the request with the
existing etag value associated with the custom role. It writes the change only
if the etag values match.
When you update a role, first get the role using roles.get(), update the role,
and then write the updated role using roles.patch(). Use the etag value when
setting the role only if the corresponding role in roles.get() contains an
etag value.
Console
In the Google Cloud console, go to the Custom tab of the Roles
page.
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
Use the gcloud iam roles update
command to update custom roles. You can use this command in two ways:
By providing a YAML file that contains the updated role definition
By using flags to specify the updated role definition
When updating a custom role, you must specify whether it applies to the
organization level or project level by using the --organization=ORGANIZATION_ID
or --project=PROJECT_ID flags. Each example below creates a
custom role at the project level.
To update a custom role using a YAML file:
Get the current definition for the role by executing one of the following commands:
To get the role definition of an organization-level custom role, execute the
following command:
gcloud iam roles describe ROLE_ID --organization=ORGANIZATION_ID
To get the role definition of a project-level custom role, execute the following command:
gcloud iam roles describe ROLE_ID --project=PROJECT_ID
Each placeholder value is described below:
ROLE_ID is the name of the role to update, such as
myCompanyAdmin.
ORGANIZATION_ID is the numeric ID of the organization, such as
123456789012.
PROJECT_ID is the name of the project, such as my-project.
The describe command returns the role's definition and includes
an etag value that uniquely identifies the current version
of the role. The etag value should be provided in the updated
role definition to ensure that any concurrent role changes are not overwritten.
The describe command returns the following output:
ROLE_DESCRIPTION is a short description of the role,
such as "My custom role description".
ETAG is the unique identifier for the current
version of the role, such as BwVkBkbfr70=.
PERMISSION_1 and PERMISSION_2
are permissions to include in the custom role, such as iam.roles.get.
You can't use wildcard characters (*) in permission names.
ROLE_NAME is the full role name, including any
organizations/, projects/, or roles/
prefixes. For example, organizations/123456789012/roles/myCompanyAdmin.
LAUNCH_STAGE indicates the stage of a role in the
launch lifecycle, such as ALPHA, BETA, or GA.
ROLE_TITLE is a friendly title for the role, such as
"My Company Admin".
To update the role, either include the outputted role definition to a YAML
file or update the original YAML file with the outputted etag value.
Consider the following example YAML file, which contains the output from
the describe command for a project-level role and adds two
Cloud Storage permissions:
description:My custom role description.etag:BwVkBkbfr70=includedPermissions:-iam.roles.get-iam.roles.list-storage.buckets.get-storage.buckets.listname:projects/my-project/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin
Save the YAML file, and then execute one of the following commands:
To update an organization-level role, execute the following command:
gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
--file=YAML_FILE_PATH
To update a project-level role, execute the following command:
gcloud iam roles update ROLE_ID --project=PROJECT_ID \
--file=YAML_FILE_PATH
Each placeholder value is described below:
ROLE_ID is the name of the role to update, such as
myCompanyAdmin.
ORGANIZATION_ID is the numeric ID of the organization,
such as 123456789012.
PROJECT_ID is the name of the project, such as
my-project-id.
YAML_FILE_PATH is the path to the location of your YAML
file that contains the updated custom role definition.
Examples
The following example demonstrates how to update an organization-level role using a YAML file:
gcloud iam roles update ROLE_ID --organization=ORGANIZATION_ID \
--file=YAML_FILE_PATH
To update a project-level role, execute the following command:
gcloud iam roles update ROLE_ID --project=PROJECT_ID \
--file=YAML_FILE_PATH
Each placeholder value is described below:
ROLE_ID is the name of the role to update, such as
myCompanyAdmin.
ORGANIZATION_ID is the numeric ID of the organization, such as
123456789012.
PROJECT_ID is the name of the project, such as my-project.
YAML_FILE_PATH is the path to the location of your YAML file that
contains the updated custom role definition.
Examples
The following example demonstrates how to update an organization-level role
using a YAML file:
gcloud iam roles update myCompanyAdmin --organization=123456789012 \
--file=my-role-definition.yaml
If the role was updated successfully, the command's output is similar to the
following:
description:My custom role description.etag:BwVkBwDN0lg=includedPermissions:-iam.roles.get-iam.roles.list-storage.buckets.get-storage.buckets.listname:organizations/123456789012/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin
The following example demonstrates how to update a project-level role using a YAML file:
gcloud iam roles update myCompanyAdmin --project=my-project \
--file=my-role-definition.yaml
If the role was updated successfully, the command's output is similar to the following:
description:My custom role description.etag:BwVkBwDN0lg=includedPermissions:-iam.roles.get-iam.roles.list-storage.buckets.get-storage.buckets.listname:projects/my-project/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin
To update a custom role using flags:
Each part of a role definition can be updated using a corresponding flag.
See the gcloud iam roles update
topic for a list of all possible flags.
You can use the following flags to add or remove permissions:
--add-permissions=PERMISSIONS: Adds one or more
comma-separated permissions to the role. You can't use wildcard characters
(*) in permission names.
--remove-permissions=PERMISSIONS: Removes one or more
comma-separated permissions from the role. You can't use wildcard characters
(*) in permission names.
Alternatively, you can simply specify the new permissions using the
--permissions=PERMISSIONS flag and providing a
comma-separated list of permissions to replace the existing permissions list.
To update other parts of the role definition, execute one of the following
commands:
To update an organization-level role, execute the following command:
gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
--title=ROLE_TITLE --description=ROLE_DESCRIPTION \
--stage=LAUNCH_STAGE
To update a project-level role, execute the following command:
ROLE_ID is the name of the role, such as myCompanyAdmin.
ORGANIZATION_ID is the numeric ID of the organization,
such as 123456789012.
PROJECT_ID is the name of the project, such as
my-project.
ROLE_TITLE is a friendly title for the role, such as
"My Company Admin".
ROLE_DESCRIPTION is a short description of the role,
such as "My custom role description.".
LAUNCH_STAGE indicates the stage of a role in the
launch lifecycle, such as ALPHA, BETA, or GA.
Examples
The following example demonstrates how to add permissions to an
organization-level role using flags:
gcloud iam roles update myCompanyAdmin --organization=123456789012 \
--add-permissions="storage.buckets.get,storage.buckets.list"
If the role was updated successfully, the command's output is similar to the following:
description:My custom role description.etag:BwVkBwDN0lg=includedPermissions:-iam.roles.get-iam.roles.list-storage.buckets.get-storage.buckets.listname:organizations/123456789012/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin
The following example demonstrates how to add permissions to a project-level role using flags:
gcloud iam roles update myCompanyAdmin --project=my-project \
--add-permissions="storage.buckets.get,storage.buckets.list"
If the role was updated successfully, the command's output is similar to the following:
description:My custom role description.etag:BwVkBwDN0lg=includedPermissions:-iam.roles.get-iam.roles.list-storage.buckets.get-storage.buckets.listname:projects/my-project/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
usingSystem;usingSystem.Collections.Generic;usingGoogle.Apis.Auth.OAuth2;usingGoogle.Apis.Iam.v1;usingGoogle.Apis.Iam.v1.Data;publicpartialclassCustomRoles{publicstaticRoleEditRole(stringname,stringprojectId,stringnewTitle,stringnewDescription,IList<string>newPermissions,stringnewStage){varcredential=GoogleCredential.GetApplicationDefault().CreateScoped(IamService.Scope.CloudPlatform);varservice=newIamService(newIamService.Initializer{HttpClientInitializer=credential});// First, get a Role using List() or Get().stringresource=$"projects/{projectId}/roles/{name}";varrole=service.Projects.Roles.Get(resource).Execute();// Then you can update its fields.role.Title=newTitle;role.Description=newDescription;role.IncludedPermissions=newPermissions;role.Stage=newStage;role=service.Projects.Roles.Patch(role,resource).Execute();Console.WriteLine("Updated role: "+role.Name);returnrole;}}
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.iam.admin.v1.Role;importcom.google.iam.admin.v1.Role.RoleLaunchStage;importcom.google.iam.admin.v1.UpdateRoleRequest;importcom.google.protobuf.FieldMask;importjava.io.IOException;/** Edit role metadata. Specifically, update description and launch stage. */publicclassEditRole{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variables before running the sample.// Role ID must point to an existing role.StringprojectId="your-project-id";StringroleId="a unique identifier (e.g. testViewer)";Stringdescription="a new description of the role";editRole(projectId,roleId,description);}publicstaticvoideditRole(StringprojectId,StringroleId,Stringdescription)throwsIOException{StringroleName="projects/"+projectId+"/roles/"+roleId;Role.BuilderroleBuilder=Role.newBuilder().setName(roleName).setDescription(description)// See launch stage enums at// https://cloud.google.com/iam/docs/reference/rpc/google.iam.admin.v1#rolelaunchstage.setStage(RoleLaunchStage.GA);FieldMaskfieldMask=FieldMask.newBuilder().addPaths("description").addPaths("stage").build();UpdateRoleRequestupdateRoleRequest=UpdateRoleRequest.newBuilder().setName(roleName).setRole(roleBuilder).setUpdateMask(fieldMask).build();// Initialize client for sending requests. This client only needs to be created// once, and can be reused for multiple requests.try(IAMClientiamClient=IAMClient.create()){Roleresult=iamClient.updateRole(updateRoleRequest);System.out.println("Edited role:\n"+result);}}}
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
fromgoogle.api_core.exceptionsimportNotFoundfromgoogle.cloud.iam_admin_v1importIAMClient,Role,UpdateRoleRequestfromsnippets.get_roleimportget_roledefedit_role(role:Role)-> Role:"""Edits an existing IAM role in a GCP project. Args: role: google.cloud.iam_admin_v1.Role object to be updated Returns: Updated google.cloud.iam_admin_v1.Role object """client=IAMClient()request=UpdateRoleRequest(name=role.name,role=role)try:role=client.update_role(request)print(f"Edited role: {role.name}: {role}")returnroleexceptNotFound:print(f"Role [{role.name}] not found, take some actions")
REST
The
roles.patch
method updates a custom role in a project or organization.
Before using any of the request data,
make the following replacements:
Required:
RESOURCE_TYPE: The resource type whose
custom roles you want to manage. Use the value projects or organizations.
RESOURCE_ID: The project ID or
organization ID whose custom roles you want to manage. Project IDs are alphanumeric strings, like
my-project. Organization IDs are numeric, like 123456789012.
ROLE_NAME: The full role name, including any
organizations/, projects/, or roles/ prefixes. For example,
organizations/123456789012/roles/myCompanyAdmin.
Recommended:
ETAG: An identifier for a version of the role.
Include this field to prevent overwriting other role changes.
Optional (define one or more of the following values):
ROLE_TITLE: The human-readable title for the
role. For example, My Company Admin.
ROLE_DESCRIPTION: A description for the
role. For example, "The company admin role allows company admins to access important
resources".
PERMISSION_1 and
PERMISSION_2: The permissions that you want to include in the role. For
example, storage.objects.update. You can't use wildcard characters (*) in
permission names.
LAUNCH_STAGE: The current launch stage of the
role. This field can contain one of the following values: EAP, ALPHA,
BETA, GA, DEPRECATED, or DISABLED.
Copy the request body and open the
method reference page.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Paste the request body in this tool, complete any other required fields, and click Execute.
The response contains an abbreviated role definition that includes the role name, the fields that
you updated, and an etag that identifies the current version of the role.
{
"name": "projects/test-project-1000092/roles/myCompanyAdmin",
"title": "My Updated Company Admin",
"includedPermissions": [
"storage.buckets.get",
"storage.buckets.list"
],
"stage": "BETA",
"etag": "BwWoyDpAxBc="
}
Disable a custom role
You can disable a custom role by changing its launch stage to DISABLED. When a
role is disabled, any role bindings related to the role are inactivated,
meaning that granting the role to a user has no effect.
Console
In the Google Cloud console, go to the Custom tab of the Roles
page.
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
Use the gcloud iam roles update
command to disable a custom role by setting its launch stage to DISABLED.
As described in the gcloud tab of the
Editing an existing custom role
section, you can update an existing custom role in the following two ways:
By providing a YAML file that contains the updated role definition
By using flags to specify the updated role definition
The easiest way to disable an existing custom role is to use the --stage
flag and set it to DISABLED. Execute one of the following commands:
To disable an organization-level role, execute the following command:
gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
--stage=DISABLED
To disable a project-level role, execute the following command:
gcloud iam roles update ROLE_ID --project=PROJECT_ID \
--stage=DISABLED
Each placeholder value is described below:
ROLE_ID is the name of the role, such as myCompanyAdmin.
ORGANIZATION_ID is the numeric ID of the organization, such as
123456789012.
PROJECT_ID is the name of the project, such as my-project.
Examples
The following example demonstrates how to disable an organization-level role:
gcloud iam roles update myCompanyAdmin --organization=123456789012 \
--stage=DISABLED
If the role was updated successfully, the command's output is similar to the following:
description:My custom role description.etag:BwVkB5NLIQw=includedPermissions:-iam.roles.get-iam.roles.listname:organizations/123456789012/roles/myCompanyAdminstage:DISABLEDtitle:My Company Admin
The following example demonstrates how to disable a project-level role:
gcloud iam roles update myCompanyAdmin --project=my-project \
--stage=DISABLED
If the role was updated successfully, the command's output is similar to the following:
description:My custom role description.etag:BwVkB5NLIQw=includedPermissions:-iam.roles.get-iam.roles.listname:projects/my-project/roles/myCompanyAdminstage:DISABLEDtitle:My Company Admin
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.iam.admin.v1.Role;importcom.google.iam.admin.v1.UpdateRoleRequest;importcom.google.protobuf.FieldMask;importjava.io.IOException;publicclassDisableRole{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variables before running the sample.// Role ID must point to an existing role.StringprojectId="your-project-id";StringroleId="testRole";Rolerole=disableRole(projectId,roleId);System.out.println("Role name: "+role.getName());System.out.println("Role stage: "+role.getStage());}publicstaticRoledisableRole(StringprojectId,StringroleId)throwsIOException{StringroleName="projects/"+projectId+"/roles/"+roleId;Rolerole=Role.newBuilder().setName(roleName).setStage(Role.RoleLaunchStage.DISABLED).build();FieldMaskfieldMask=FieldMask.newBuilder().addPaths("stage").build();UpdateRoleRequestupdateRoleRequest=UpdateRoleRequest.newBuilder().setName(roleName).setRole(role).setUpdateMask(fieldMask).build();// Initialize client for sending requests. This client only needs to be created// once, and can be reused for multiple requests.try(IAMClientiamClient=IAMClient.create()){returniamClient.updateRole(updateRoleRequest);}}}
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
fromgoogle.api_core.exceptionsimportNotFoundfromgoogle.cloud.iam_admin_v1importGetRoleRequest,IAMClient,Role,UpdateRoleRequestdefdisable_role(project_id:str,role_id:str)-> Role:"""Disables an IAM role in a GCP project. Args: project_id: GCP project ID role_id: ID of GCP IAM role Returns: Updated google.cloud.iam_admin_v1.Role object with disabled stage """client=IAMClient()name=f"projects/{project_id}/roles/{role_id}"get_request=GetRoleRequest(name=name)try:role=client.get_role(get_request)role.stage=Role.RoleLaunchStage.DISABLEDupdate_request=UpdateRoleRequest(name=role.name,role=role)client.update_role(update_request)print(f"Disabled role: {role_id}: {role}")returnroleexceptNotFoundasexc:raiseNotFound(f'Role with id [{role_id}] not found, take some actions')fromexc
REST
The
roles.patch
method lets you change a custom role's launch stage to DISABLED,
which disables the role.
Before using any of the request data,
make the following replacements:
RESOURCE_TYPE: The resource type whose
custom roles you want to manage. Use the value projects or organizations.
RESOURCE_ID: The project ID or
organization ID whose custom roles you want to manage. Project IDs are alphanumeric strings, like
my-project. Organization IDs are numeric, like 123456789012.
ROLE_NAME: The full role name, including any
organizations/, projects/, or roles/ prefixes. For example,
organizations/123456789012/roles/myCompanyAdmin.
ETAG: An identifier for a version of the role.
Include this field to prevent overwriting other role changes.
Copy the request body and open the
method reference page.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Paste the request body in this tool, complete any other required fields, and click Execute.
You should receive a JSON response similar to the following:
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
Use the gcloud iam roles list
command to list custom roles and predefined roles for a project or organization:
To list organization-level custom roles, execute the following command:
gcloud iam roles list --organization=ORGANIZATION_ID
To list project-level custom roles, execute the following command:
gcloud iam roles list --project=PROJECT_ID
Each placeholder value is described below:
ORGANIZATION_ID is the numeric ID of the organization, such as
123456789012.
PROJECT_ID is the name of the project, such as my-project.
To list deleted roles, you can also specify the --show-deleted flag.
Execute the following command to list predefined roles:
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.cloud.iam.admin.v1.IAMClient.ListRolesPagedResponse;importcom.google.iam.admin.v1.ListRolesRequest;importjava.io.IOException;/** List roles in a project. */publicclassListRoles{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variable before running the sample.StringprojectId="your-project-id";listRoles(projectId);}publicstaticvoidlistRoles(StringprojectId)throwsIOException{ListRolesRequestlistRolesRequest=ListRolesRequest.newBuilder().setParent("projects/"+projectId).build();// Initialize client for sending requests. This client only needs to be created// once, and can be reused for multiple requests.try(IAMClientiamClient=IAMClient.create()){ListRolesPagedResponselistRolesResponse=iamClient.listRoles(listRolesRequest);listRolesResponse.iterateAll().forEach(role->System.out.println(role));}}}
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
fromgoogle.cloud.iam_admin_v1importIAMClient,ListRolesRequest,RoleViewfromgoogle.cloud.iam_admin_v1.services.iam.pagersimportListRolesPagerdeflist_roles(project_id:str,show_deleted:bool=True,role_view:RoleView=RoleView.BASIC)-> ListRolesPager:"""Lists IAM roles in a GCP project. Args: project_id: GCP project ID show_deleted: Whether to include deleted roles in the results role_view: Level of detail for the returned roles (e.g., BASIC or FULL) Returns: A pager for traversing through the roles """client=IAMClient()parent=f"projects/{project_id}"request=ListRolesRequest(parent=parent,show_deleted=show_deleted,view=role_view)roles=client.list_roles(request)forpageinroles.pages:forroleinpage.roles:print(role)print("Listed all iam roles")returnroles
REST
The
roles.list
method lists all of the custom roles in a project or organization.
Before using any of the request data,
make the following replacements:
RESOURCE_TYPE: The resource type whose
custom roles you want to manage. Use the value projects or organizations.
RESOURCE_ID: The project ID or
organization ID whose custom roles you want to manage. Project IDs are alphanumeric strings, like
my-project. Organization IDs are numeric, like 123456789012.
ROLE_VIEW: Optional. The information to include for the returned
roles. To include the roles' permissions, set this field to FULL. To exclude the
roles' permissions, set this field to BASIC. The default value is BASIC.
PAGE_SIZE: Optional. The number of roles to include in the
response. The default value is 300, and the maximum value is 1,000. If the number of roles
is greater than the page size, the response contains a pagination token that you can use to
retrieve the next page of results.
NEXT_PAGE_TOKEN: Optional. The pagination token returned in an earlier
response from this method. If specified, the list of roles will start where the previous
request ended.
HTTP method and URL:
GET https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles?view=ROLE_VIEW&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN
To send your request, expand one of these options:
Open the
method reference page.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Complete any required fields and click Execute.
You should receive a JSON response similar to the following:
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
To delete an organization-level custom role, execute the following command:
gcloud iam roles delete ROLE_ID --organization=ORGANIZATION_ID
To delete a project-level custom role, execute the following command:
gcloud iam roles delete ROLE_ID --project=PROJECT_ID
Each placeholder value is described below:
ROLE_ID is the name of the role, such as myCompanyAdmin.
ORGANIZATION_ID is the numeric ID of the organization, such as
123456789012.
PROJECT_ID is the name of the project, such as my-project.
The role will not be included in gcloud iam roles list, unless the
--show-deleted flag is included. Deleted roles are indicated by the
deleted: true block in a list response, such as:
---
deleted: true
description: My custom role description.
etag: BwVkB5NLIQw=
name: projects/my-project/roles/myCompanyAdmin
title: My Company Admin
---
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.iam.admin.v1.DeleteRoleRequest;importjava.io.IOException;/** Delete role. */publicclassDeleteRole{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variables before running the sample.// Role ID must point to an existing role.StringprojectId="your-project-id";StringroleId="a unique identifier (e.g. testViewer)";deleteRole(projectId,roleId);}publicstaticvoiddeleteRole(StringprojectId,StringroleId)throwsIOException{StringroleName="projects/"+projectId+"/roles/"+roleId;DeleteRoleRequestdeleteRoleRequest=DeleteRoleRequest.newBuilder().setName(roleName).build();// Initialize client for sending requests. This client only needs to be created// once, and can be reused for multiple requests.try(IAMClientiamClient=IAMClient.create()){iamClient.deleteRole(deleteRoleRequest);System.out.println("Role deleted.");}}}
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
fromgoogle.api_core.exceptionsimportFailedPrecondition,NotFoundfromgoogle.cloud.iam_admin_v1import(DeleteRoleRequest,IAMClient,Role,UndeleteRoleRequest,)defdelete_role(project_id:str,role_id:str)-> Role:"""Deletes iam role in GCP project. Can be undeleted later. Args: project_id: GCP project id role_id: id of GCP iam role Returns: google.cloud.iam_admin_v1.Role object """client=IAMClient()name=f"projects/{project_id}/roles/{role_id}"request=DeleteRoleRequest(name=name)try:role=client.delete_role(request)print(f"Deleted role: {role_id}: {role}")returnroleexceptNotFound:print(f"Role with id [{role_id}] not found, take some actions")exceptFailedPreconditionaserr:print(f"Role with id [{role_id}] already deleted, take some actions)",err)
REST
The
roles.delete
method deletes a custom role in a project or organization.
Before using any of the request data,
make the following replacements:
ROLE_NAME: The full role name, including any
organizations/, projects/, or roles/ prefixes. For example,
organizations/123456789012/roles/myCompanyAdmin.
HTTP method and URL:
DELETE https://iam.googleapis.com/v1/ROLE_NAME
To send your request, expand one of these options:
Open the
method reference page.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Complete any required fields and click Execute.
The response contains the definition of the role that was deleted.
{
"name": "projects/my-project/roles/myCompanyAdmin",
"title": "My Company Admin",
"description": "My custom role description.",
"includedPermissions": [
"iam.roles.get",
"iam.roles.list"
],
"etag": "BwWiPg2fmDE=",
"deleted": true
}
When a role is deleted, any role bindings that refer to the role remain in your
allow policies, but they have no effect. You can undelete a role within
7 days. During this 7-day
period, the Google Cloud console shows that the role was deleted. You can also
list deleted roles programmatically, but they are omitted by default.
The role is scheduled for permanent deletion 7 to
14 days after the initial request to delete the role.
At this point, the role no longer counts towards the limit of
300 custom roles per organization or
300 custom roles per project.
After the role is scheduled for permanent deletion, Google Cloud initiates
the process to permanently delete the role. This process takes
30 days. During this 30-day
window, the role and all associated bindings are permanently removed, and you
cannot create a new role with the same role ID.
After the role has been permanently deleted, up to 44
days after the initial deletion request, you can create a new role using the
same role ID.
Undelete a custom role
Undeleting a role returns it to its previous state.
Roles can only be undeleted within 7 days. After
7 days, Google Cloud initiates the process to
permanently delete the role. This permanent deletion process can take up to
30 days. After a role is permanently deleted, all role
bindings that refer to the role are removed, and you can create a new role using
the same role ID.
Console
In the Google Cloud console, go to the Custom tab of the Roles
page.
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
To undelete an organization-level custom role, execute the following command:
gcloud iam roles undelete ROLE_ID --organization=ORGANIZATION_ID
To undelete a project-level custom role, execute the following command:
gcloud iam roles undelete ROLE_ID --project=PROJECT_ID
Each placeholder value is described below:
ROLE_ID is the name of the role, such as myCompanyAdmin.
ORGANIZATION_ID is the numeric ID of the organization, such as
123456789012.
PROJECT_ID is the name of the project, such as my-project.
Examples
The following example demonstrates how to undelete an organization-level custom role:
gcloud iam roles undelete myCompanyAdmin --organization=123456789012
If the role was undeleted successfully, the command's output is similar to the following:
description:My custom role description.etag:BwVkCAx9W6w=includedPermissions:-iam.roles.get-iam.roles.listname:organizations/123456789012/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin
The following example demonstrates how to undelete a project-level custom role:
gcloud iam roles undelete myCompanyAdmin --project=my-project
If the role was undeleted successfully, the command's output is similar to the following:
description:My custom role description.etag:BwVkCAx9W6w=includedPermissions:-iam.roles.get-iam.roles.listname:projects/my-project/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.iam.admin.v1.Role;importcom.google.iam.admin.v1.UndeleteRoleRequest;importjava.io.IOException;/** * Undelete a role to return it to its previous state. Undeleting only works on roles that were * deleted in the past 7 days. */publicclassUndeleteRole{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variables before running the sample.// Role ID must point to a role that was deleted in the past 7 days.StringprojectId="your-project-id";StringroleId="a unique identifier (e.g. testViewer)";undeleteRole(projectId,roleId);}publicstaticvoidundeleteRole(StringprojectId,StringroleId)throwsIOException{StringroleName="projects/"+projectId+"/roles/"+roleId;UndeleteRoleRequestundeleteRoleRequest=UndeleteRoleRequest.newBuilder().setName(roleName).build();// Initialize client for sending requests. This client only needs to be created// once, and can be reused for multiple requests.try(IAMClientiamClient=IAMClient.create()){Roleresult=iamClient.undeleteRole(undeleteRoleRequest);System.out.println("Undeleted role:\n"+result);}}}
To authenticate to IAM, set up Application Default Credentials.
For more information, see
Before you begin.
fromgoogle.api_core.exceptionsimportFailedPrecondition,NotFoundfromgoogle.cloud.iam_admin_v1import(DeleteRoleRequest,IAMClient,Role,UndeleteRoleRequest,)defundelete_role(project_id:str,role_id:str)-> Role:"""Undeleted deleted iam role in GCP project. Args: project_id: GCP project id role_id: id of GCP iam role """client=IAMClient()name=f"projects/{project_id}/roles/{role_id}"request=UndeleteRoleRequest(name=name)try:role=client.undelete_role(request)print(f"Undeleted role: {role_id}: {role}")returnroleexceptNotFound:print(f"Role with id [{role_id}] not found, take some actions")exceptFailedPreconditionaserr:print(f"Role with id [{role_id}] is not deleted, take some actions)",err)
REST
The
roles.undelete
method undeletes a custom role in a project or organization.
Before using any of the request data,
make the following replacements:
ROLE_NAME: The full role name, including any
organizations/, projects/, or roles/ prefixes. For example,
organizations/123456789012/roles/myCompanyAdmin.
ETAG: An identifier for a version of the role.
Include this field to prevent overwriting other role changes.
HTTP method and URL:
POST https://iam.googleapis.com/v1/ROLE_NAME:undelete
Request JSON body:
{
"etag": "ETAG"
}
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
Save the request body in a file named request.json,
and execute the following command:
Copy the request body and open the
method reference page.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Paste the request body in this tool, complete any other required fields, and click Execute.
The response contains the definition of the role that was undeleted.
{
"name": "projects/my-project/roles/myCompanyAdmin",
"title": "My Company Admin",
"description": "My custom role description.",
"includedPermissions": [
"iam.roles.get",
"iam.roles.list"
],
"etag": "BwWiPg2fmDE="
}
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2026-09-30 UTC."],[],[]]
