This page describes Identity and Access Management (IAM) basic, predefined, and custom roles, which are collections of IAM permissions.
A role contains a set of permissions that allows you to perform specific actions on Google Cloud resources. To make permissions available to principals, including users, groups, and service accounts, you grant roles to the principals.
Before you begin
- Understand the basic concepts of IAM.
There are three types of roles in IAM:
- Basic roles, which include the Owner, Editor, and Viewer roles that existed prior to the introduction of IAM.
- Predefined roles, which provide granular access for a specific service and are managed by Google Cloud.
- Custom roles, which provide granular access according to a user-specified list of permissions.
To determine if a permission is included in a basic, predefined, or custom role, you can use one of the following methods:
View the role in the Google Cloud console.
gcloud iam roles describecommand.
Get the role using the appropriate REST API method:
For basic and predefined roles only: Search the permissions reference to see if the permission is granted by the role.
For predefined roles only: Search the predefined role descriptions to see which permissions the role includes.
Each role has the following components:
- Title: A human-readable name for the role. The role title is used to identify the role in the Google Cloud console.
Name: An identifier for the role in one of the following formats:
- Predefined roles:
- Project-level custom roles:
- Organization-level custom roles:
The role name is used to identify the role in allow policies.
- Predefined roles:
ID: A unique identifier for the role. For basic and predefined roles, the ID is the same as the role name. For custom roles, the ID is everything after
roles/in the role name.
Description: A human-readable description of the role.
Stage: The stage of the role in the launch lifecycle, such as
GA. To learn more about launch stages, see Testing and deploying.
Permissions: The permissions included in the role. When you grant a role to a principal, the principal gets all of the permissions in the role.
ETag: An identifier for the version of the role to help prevent concurrent updates from overwriting each other. Basic and predefined roles always have the ETag
AA==. ETags for custom roles change each time you modify the roles.
There are several basic roles that existed prior to the introduction of IAM: Owner, Editor, and Viewer. These roles are concentric; that is, the Owner role includes the permissions in the Editor role, and the Editor role includes the permissions in the Viewer role. They were originally known as "primitive roles."
The following table summarizes the permissions that the basic roles include across all Google Cloud services:
Basic role definitions
||Viewer||Permissions for read-only actions that do not affect state, such as viewing (but not modifying) existing resources or data.|
All viewer permissions, plus permissions for actions that modify
state, such as changing existing resources.
Note: The Editor role contains permissions to create and delete resources for most Google Cloud services. However, it does not contain permissions to perform all actions for all services. For more information about how to check whether a role has the permissions that you need, see Role types on this page.
All Editor permissions and permissions for the following actions:
You can grant basic roles using the Google Cloud console, the API, and the gcloud CLI. See Granting, changing, and revoking access for instructions.
To see how to grant roles using the Google Cloud console, see Granting, changing, and revoking access.
In addition to the basic roles, IAM provides additional predefined roles that give granular access to specific Google Cloud resources. These roles are created and maintained by Google. Google automatically updates their permissions as necessary, such as when Google Cloud adds new features or services.
You can grant multiple roles to the same user, at any level of the resource hierarchy. For example, the same user can have the Compute Network Admin and Logs Viewer roles on a project, and also have the Pub/Sub Publisher role on a Pub/Sub topic within that project. To list the permissions contained in a role, see Getting the role metadata.
For help choosing the most appropriate predefined roles, see Choose predefined roles.
For a list of predefined roles, see the roles reference.
Any user with the correct permissions can create a custom role. Custom roles are granted in the same way as predefined and basic roles.
- Learn how to grant IAM roles to principals.
- Find out how to choose the most appropriate predefined roles.
- Use the Policy Troubleshooter to understand why a user does or doesn't have access to a resource or have permission to call an API.