Configure idle reservation recommendations

This page describes how to view and modify the configuration of your idle, on-demand reservation recommendations. You might want to modify the configuration to increase the number of recommendations that you receive, or to get fewer recommendations to delete reservations that you plan to use.

Before you begin

  • If you haven't already, then set up authentication. Authentication is the process by which your identity is verified 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

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. 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, then initialize it by running the following command: 

      gcloud init

    For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Configure your recommendations

To configure your idle reservation recommendations, do the following:

  1. Get the current configuration to obtain the JSON file of the configuration.
  2. Edit the configuration file in JSON format.
  3. Upload the new configuration file to apply the changes.

Get the current configuration

You can obtain the current configuration for idle reservation recommendations for your project by using the Google Cloud CLI or REST.

Complete this task using one of the following methods.

gcloud

To get the current configuration parameters, use the gcloud recommender recommender-config describe command and use google.compute.IdleResourceRecommender as the Recommender ID:

gcloud recommender recommender-config describe google.compute.IdleResourceRecommender \
  --location=ZONE --billing-account=BILLING_ACCOUNT_ID

Replace ZONE with the zone for which you want to get the current configuration.

For example:

gcloud recommender recommender-config describe google.compute.IdleResourceRecommender \
  --location=us-central1-c --billing-account=my-billing-account-id

The command returns the recommender configuration, including the modifiable subfield params.idle_reservation_lookback_period.

{
  "name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.IdleResourceRecommender/config",
  "recommenderGenerationConfig": {
    "params": {
      "idle_reservation_lookback_period": "P7D"
    }
  },
  "etag": "\"2f3c9b65cda6a4ba\"",
  "updateTime": "2024-06-03T04:41:15.330351Z"
}

REST

To retrieve the current configuration, use the recommenders.getConfig method and specify google.compute.IdleResourceRecommender as the Recommender ID:

GET https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.IdleResourceRecommender/config

Replace ZONE with the zone that contains your project.

From the command line, execute the following command to get the recommender configuration for a project:

PROJECT_ID=PROJECT_ID
ZONE=ZONE
curl -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.IdleResourceRecommender/config

The command returns the recommender configuration, including the subfield that you can modify: params.idle_reservation_lookback_period.

{
  "name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.IdleResourceRecommender/config",
  "recommenderGenerationConfig": {
    "params": {
      "idle_reservation_lookback_period": "P7D"
    }
  },
  "etag": "\"2f3c9b65cda6a4ba\"",
  "updateTime": "2024-06-03T04:41:15.330351Z"
}

Update the configuration for a project

To update the configuration of your idle reservation recommendations, modify the value for idle_reservation_lookback_period and upload the new configuration for your project.

You can set the observation period to a value of 7 days up to 30 days, using a string beginning with P, then an integer for the number of days (7 minimum and 30 maximum), followed by D, for example:

  • For an observation period of 7 days, use "P7D".
  • For an observation period of 30 days, use "P30D".

After you upload the new configuration, it takes approximately 48 hours for it to take effect. Until that time, any generated recommendations use the previous configuration.

gcloud

To update the configuration parameters, use the gcloud recommender recommender-config update command and use google.compute.IdleResourceRecommender as the Recommender ID:

gcloud recommender recommender-config update google.compute.IdleResourceRecommender\
  --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 the current configuration
  • CONFIG_FILE_PATH: the path to the JSON file with the current configuration
  • ETAG: the etag value of the current configuration
  • BILLING_ACCOUNT_ID: the ID of the billing account

In your configuration file, specify only the recommenderGenerationConfig object with the updated configuration parameters. For example, to specify an observation period of 21 days, use the following configuration file:

{
  "params": {
    "idle_reservation_lookback_period": "P21D"
  }
}

If the command is successful, it returns a response body similar to the following, showing the new configuration with the parameters you just modified.

{
  "name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.IdleResourceRecommender/config",
  "recommenderGenerationConfig": {
    "params": {
      "idle_reservation_lookback_period": "P21D"
    }
  },
  "etag": "\"1245f9435cd01ea8\"",
  "updateTime": "2024-06-03T05:00:05Z"
}

REST

To update the configuration, make a PATCH request to the recommenders.updateConfig method and specify google.compute.IdleResourceRecommender as the Recommender ID:

PATCH https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.IdleResourceRecommender/config

{
  "name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.IdleResourceRecommender/config",
  "recommenderGenerationConfig": {
    "params": {
      "idle_reservation_lookback_period": "P21D"
    }
  },
  "etag": "\"2f3c9b65cda6a4ba\""
}

Replace the following:

  • PROJECT_ID: the ID of the project for which you want to modify the recommender configuration.
  • ZONE: the zone that contains your project.

Save the request body in a file, for example config.json. You can then reference the file when you update the recommender configuration for 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.IdleResourceRecommender/config

The POST command returns a response body similar to the following, showing the new configuration with the parameters you just modified.

{
  "name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.IdleResourceRecommender/config",
  "recommenderGenerationConfig": {
    "params": {
      "idle_reservation_lookback_period": "P21D"
    }
  },
  "etag": "\"1245f9435cd01ea8\"",
  "updateTime": "2024-06-03T05:00:05Z"
}

What's next