Get predefined role suggestions with Gemini assistance

This page describes how you can find and grant the least permissive Identity and Access Management (IAM) predefined roles to your principals with Gemini assistance.

The IAM role picker lets you ask Gemini which roles you should grant to your principals. Typically, to find the right predefined roles to grant, you would need to search through the IAM roles and permissions index or the Roles page in the Google Cloud console. With the IAM role picker, you can describe the actions you want the principal to perform and the resources that they need to perform them on. Based on your input, Gemini suggests the least permissive predefined roles that it considers appropriate.

Gemini can suggest predefined roles for individual principals. If Gemini suggests granting a role at the project level, then you can use the IAM role picker to grant that role.

Gemini can't suggest granting the following things:

Custom roles
Roles for multiple principals

Learn how and when Gemini for Google Cloud uses your data.

Before you begin

To enable the IAM role picker in your project, enable the Gemini for Google Cloud API in the Google Cloud console.

Enable the API

If you don't enable the API, the Help me choose roles button to access the IAM role picker in the Google Cloud console will be disabled.

Required Roles

To get the permissions that you need to use the IAM role picker, ask your administrator to grant you the following IAM roles on your project:

Ask Gemini for role suggestions: Gemini for Google Cloud User (roles/cloudaicompanion.user)
Grant suggested roles: Project IAM Admin (roles/resourcemanager.projectIamAdmin)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Get role suggestions with Gemini assistance

To get role suggestions from Gemini, you can access the IAM role picker on pages in the Google Cloud console that let you grant access at the project level. For example, the IAM role picker is available on the following pages:

The IAM page
The Service Accounts page
The Google Cloud console Dashboard page

The following procedure uses the IAM page as the primary entry point.

In the Google Cloud console, go to the IAM page.

Go to IAM
Select a project.
Select a principal to get role suggestions for:
- To get role suggestions for a principal who already has other roles on the resource, find a row containing the principal, and then click Edit principal in that row.
  
  To grant a role to a service agent, select the Include Google-provided role grants checkbox to see its email address.
  
  Note: You cannot edit inherited roles when managing access to a resource. To edit inherited roles, go to the resource where the role was granted.
- To get role suggestions for a principal who doesn't have any existing roles on the resource, click Grant Access, then enter a principal identifier—for example, my-user@example.com or //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.
To open the IAM role picker dialog, click Help me choose roles.
In your own words, describe the action you want the principal to perform and the resource in the project that they need to perform it on.
Click Suggest roles. Based on your input, Gemini suggests the least permissive predefined roles that it considers appropriate.

To get more information about the roles and why Gemini suggested them, click Show reasoning. We also recommend using the roles and permissions reference to validate Gemini's suggested roles before granting them to the principal.
Optional: If Gemini doesn't suggest the right roles, you can refine your prompt.
1. To modify your prompt, click Edit.
2. Edit the description and then click Update. Gemini updates its role suggestions based on the new description.
To accept the suggestions, click Add roles.
Optional: Add a condition to the role.
Click Save. The principal is granted the role on the resource.

You can grant project-level roles suggested by Gemini directly from the IAM role picker. For organization-, folder-, or resource-level role suggestions, note the suggested roles and grant them to the principal at the appropriate level using the typical process in the Google Cloud console. For more information about granting roles, see Manage access to projects, folders, and organizations.

If you don't have the permissions to grant the roles at the organization, folder, or resource levels, contact your administrator.

Sample use cases

The following table illustrates some example use cases where Gemini can help you identify the least permissive roles for your principals.

Use case	Prompt examples
Identifying least-permissive roles necessary to perform a specific task	"What role is required to create, start, and stop VMs?" "What are the least-privileged IAM roles required to create IAM policies?" "I need to allow a user to create and manage BigQuery datasets and tables. What role should I assign?" "I need to grant a service account access to invoke Cloud Run functions. What's the minimal role required?" "Which role allows a service account to read data from Cloud Storage but not write or delete objects?"
Identifying least-permissive roles necessary to run Google Cloud CLI commands	"What IAM role is required to run the following command: `gcloud compute instances create instance-1 --zone=us-central1-a`" "I would like to identify the necessary roles for a service account to execute the following command: `gcloud datastore instances describe`"
Identifying roles for a task that includes transitive dependencies	"I need to configure a Compute Engine instance to automatically scale based on CPU utilization. Which IAM role(s) should be granted to the service account used by the instance autoscaler?"
Identifying roles for a task that might require a combination of multiple granular roles	"Provide users access only to a particular dataset. We don't want to share the access to all datasets, and we only allow users to access a particular dataset within BigQuery. They shouldn't be able to create new datasets or delete it"

Best practices

To help Gemini provide the most accurate suggestions for your use case, we recommend that you adhere to the following best practices when drafting your prompt.

Clearly describe your use case. Avoid using vague language in your prompts. Be as clear as possible about what actions you want the principal to perform on which services and resource types.

Do	Don't	Details
"What role is required to execute SQL queries on a BigQuery table and read the data from it?"	"What role is required to execute SQL statements?"	SQL is a generic language used across multiple Google Cloud services. Without specifying the service or actions, Gemini can't suggest a precise role.
"I need roles to start, stop, and reboot Compute Engine virtual machine instances."	"I need to manage my virtual machines."	The term manage is too vague. Manage could mean creating, deleting, updating, or viewing VMs. Clearly listing the specific actions to be performed (start, stop, reboot) and the exact resource type (Compute Engine virtual machine instances) yields more accurate suggestions.
"I need to upload and download objects from a Cloud Storage bucket named `example-bucket`."	"Give me access to storage."	The term Storage alone could refer to various services like Cloud Storage, Filestore, or Persistent Disk. In addition, there are no actions specified. Without specifying the service (Cloud Storage), the resource type name (`example-bucket`), or the actions (upload and download objects), Gemini doesn't have enough information to suggest the right roles.

Use official names. Use the official names of Google Cloud services, resource types, and API operations in your prompt. If you are unsure about the official names of services, resource types, or API operations, we recommend consulting the official product documentation.

Do	Don't	Details
"What role do I need to update BigQuery datasets?"	"What role do I need to update Big query datasets?	BigQuery is the official name of the product—not Big query.
"What role is required to create a Cloud Storage bucket in my project?"	"What role is required to create a Storage bucket in my project?"	Storage bucket could refer to different resource types from services like Cloud Storage, Filestore, or Persistent Disk. Specifying the product name and the associated resource type will yield more accurate suggestions.

Troubleshooting

This section describes resolutions for common issues with the IAM role picker.

Gemini suggests roles that you can't grant at the project level

Gemini can suggest roles at all resource levels; however, you can only use the IAM role picker to grant the project-level roles that are suggested. When Gemini suggests organization, folder, or resource-level roles, the IAM role picker indicates that there are suggested roles that can't be granted and the Add roles button will be disabled.

When this occurs, you can copy the suggested roles and grant them to the principal at the appropriate level using the typical process in the Google Cloud console. For more information on granting roles, see Manage access to projects, folders, and organizations.