roles

Creates, updates, deletes, gets or lists a roles resource.

Overview

Name	roles
Type	Resource
Id	google.iam.roles

Fields

The following fields are returned by SELECT queries:

get_project_roles

Successful response

Name	Datatype	Description
name	string	The name of the role. When Role is used in CreateRole, the role name must not be set. When Role is used in output and other input such as UpdateRole, the role name is the complete path. For example, roles/logging.viewer for predefined roles, organizations/{ORGANIZATION_ID}/roles/myRole for organization-level custom roles, and projects/{PROJECT_ID}/roles/myRole for project-level custom roles.
deleted	boolean	The current deleted state of the role. This field is read only. It will be ignored in calls to CreateRole and UpdateRole.
description	string	Optional. A human-readable description for the role.
etag	string (byte)	Used to perform a consistent read-modify-write.
includedPermissions	array	The names of the permissions this role grants when bound in an IAM policy.
stage	string	The current launch stage of the role. If the ALPHA launch stage has been selected for a role, the stage field will not be included in the returned definition for the role.
title	string	Optional. A human-readable title for the role. Typically this is limited to 100 UTF-8 bytes.

get_org_roles

Successful response

Name	Datatype	Description
name	string	The name of the role. When Role is used in CreateRole, the role name must not be set. When Role is used in output and other input such as UpdateRole, the role name is the complete path. For example, roles/logging.viewer for predefined roles, organizations/{ORGANIZATION_ID}/roles/myRole for organization-level custom roles, and projects/{PROJECT_ID}/roles/myRole for project-level custom roles.
deleted	boolean	The current deleted state of the role. This field is read only. It will be ignored in calls to CreateRole and UpdateRole.
description	string	Optional. A human-readable description for the role.
etag	string (byte)	Used to perform a consistent read-modify-write.
includedPermissions	array	The names of the permissions this role grants when bound in an IAM policy.
stage	string	The current launch stage of the role. If the ALPHA launch stage has been selected for a role, the stage field will not be included in the returned definition for the role.
title	string	Optional. A human-readable title for the role. Typically this is limited to 100 UTF-8 bytes.

list_project_roles

Successful response

Name	Datatype	Description
name	string	The name of the role. When Role is used in CreateRole, the role name must not be set. When Role is used in output and other input such as UpdateRole, the role name is the complete path. For example, roles/logging.viewer for predefined roles, organizations/{ORGANIZATION_ID}/roles/myRole for organization-level custom roles, and projects/{PROJECT_ID}/roles/myRole for project-level custom roles.
deleted	boolean	The current deleted state of the role. This field is read only. It will be ignored in calls to CreateRole and UpdateRole.
description	string	Optional. A human-readable description for the role.
etag	string (byte)	Used to perform a consistent read-modify-write.
includedPermissions	array	The names of the permissions this role grants when bound in an IAM policy.
stage	string	The current launch stage of the role. If the ALPHA launch stage has been selected for a role, the stage field will not be included in the returned definition for the role.
title	string	Optional. A human-readable title for the role. Typically this is limited to 100 UTF-8 bytes.

get

Successful response

Name	Datatype	Description
name	string	The name of the role. When Role is used in CreateRole, the role name must not be set. When Role is used in output and other input such as UpdateRole, the role name is the complete path. For example, roles/logging.viewer for predefined roles, organizations/{ORGANIZATION_ID}/roles/myRole for organization-level custom roles, and projects/{PROJECT_ID}/roles/myRole for project-level custom roles.
deleted	boolean	The current deleted state of the role. This field is read only. It will be ignored in calls to CreateRole and UpdateRole.
description	string	Optional. A human-readable description for the role.
etag	string (byte)	Used to perform a consistent read-modify-write.
includedPermissions	array	The names of the permissions this role grants when bound in an IAM policy.
stage	string	The current launch stage of the role. If the ALPHA launch stage has been selected for a role, the stage field will not be included in the returned definition for the role.
title	string	Optional. A human-readable title for the role. Typically this is limited to 100 UTF-8 bytes.

list_org_roles

Successful response

Name	Datatype	Description
name	string	The name of the role. When Role is used in CreateRole, the role name must not be set. When Role is used in output and other input such as UpdateRole, the role name is the complete path. For example, roles/logging.viewer for predefined roles, organizations/{ORGANIZATION_ID}/roles/myRole for organization-level custom roles, and projects/{PROJECT_ID}/roles/myRole for project-level custom roles.
deleted	boolean	The current deleted state of the role. This field is read only. It will be ignored in calls to CreateRole and UpdateRole.
description	string	Optional. A human-readable description for the role.
etag	string (byte)	Used to perform a consistent read-modify-write.
includedPermissions	array	The names of the permissions this role grants when bound in an IAM policy.
stage	string	The current launch stage of the role. If the ALPHA launch stage has been selected for a role, the stage field will not be included in the returned definition for the role.
title	string	Optional. A human-readable title for the role. Typically this is limited to 100 UTF-8 bytes.

list

Successful response

Name	Datatype	Description
name	string	The name of the role. When Role is used in CreateRole, the role name must not be set. When Role is used in output and other input such as UpdateRole, the role name is the complete path. For example, roles/logging.viewer for predefined roles, organizations/{ORGANIZATION_ID}/roles/myRole for organization-level custom roles, and projects/{PROJECT_ID}/roles/myRole for project-level custom roles.
deleted	boolean	The current deleted state of the role. This field is read only. It will be ignored in calls to CreateRole and UpdateRole.
description	string	Optional. A human-readable description for the role.
etag	string (byte)	Used to perform a consistent read-modify-write.
includedPermissions	array	The names of the permissions this role grants when bound in an IAM policy.
stage	string	The current launch stage of the role. If the ALPHA launch stage has been selected for a role, the stage field will not be included in the returned definition for the role.
title	string	Optional. A human-readable title for the role. Typically this is limited to 100 UTF-8 bytes.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_project_roles	select	projectsId, rolesId		Gets the definition of a Role.
get_org_roles	select	organizationsId, rolesId		Gets the definition of a Role.
list_project_roles	select	projectsId	pageSize, pageToken, view, showDeleted	Lists every predefined Role that IAM supports, or every custom role that is defined for an organization or project.
get	select	rolesId		Gets the definition of a Role.
list_org_roles	select	organizationsId	pageSize, pageToken, view, showDeleted	Lists every predefined Role that IAM supports, or every custom role that is defined for an organization or project.
list	select		parent, pageSize, pageToken, view, showDeleted	Lists every predefined Role that IAM supports, or every custom role that is defined for an organization or project.
create_project_roles	insert	projectsId		Creates a new custom Role.
create_org_roles	insert	organizationsId		Creates a new custom Role.
patch_project_roles	update	projectsId, rolesId	updateMask	Updates the definition of a custom Role.
patch_org_roles	update	organizationsId, rolesId	updateMask	Updates the definition of a custom Role.
delete_project_roles	delete	projectsId, rolesId	etag	Deletes a custom Role. When you delete a custom role, the following changes occur immediately: * You cannot bind a principal to the custom role in an IAM Policy. * Existing bindings to the custom role are not changed, but they have no effect. * By default, the response from ListRoles does not include the custom role. A deleted custom role still counts toward the custom role limit until it is permanently deleted. You have 7 days to undelete the custom role. After 7 days, the following changes occur: * The custom role is permanently deleted and cannot be recovered. * If an IAM policy contains a binding to the custom role, the binding is permanently removed. * The custom role no longer counts toward your custom role limit.
delete_org_roles	delete	organizationsId, rolesId	etag	Deletes a custom Role. When you delete a custom role, the following changes occur immediately: * You cannot bind a principal to the custom role in an IAM Policy. * Existing bindings to the custom role are not changed, but they have no effect. * By default, the response from ListRoles does not include the custom role. A deleted custom role still counts toward the custom role limit until it is permanently deleted. You have 7 days to undelete the custom role. After 7 days, the following changes occur: * The custom role is permanently deleted and cannot be recovered. * If an IAM policy contains a binding to the custom role, the binding is permanently removed. * The custom role no longer counts toward your custom role limit.
undelete_project_roles	exec	projectsId, rolesId		Undeletes a custom Role.
query_grantable_roles	exec			Lists roles that can be granted on a Google Cloud resource. A role is grantable if the IAM policy for the resource can contain bindings to the role.
undelete_org_roles	exec	organizationsId, rolesId		Undeletes a custom Role.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
organizationsId	string
projectsId	string
rolesId	string
etag	string (byte)
pageSize	integer (int32)
pageToken	string
parent	string
showDeleted	boolean
updateMask	string (google-fieldmask)
view	string

SELECT examples

get_project_roles

Gets the definition of a Role.

SELECT
name,
deleted,
description,
etag,
includedPermissions,
stage,
title
FROM google.iam.roles
WHERE projectsId = '{{ projectsId }}' -- required
AND rolesId = '{{ rolesId }}' -- required;

get_org_roles

Gets the definition of a Role.

SELECT
name,
deleted,
description,
etag,
includedPermissions,
stage,
title
FROM google.iam.roles
WHERE organizationsId = '{{ organizationsId }}' -- required
AND rolesId = '{{ rolesId }}' -- required;

list_project_roles

Lists every predefined Role that IAM supports, or every custom role that is defined for an organization or project.

SELECT
name,
deleted,
description,
etag,
includedPermissions,
stage,
title
FROM google.iam.roles
WHERE projectsId = '{{ projectsId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}'
AND view = '{{ view }}'
AND showDeleted = '{{ showDeleted }}';

get

Gets the definition of a Role.

SELECT
name,
deleted,
description,
etag,
includedPermissions,
stage,
title
FROM google.iam.roles
WHERE rolesId = '{{ rolesId }}' -- required;

list_org_roles

Lists every predefined Role that IAM supports, or every custom role that is defined for an organization or project.

SELECT
name,
deleted,
description,
etag,
includedPermissions,
stage,
title
FROM google.iam.roles
WHERE organizationsId = '{{ organizationsId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}'
AND view = '{{ view }}'
AND showDeleted = '{{ showDeleted }}';

list

Lists every predefined Role that IAM supports, or every custom role that is defined for an organization or project.

SELECT
name,
deleted,
description,
etag,
includedPermissions,
stage,
title
FROM google.iam.roles
WHERE parent = '{{ parent }}'
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}'
AND view = '{{ view }}'
AND showDeleted = '{{ showDeleted }}';

INSERT examples

create_project_roles

Creates a new custom Role.

INSERT INTO google.iam.roles (
data__roleId,
data__role,
projectsId
)
SELECT 
'{{ roleId }}',
'{{ role }}',
'{{ projectsId }}'
RETURNING
name,
deleted,
description,
etag,
includedPermissions,
stage,
title
;

create_org_roles

Creates a new custom Role.

INSERT INTO google.iam.roles (
data__roleId,
data__role,
organizationsId
)
SELECT 
'{{ roleId }}',
'{{ role }}',
'{{ organizationsId }}'
RETURNING
name,
deleted,
description,
etag,
includedPermissions,
stage,
title
;

Manifest

# Description fields are for documentation purposes
- name: roles
  props:
    - name: projectsId
      value: string
      description: Required parameter for the roles resource.
    - name: organizationsId
      value: string
      description: Required parameter for the roles resource.
    - name: roleId
      value: string
      description: >
        The role ID to use for this role. A role ID may contain alphanumeric characters, underscores (`_`), and periods (`.`). It must contain a minimum of 3 characters and a maximum of 64 characters.
        
    - name: role
      value: object
      description: >
        A role in the Identity and Access Management API.
        

UPDATE examples

patch_project_roles

Updates the definition of a custom Role.

UPDATE google.iam.roles
SET 
data__name = '{{ name }}',
data__title = '{{ title }}',
data__description = '{{ description }}',
data__includedPermissions = '{{ includedPermissions }}',
data__stage = '{{ stage }}',
data__etag = '{{ etag }}',
data__deleted = {{ deleted }}
WHERE 
projectsId = '{{ projectsId }}' --required
AND rolesId = '{{ rolesId }}' --required
AND updateMask = '{{ updateMask}}'
RETURNING
name,
deleted,
description,
etag,
includedPermissions,
stage,
title;

patch_org_roles

Updates the definition of a custom Role.

UPDATE google.iam.roles
SET 
data__name = '{{ name }}',
data__title = '{{ title }}',
data__description = '{{ description }}',
data__includedPermissions = '{{ includedPermissions }}',
data__stage = '{{ stage }}',
data__etag = '{{ etag }}',
data__deleted = {{ deleted }}
WHERE 
organizationsId = '{{ organizationsId }}' --required
AND rolesId = '{{ rolesId }}' --required
AND updateMask = '{{ updateMask}}'
RETURNING
name,
deleted,
description,
etag,
includedPermissions,
stage,
title;

DELETE examples

delete_project_roles

Deletes a custom Role. When you delete a custom role, the following changes occur immediately: * You cannot bind a principal to the custom role in an IAM Policy. * Existing bindings to the custom role are not changed, but they have no effect. * By default, the response from ListRoles does not include the custom role. A deleted custom role still counts toward the custom role limit until it is permanently deleted. You have 7 days to undelete the custom role. After 7 days, the following changes occur: * The custom role is permanently deleted and cannot be recovered. * If an IAM policy contains a binding to the custom role, the binding is permanently removed. * The custom role no longer counts toward your custom role limit.

DELETE FROM google.iam.roles
WHERE projectsId = '{{ projectsId }}' --required
AND rolesId = '{{ rolesId }}' --required
AND etag = '{{ etag }}';

delete_org_roles

Deletes a custom Role. When you delete a custom role, the following changes occur immediately: * You cannot bind a principal to the custom role in an IAM Policy. * Existing bindings to the custom role are not changed, but they have no effect. * By default, the response from ListRoles does not include the custom role. A deleted custom role still counts toward the custom role limit until it is permanently deleted. You have 7 days to undelete the custom role. After 7 days, the following changes occur: * The custom role is permanently deleted and cannot be recovered. * If an IAM policy contains a binding to the custom role, the binding is permanently removed. * The custom role no longer counts toward your custom role limit.

DELETE FROM google.iam.roles
WHERE organizationsId = '{{ organizationsId }}' --required
AND rolesId = '{{ rolesId }}' --required
AND etag = '{{ etag }}';

Lifecycle Methods

undelete_project_roles

Undeletes a custom Role.

EXEC google.iam.roles.undelete_project_roles 
@projectsId='{{ projectsId }}' --required, 
@rolesId='{{ rolesId }}' --required 
@@json=
'{
"etag": "{{ etag }}"
}';

query_grantable_roles

Lists roles that can be granted on a Google Cloud resource. A role is grantable if the IAM policy for the resource can contain bindings to the role.

EXEC google.iam.roles.query_grantable_roles 
@@json=
'{
"fullResourceName": "{{ fullResourceName }}", 
"view": "{{ view }}", 
"pageSize": {{ pageSize }}, 
"pageToken": "{{ pageToken }}"
}';

undelete_org_roles

Undeletes a custom Role.

EXEC google.iam.roles.undelete_org_roles 
@organizationsId='{{ organizationsId }}' --required, 
@rolesId='{{ rolesId }}' --required 
@@json=
'{
"etag": "{{ etag }}"
}';