Configure underutilized reservation recommendations
Preview
This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.
This page describes how to view and modify the configuration of your underutilized,on-demand reservation recommendations. You might want to modify theconfiguration to increase the number of recommendations that you receive, orto get fewer recommendations to delete reservations that you plan to use.
- For more information on the parameters you can use to customize therecommendations, seeChoose the right configuration parameters.
- For more information on how to take action when you get recommendations aboutidle or underutilized reservations, seeView and apply idle reservation recommendationsorView and apply underutilized reservation recommendations.
Before you begin
- If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
gcloud
Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
gcloudinit
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.- Set a default region and zone.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
gcloudinit
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.
Configure your recommendations
To configure your underutilized reservation recommendations, do the following:
- Get the current configuration to obtainthe JSON file of the configuration.
- Edit the configuration file in JSON format.
- Upload the new configuration fileto apply the changes.
Get the current configuration
You can obtain the current configuration for underutilized reservation recommendationsfor your project by using the Google Cloud CLI or REST.
Permissions required for this task
To perform this task, you must have the followingpermissions:
recommender.computeRightSizeResourceRecommender.geton the project.
Complete this task using one of the following methods.
gcloud
To get the current configuration parameters, use thegcloud recommender recommender-config describe commandand usegoogle.compute.RightSizeResourceRecommender as theRecommender ID:
gcloud recommender recommender-config describe google.compute.RightSizeResourceRecommender \ --location=ZONE --billing-account=BILLING_ACCOUNT_ID
Replace the following:
ZONEwith the zone that contains reservationsto list recommendations for.BILLING_ACCOUNT_IDwith the ID of your billingaccount.
For example:
gcloud recommender recommender-config describe google.compute.RightSizeResourceRecommender \ --location=us-central1-c --billing-account=my-billing-account-id
The command returns the recommender configuration, including the modifiablesubfieldsparams.under_utilized_reservation_lookback_period andparams.under_utilized_reservation_utilization_threshold.
{ "name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.RightSizeResourceRecommender/config", "recommenderGenerationConfig": { "params": { "under_utilized_reservation_lookback_period": "P7D", "under_utilized_reservation_utilization_threshold": "0.8" } }, "etag": "\"2f3c9b65cda6a4ba\"", "updateTime": "2024-06-03T04:41:15.330351Z"}REST
To retrieve the current configuration, use therecommenders.getConfigmethod and specifygoogle.compute.RightSizeResourceRecommender as theRecommender ID:
GET https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.RightSizeResourceRecommender/config
Replace the following:
PROJECT_ID: the ID of the project for which youwant to modify the recommender configuration.ZONE: the zone that contains your project.
From the command line, execute the following command to get the recommenderconfiguration for a project:
PROJECT_ID=PROJECT_IDZONE=ZONEcurl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \-H "x-goog-user-project: ${PROJECT_ID}" \https://recommender.googleapis.com/v1/projects/$PROJECT_ID/locations/$ZONE/recommenders/google.compute.RightSizeResourceRecommender/configThe command returns the recommender configuration, including the subfieldsthat you can modify:params.under_utilized_reservation_lookback_period andparams.under_utilized_reservation_utilization_threshold.
{ "name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.RightSizeResourceRecommender/config", "recommenderGenerationConfig": { "params": { "under_utilized_reservation_lookback_period": "P7D", "under_utilized_reservation_utilization_threshold": "0.8" } }, "etag": "\"2f3c9b65cda6a4ba\"", "updateTime": "2024-06-03T04:41:15.330351Z"}updateTimeparameter.Update the configuration for a project
To update the configuration of your underutilized reservation recommendations, modify thevalue forunder_utilized_reservation_lookback_period and upload the newconfiguration for your project.
You can set the observation period to a value of 7 days up to 30 days, usinga string beginning withP, then an integer for the number of days (7 minimumand30 maximum), followed byD, for example:
- For an observation period of 7 days, use
"P7D". - For an observation period of 30 days, use
"P30D".
Similarly, set the usage threshold that triggers an underutilized reservationrecommendation by modifying the value forunder_utilized_reservation_utilization_threshold and upload the newconfiguration for your project, for example:
- For a threshold of 80%,
"0.8".
After you upload the new configuration, it takes approximately 48 hours for itto take effect. Until that time, any generated recommendations use the previousconfiguration.
Permissions required for this task
To perform this task, you must have the followingpermissions:
recommender.computeRightSizeResourceRecommender.geton the project to view the configuration.recommender.computeRightSizeResourceRecommender.updateon the project to modify the configuration.
Complete this task using one of the following methods.
gcloud
To update the configuration parameters, use thegcloud recommender recommender-config update commandand usegoogle.compute.RightSizeResourceRecommender as theRecommender ID:
gcloud recommender recommender-config update google.compute.RightSizeResourceRecommender\ --location=ZONE \ --config-file=CONFIG_FILE_PATH \ --etag=ETAG \ --billing-account=BILLING_ACCOUNT_ID
Replace the following:
ZONE: the zone for which you want to obtain thecurrent configurationCONFIG_FILE_PATH: the path to the JSON file withthe current configurationETAG: the etag value of the current configurationBILLING_ACCOUNT_ID: the ID of the billing account
In your configuration file, specify only therecommenderGenerationConfigobject with the updated configuration parameters. For example, to specifyan observation period of 21 days and the underutilized reservation thresholdto 80%, use the following configuration file:
{ "params": { "under_utilized_reservation_lookback_period": "P21D", "under_utilized_reservation_utilization_threshold": "0.8" }}If the command is successful, it returns a response body similar to thefollowing, showing the new configuration with the parameters you justmodified.
{ "name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.RightSizeResourceRecommender/config", "recommenderGenerationConfig": { "params": { "under_utilized_reservation_lookback_period": "P21D", "under_utilized_reservation_utilization_threshold": "0.8" } }, "etag": "\"1245f9435cd01ea8\"", "updateTime": "2024-06-03T05:00:05Z"}etag value changes from the previous configuration. Youmust use the new value if you update the configuration again.REST
To update the configuration, make aPATCH request to therecommenders.updateConfigmethod and specifygoogle.compute.RightSizeResourceRecommender as theRecommender ID:
PATCH https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.RightSizeResourceRecommender/config{ "name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.RightSizeResourceRecommender/config", "recommenderGenerationConfig": { "params": { "under_utilized_reservation_lookback_period": "P21D", "under_utilized_reservation_utilization_threshold": "0.8" } }, "etag": "\"2f3c9b65cda6a4ba\""}Replace the following:
PROJECT_ID: the ID of the project for which youwant to modify the recommender configuration.ZONE: the zone that contains your project.
Save the request body in a file, for exampleconfig.json.You can then reference the file when you update the recommender configurationfor your project, using a command similar to the following:
curl -X PATCH \-H "Authorization: Bearer $(gcloud auth print-access-token)" \-H "Content-Type: application/json; charset=utf-8" \-H "x-goog-user-project: ${PROJECT_ID}" \-d @config.json \https://recommender.googleapis.com/v1/projects/$PROJECT_ID/locations/$ZONE/recommenders/google.compute.RightSizeResourceRecommender/configThePOST command returns a response body similar to the following, showingthe new configuration with the parameters you just modified.
{ "name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.RightSizeResourceRecommender/config", "recommenderGenerationConfig": { "params": { "under_utilized_reservation_lookback_period": "P21D", "under_utilized_reservation_utilization_threshold": "0.8" } }, "etag": "\"1245f9435cd01ea8\"", "updateTime": "2024-06-03T05:00:05Z"}etag value changes from the previous configuration. Youmust use the new value if you update the configuration again.What's next
- Learn how toview and apply idle reservation recommendations.
- Learn how toview and apply underutilized reservation recommendations.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-18 UTC.