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

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.
  • recommenderGenerationConfig: The parameters that the IAM recommender uses when generating recommendations. This field contains the following parameters:

    • minimum_observation_period: The number of days of permission usage data that the IAM recommender needs to start generating role recommendations.
  • etag: An identifier for the current state of a configuration, used to prevent concurrent updates. Each time the configuration changes, a new ETag value is assigned.

  • updateTime: The timestamp of the most recent time that the configuration was updated, in UTC format (RFC 3339).

  • revisionId: Output only. An identifier for the current revision of the configuration. This value is updated every time the configuration is edited.

Edit your configuration

Edit your configuration to change how quickly recommendations are generated for your project.

gcloud

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

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

  • OBSERVATION_PERIOD: The minimum observation period that you want to set. Use one of the following values: P30D (30 days), P60D (60 days), or P90D (90 days).
  • ETAG: The configuration's current etag, which you can find by getting the current configuration and copying the value of the response's etag field.
  • PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.
  • Save the following content in a file called request.json:

    {
      "params": {
        "minimum_observation_period": "OBSERVATION_PERIOD"
      }
    }

    Execute the gcloud beta recommender recommender-config update command:

    Linux, macOS, or Cloud Shell

    gcloud beta recommender recommender-config update \
    google.iam.policy.Recommender \
    --etag="ETAG" \
    --project="PROJECT_ID" \
    --location="global" \
    --config-file="request.json"

    Windows (PowerShell)

    gcloud beta recommender recommender-config update `
    google.iam.policy.Recommender `
    --etag="ETAG" `
    --project="PROJECT_ID" `
    --location="global" `
    --config-file="request.json"

    Windows (cmd.exe)

    gcloud beta recommender recommender-config update ^
    google.iam.policy.Recommender ^
    --etag="ETAG" ^
    --project="PROJECT_ID" ^
    --location="global" ^
    --config-file="request.json"

    The response contains the updated configuration. For example, it might look like the following:

    etag: '"2549af0942332910"'
    name: projects/123456789012/locations/global/recommenders/google.iam.policy.Recommender/config
    recommenderGenerationConfig:
      params:
        minimum_observation_period: P60D
    revisionId: 288c60eb
    updateTime: '2022-10-05T21:42:21.069170Z'
    

REST

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

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

  • PROJECT_NUMBER: The numeric ID of your Google Cloud project.
  • OBSERVATION_PERIOD: The minimum observation period that you want to set. Use one of the following values: P30D (30 days), P60D (60 days), or P90D (90 days).
  • ETAG: The configuration's current etag, which you can find by getting the current configuration and copying the value of the response's etag field. Use backslashes to escape quotes, for example, "\"df7308cca9719dcc\"".
  • PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.
  • HTTP method and URL:

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

    Request JSON body:

    {
      "name": "projects/PROJECT_NUMBER/locations/global/recommenders/google.iam.policy.Recommender/config",
      "recommenderGenerationConfig": {
        "params": {
          "minimum_observation_period": "OBSERVATION_PERIOD"
        }
      },
      "etag": "ETAG"
    }
    

    To send your request, expand one of these options:

    The response contains the updated 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": "P60D"
        }
      },
      "etag": "\"2549af0942332910\"",
      "updateTime": "2022-10-05T21:26:52.127512Z",
      "revisionId": "b5fc0053"
    }
    

What's next