![[Google Cloud Documentation]](https://www.gstatic.com/devrel-devsite/prod/v0f3a5b8b76e4a120372a69044e02756e703b6140f9f1812c6e4a0407b19864b7/clouddocs/images/lockup_full_color.svg){kind=link}
![[]](https://docs.cloud.google.com/_static/clouddocs/images/icons/products/compute-engine-color.svg){kind=link}
Preview
This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.
This page describes how to view and modify the configuration of your idle VM recommendations. You might want to modify the configuration to increase the number of recommendations that you receive or to avoid misclassifying VMs with intentionally small workloads as idle VMs.
- For more information on the parameters you can use to customize the recommendations, see Choose the right configuration parameters.
- For more information on how to identify idle VMs and take action, see View and apply idle VM recommendations.
Before you begin
-
If you haven't already, set up authentication.
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:
gcloud initIf 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.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
-
Pricing
Configurable recommendations are available free of charge. Using recommendations to reduce your resource usage can result in cost savings.
Configure your recommendations
To configure your idle VM recommendations, perform the following steps:
- Get the current configuration to obtain the JSON file of the configuration.
- Edit the configuration file in JSON format.
- Upload the new configuration file to apply the changes.
Get the current configuration
You can obtain the current configuration for idle VM recommendations for your project by using the Google Cloud CLI or REST.
Permissions required for this task
To perform this task, you must have the following permissions:
recommender.computeInstanceIdleResourceRecommenderConfig.geton the project.
gcloud
To get the current configuration parameters, use the
gcloud recommender recommender-config describe
command and use google.compute.instance.IdleResourceRecommender as the
Recommender ID:
gcloud recommender recommender-config describe google.compute.instance.IdleResourceRecommender \ --project=PROJECT_ID \ --location=ZONE
Replace the following:
PROJECT_ID: the ID of your projectZONE: the zone for which you want to obtain the current configuration
For example:
gcloud recommender recommender-config describe google.compute.instance.IdleResourceRecommender \ --project=my-project \ --location=us-central1-c
The command returns the recommender configuration, including the modifiable
subfield params.observation_period.
{
"name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.instance.IdleResourceRecommender/config",
"recommenderGenerationConfig": {
"params": {
"observation_period": "1209600s"
}
},
"etag": "\"2f3c9b65cda6a4ba\"",
"updateTime": "2021-02-03T04:41:15.330351Z"
}
REST
To retrieve the current configuration, use the
recommenders.getConfig
method and specify google.compute.instance.IdleResourceRecommender as the
Recommender ID:
GET https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.instance.IdleResourceRecommender/config
Replace the following:
PROJECT_ID: the ID of the project for which you want to retrieve the recommender config.ZONE: 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.instance.IdleResourceRecommender/config
The command returns the recommender configuration, including the subfield
that you can modify: params.observation_period.
{
"name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.instance.IdleResourceRecommender/config",
"recommenderGenerationConfig": {
"params": {
"observation_period": "1209600s"
}
},
"etag": "\"2f3c9b65cda6a4ba\"",
"updateTime": "2021-02-03T04:41:15.330351Z"
}
Note: When you submit the new configuration, remove the updateTime
parameter.
Update the configuration for a project
To update the configuration of your idle VM recommendations, modify the value
for observation_period and upload the new configuration for your project.
You can set the observation period to a value between 1 day and 14 days, using
a string with the total number of seconds, followed by the letter s.
- For an observation period of 1 day, use
"86400s". - For an observation period of 14 days, use
"1209600s".
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.
Permissions required for this task
To perform this task, you must have the following permissions:
recommender.computeInstanceIdleResourceRecommenderConfig.geton the project to view the configuration.recommender.computeInstanceIdleResourceRecommenderConfig.updateon the project to modify the configuration.
gcloud
To update the configuration parameters, use the
gcloud recommender recommender-config update
command and use google.compute.instance.IdleResourceRecommender as the
Recommender ID:
gcloud recommender recommender-config update google.compute.instance.IdleResourceRecommender\ --project=PROJECT_ID \ --location=ZONE \ --config-file=CONFIG_FILE_PATH \ --etag=ETAG
Replace the following:
PROJECT_ID: the ID of your projectZONE: the zone for which you want to obtain the current configurationCONFIG_FILE_PATH: the path to the JSON file with the current configurationETAG: the etag value of the current configuration
In your configuration file, specify only the recommenderGenerationConfig
object with the updated configuration parameters. For example, to specify
an observation period of five days, use the following configuration file:
{
"params": {
"observation_period": "432000s"
}
}
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.instance.IdleResourceRecommender/config",
"recommenderGenerationConfig": {
"params": {
"observation_period": "432000s"
}
},
"etag": "\"1245f9435cd01ea8\"",
"updateTime": "2021-02-03T05:00:05Z"
}
Note: the etag value changes from the previous configuration. You
must use the new value if you update the configuration again.
REST
To update the configuration, use the
recommenders.updateConfig
method and specify google.compute.instance.IdleResourceRecommender as the
Recommender ID:
PATCH https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.instance.IdleResourceRecommender/config
{
"name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.instance.IdleResourceRecommender/config",
"recommenderGenerationConfig": {
"params": {
"observation_period": "1209600s"
}
},
"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.instance.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.instance.IdleResourceRecommender/config",
"recommenderGenerationConfig": {
"params": {
"observation_period": "432000s"
}
},
"etag": "\"1245f9435cd01ea8\"",
"updateTime": "2021-02-03T05:00:05Z"
}
Note: the etag value changes from the previous configuration. You
must use the new value if you update the configuration again.
What's next
- Learn how to view and apply idle VM recommendations.