Configure role recommendation generation

By changing your IAM recommender configuration, you can customize how your role recommendations are generated. This page explains how to edit your configuration to change how quickly recommendations are generated for your project.

Though the IAM recommender generates role recommendations for a variety of resources, you can only edit how role recommendations are generated for projects.

Before you begin

  • Enable the Recommender API.

    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.

    Enable the API

  • Understand how the IAM recommender generates role recommendations.
  • Install the Google Cloud CLI.

Required roles

To get the permissions that you need to configure IAM role recommendations, ask your administrator to grant you the following IAM roles on the project whose IAM recommender you want to configure:

  • View configuration details: IAM Recommender Viewer (roles/recommender.iamViewer)
  • Modify your configuration: IAM Recommender Admin (roles/recommender.iamAdmin)

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

These predefined roles contain the permissions required to configure IAM role recommendations. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to configure IAM role recommendations:

  • View configuration details: recommender.iamPolicyRecommenderConfig.get
  • Modify your configuration: recommender.iamPolicyRecommenderConfig.update

You might also be able to get these permissions with custom roles or other predefined roles.

View your current configuration

View your current configuration to see how many days of permission usage data the IAM recommender waits before generating role recommendations.

You can view the configuration using the gcloud CLI or the REST API.

gcloud

To get a project's IAM recommender configuration, use the gcloud beta recommender recommender-config describe command.

Before using any of the command data below, make the following replacements:

  • PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.

Execute the gcloud beta recommender recommender-config describe command:

Linux, macOS, or Cloud Shell

gcloud beta recommender recommender-config describe \
google.iam.policy.Recommender \
--project="PROJECT_ID" \
--location="global"

Windows (PowerShell)

gcloud beta recommender recommender-config describe `
google.iam.policy.Recommender `
--project="PROJECT_ID" `
--location="global"

Windows (cmd.exe)

gcloud beta recommender recommender-config describe ^
google.iam.policy.Recommender ^
--project="PROJECT_ID" ^
--location="global"

The response contains the project's IAM recommender configuration. For example, it might look like the following: 

etag: '"d3e779ee3f34f276"'
name: projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/config
recommenderGenerationConfig:
  params:
    minimum_observation_period: P90D
revisionId: DEFAULT
updateTime: '2022-10-02T22:57:33Z'

REST

To get a project's IAM recommender configuration, use the Recommender API's projects.locations.recommenders.getConfig method.

Before using any of the request data, make the following replacements:

  • PROJECT_NUMBER: The numeric ID of your Google Cloud project.
  • PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.

HTTP method and URL: 

GET https://recommender.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/global/recommenders/google.iam.policy.Recommender/config

To send your request, expand one of these options:

The response contains the project's IAM recommender configuration. For example, it might look like the following: 

{
  "name": "projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/config",
  "recommenderGenerationConfig": {
    "params": {
      "minimum_observation_period": "P90D"
    }
  },
  "etag": "\"d3e779ee3f34f276\"",
  "updateTime": "2022-10-02T22:57:33Z",
  "revisionId": "DEFAULT"
}

Understand configuration details

The contents of a configuration depend on which recommender the configuration is for. IAM recommender configurations have the following components, not necessarily in this order:

  • name: The identifier for the configuration, in the form projects/PROJECT_NUMBER/locations/global/recommenders/google.iam.policy.Recommender/config.