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.
- 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, likemy-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, likemy-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 formprojects/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), orP90D
(90 days). -
ETAG
: The configuration's current etag, which you can find by getting the current configuration and copying the value of the response'setag
field. PROJECT_ID
: Your Google Cloud project ID. Project IDs are alphanumeric strings, likemy-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), orP90D
(90 days). -
ETAG
: The configuration's current etag, which you can find by getting the current configuration and copying the value of the response'setag
field. Use backslashes to escape quotes, for example,"\"df7308cca9719dcc\""
. PROJECT_ID
: Your Google Cloud project ID. Project IDs are alphanumeric strings, likemy-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
- Review and apply role recommendations for projects, folders, and organizations.
- Review and apply your role recommendations for Cloud Storage buckets
- Learn more about Recommender.