Configure machine type recommendations

This page describes how to view and modify the configuration of your machine type recommendations. You can modify which machine types are recommended, so the generated recommendations only include your preferred machine series. You can also change the metrics used to generate memory recommendations to improve the accuracy of the recommendations. The changes to the configuration are applied at the project level.

For more information about machine type recommendations, see Apply machine type recommendations for VMs.

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:
1. Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.

Required roles

To get the permissions that you need to modify machine type recommendations, ask your administrator to grant you the Compute Recommender Admin (roles/recommender.computeAdmin) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to modify machine type recommendations. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to modify machine type recommendations:

View the machine type recommendation configuration: recommender.computeInstanceMachineTypeRecommenderConfig.get on the project
Modify the machine type recommendation configuration: recommender.computeInstanceMachineTypeRecommenderConfig.update on the project

You might also be able to get these permissions with custom roles or other predefined roles.

Configure your recommendations

To configure your machine type 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 machine type recommendations for your project by using the Google Cloud CLI.

gcloud

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

gcloud beta recommender recommender-config describe google.compute.instance.MachineTypeRecommender \
  --project=PROJECT_ID \
  --location=ZONE

Replace the following:

PROJECT_ID: the ID of your project.
ZONE: the zone for which you want to obtain the current configuration.

The command returns the recommender configuration, including the modifiable subfields preferred_machine_types and memory_metrics.

{
  "name": "projects/PROJECT_ID/locations/ZONE/recommenders/google.compute.instance.MachineTypeRecommender/config",
  "recommenderGenerationConfig": {
    "params": {
      "preferred_machine_types": "STANDARD_AND_CUSTOM",
      "memory_metrics": "MONITORING_AGENT_ONLY"
    }
  },
  "etag": "\"2f3c9b65cda6a4ba\"",
  "updateTime": "2024-08-20T04:41:15.330351Z"
}

If you want to save the configuration to a local file, so you can edit it and upload it later, run the following command:

gcloud beta recommender recommender-config describe \
  google.compute.instance.MachineTypeRecommender \
  --project=PROJECT_ID \
  --location=ZONE > LOCAL_FILE_PATH_AND_NAME

Edit the recommendation configuration

The configuration lets you customize the following parameters:

preferred_machine_types: The machine types recommendations that you receive.
memory_metrics: How memory metrics are used to generate recommendations.

Options for machine types recommendations

You can specify which machine types recommendations you get by changing the preferred_machine_types setting to one of the following values:

DEFAULT: The default value is STANDARD_AND_CUSTOM.
STANDARD_AND_CUSTOM: Recommends the best match from standard and custom machine types.
STANDARD_ONLY: Recommends the best match from standard machine types only.

Options for memory recommendations

For the memory metrics used to generate the recommendations, you can set the following values:

MEMORY_METRICS_DEFAULT: Use the default metrics to generate recommendations.
MEMORY_METRICS_ALL: Use all the available metrics to generate recommendations.
MONITORING_AGENT_ONLY: Use only metrics collected by the Cloud Monitoring Ops Agent.
If you don't use the Ops Agent, and prefer not to receive memory recommendations, use the MEMORY_AGENT_ONLY value to disable the recommendations.

To get more accurate recommendations about memory usage, use the Ops Agent.

Update the configuration for a project

To update the configuration of your machine type recommendations, modify the configuration values and upload the new configuration for your project. You can change the preferred machine types, the memory metrics used for recommendations, or both values in the same request.

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 beta recommender recommender-config update command and use google.compute.instance.MachineTypeRecommender as the Recommender ID:

gcloud beta recommender recommender-config update google.compute.instance.MachineTypeRecommender\
  --project=PROJECT_ID \
  --location=ZONE \
  --config-file=LOCAL_FILE_PATH_AND_NAME \
  --etag=ETAG

Replace the following:

PROJECT_ID: the ID of your project.
ZONE: the zone for which you want to obtain the current configuration.
LOCAL_FILE_PATH_AND_NAME: the path to the JSON file with the current configuration.
ETAG: the etag value of the current configuration. You can find this value in the output of the previous command.

In your configuration file, specify only the recommenderGenerationConfig object with the updated configuration parameters. If you saved the configuration to a local file, make sure you copy the etag value, then remove all the fields except the recommenderGenerationConfig value.

For example, to get recommendations with standard machine types only, use the following configuration file:

{
  "params": {
    "preferred_machine_types": "STANDARD_ONLY"
  }
}

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.MachineTypeRecommender/config",
  "recommenderGenerationConfig": {
    "params": {
      "preferred_machine_types": "STANDARD_ONLY"
    }
  },
  "etag": "\"1245f9435cd01ea8\"",
  "updateTime": "2024-08-20T05:00:05Z"
}

What's next

Learn how to Apply machine type recommendations to instances.
Learn how to Apply machine type recommendations to managed instance groups.