Package google.cloud.recommender.v1

Index

Recommender

Provides insights and recommendations for cloud customers for various categories like performance optimization, cost savings, reliability, feature discovery, etc. Insights and recommendations are generated automatically based on analysis of user resources, configuration and monitoring metrics.

GetInsight

rpc GetInsight(GetInsightRequest) returns (Insight)

Gets the requested insight. Requires the recommender.*.get IAM permission for the specified insight type.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires one of the following IAM permissions on the name resource, depending on the resource type:

  • recommender.commitmentUtilizationInsights.get
  • recommender.computeAddressIdleResourceInsights.get
  • recommender.computeDiskIdleResourceInsights.get
  • recommender.computeFirewallInsights.get
  • recommender.computeImageIdleResourceInsights.get
  • recommender.containerDiagnosisInsights.get
  • recommender.iamPolicyInsights.get
  • recommender.iamServiceAccountInsights.get
  • recommender.resourcemanagerProjectUtilizationInsights.get

For more information, see the IAM documentation.
GetInsightTypeConfig

rpc GetInsightTypeConfig(GetInsightTypeConfigRequest) returns (InsightTypeConfig)

Gets the requested InsightTypeConfig. There is only one instance of the config for each InsightType.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetRecommendation

rpc GetRecommendation(GetRecommendationRequest) returns (Recommendation)

Gets the requested recommendation. Requires the recommender.*.get IAM permission for the specified recommender.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires one of the following IAM permissions on the name resource, depending on the resource type:

  • recommender.usageCommitmentRecommendations.get
  • recommender.computeAddressIdleResourceRecommendations.get
  • recommender.computeDiskIdleResourceRecommendations.get
  • recommender.computeImageIdleResourceRecommendations.get
  • recommender.computeInstanceGroupManagerMachineTypeRecommendations.get
  • recommender.computeInstanceIdleResourceRecommendations.get
  • recommender.computeInstanceMachineTypeRecommendations.get
  • recommender.containerDiagnosisRecommendations.get
  • recommender.iamPolicyRecommendations.get
  • recommender.resourcemanagerProjectUtilizationRecommendations.get

For more information, see the IAM documentation.
GetRecommenderConfig

rpc GetRecommenderConfig(GetRecommenderConfigRequest) returns (RecommenderConfig)

Gets the requested Recommender Config. There is only one instance of the config for each Recommender.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ListInsights

rpc ListInsights(ListInsightsRequest) returns (ListInsightsResponse)

Lists insights for the specified Cloud Resource. Requires the recommender.*.list IAM permission for the specified insight type.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permissions on the parent resource:

  • recommender.commitmentUtilizationInsights.list
  • recommender.computeAddressIdleResourceInsights.list
  • recommender.computeDiskIdleResourceInsights.list
  • recommender.computeFirewallInsights.list
  • recommender.computeImageIdleResourceInsights.list
  • recommender.iamPolicyInsights.list
  • recommender.iamServiceAccountInsights.list

For more information, see the IAM documentation.
ListRecommendations

rpc ListRecommendations(ListRecommendationsRequest) returns (ListRecommendationsResponse)

Lists recommendations for the specified Cloud Resource. Requires the recommender.*.list IAM permission for the specified recommender.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permissions on the parent resource:

  • recommender.usageCommitmentRecommendations.list
  • recommender.computeAddressIdleResourceRecommendations.list
  • recommender.computeDiskIdleResourceRecommendations.list
  • recommender.computeImageIdleResourceRecommendations.list
  • recommender.computeInstanceGroupManagerMachineTypeRecommendations.list
  • recommender.computeInstanceIdleResourceRecommendations.list
  • recommender.computeInstanceMachineTypeRecommendations.list
  • recommender.iamPolicyRecommendations.list

For more information, see the IAM documentation.
MarkInsightAccepted

rpc MarkInsightAccepted(MarkInsightAcceptedRequest) returns (Insight)

Marks the Insight State as Accepted. Users can use this method to indicate to the Recommender API that they have applied some action based on the insight. This stops the insight content from being updated.

MarkInsightAccepted can be applied to insights in ACTIVE state. Requires the recommender.*.update IAM permission for the specified insight.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires one of the following IAM permissions on the name resource, depending on the resource type:

  • recommender.commitmentUtilizationInsights.update
  • recommender.computeAddressIdleResourceInsights.update
  • recommender.computeDiskIdleResourceInsights.update
  • recommender.computeFirewallInsights.update
  • recommender.computeImageIdleResourceInsights.update
  • recommender.containerDiagnosisInsights.update
  • recommender.iamPolicyInsights.update
  • recommender.iamServiceAccountInsights.update
  • recommender.resourcemanagerProjectUtilizationInsights.update

For more information, see the IAM documentation.
MarkRecommendationClaimed

rpc MarkRecommendationClaimed(MarkRecommendationClaimedRequest) returns (Recommendation)

Marks the Recommendation State as Claimed. Users can use this method to indicate to the Recommender API that they are starting to apply the recommendation themselves. This stops the recommendation content from being updated. Associated insights are frozen and placed in the ACCEPTED state.

MarkRecommendationClaimed can be applied to recommendations in CLAIMED, SUCCEEDED, FAILED, or ACTIVE state.

Requires the recommender.*.update IAM permission for the specified recommender.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires one of the following IAM permissions on the name resource, depending on the resource type:

  • recommender.usageCommitmentRecommendations.update
  • recommender.computeAddressIdleResourceRecommendations.update
  • recommender.computeDiskIdleResourceRecommendations.update
  • recommender.computeImageIdleResourceRecommendations.update
  • recommender.computeInstanceGroupManagerMachineTypeRecommendations.update
  • recommender.computeInstanceIdleResourceRecommendations.update
  • recommender.computeInstanceMachineTypeRecommendations.update
  • recommender.containerDiagnosisRecommendations.update
  • recommender.iamPolicyRecommendations.update
  • recommender.resourcemanagerProjectUtilizationRecommendations.update

For more information, see the IAM documentation.
MarkRecommendationDismissed

rpc MarkRecommendationDismissed(MarkRecommendationDismissedRequest) returns (Recommendation)

Mark the Recommendation State as Dismissed. Users can use this method to indicate to the Recommender API that an ACTIVE recommendation has to be marked back as DISMISSED.

MarkRecommendationDismissed can be applied to recommendations in ACTIVE state.

Requires the recommender.*.update IAM permission for the specified recommender.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires one of the following IAM permissions on the name resource, depending on the resource type:

  • recommender.usageCommitmentRecommendations.update
  • recommender.computeAddressIdleResourceRecommendations.update
  • recommender.computeDiskIdleResourceRecommendations.update
  • recommender.computeImageIdleResourceRecommendations.update
  • recommender.computeInstanceGroupManagerMachineTypeRecommendations.update
  • recommender.computeInstanceIdleResourceRecommendations.update
  • recommender.computeInstanceMachineTypeRecommendations.update
  • recommender.containerDiagnosisRecommendations.update
  • recommender.iamPolicyRecommendations.update
  • recommender.resourcemanagerProjectUtilizationRecommendations.update

For more information, see the IAM documentation.
MarkRecommendationFailed

rpc MarkRecommendationFailed(MarkRecommendationFailedRequest) returns (Recommendation)

Marks the Recommendation State as Failed. Users can use this method to indicate to the Recommender API that they have applied the recommendation themselves, and the operation failed. This stops the recommendation content from being updated. Associated insights are frozen and placed in the ACCEPTED state.

MarkRecommendationFailed can be applied to recommendations in ACTIVE, CLAIMED, SUCCEEDED, or FAILED state.

Requires the recommender.*.update IAM permission for the specified recommender.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires one of the following IAM permissions on the name resource, depending on the resource type:

  • recommender.usageCommitmentRecommendations.update
  • recommender.computeAddressIdleResourceRecommendations.update
  • recommender.computeDiskIdleResourceRecommendations.update
  • recommender.computeImageIdleResourceRecommendations.update
  • recommender.computeInstanceGroupManagerMachineTypeRecommendations.update
  • recommender.computeInstanceIdleResourceRecommendations.update
  • recommender.computeInstanceMachineTypeRecommendations.update
  • recommender.containerDiagnosisRecommendations.update
  • recommender.iamPolicyRecommendations.update
  • recommender.resourcemanagerProjectUtilizationRecommendations.update

For more information, see the IAM documentation.
MarkRecommendationSucceeded

rpc MarkRecommendationSucceeded(MarkRecommendationSucceededRequest) returns (Recommendation)

Marks the Recommendation State as Succeeded. Users can use this method to indicate to the Recommender API that they have applied the recommendation themselves, and the operation was successful. This stops the recommendation content from being updated. Associated insights are frozen and placed in the ACCEPTED state.

MarkRecommendationSucceeded can be applied to recommendations in ACTIVE, CLAIMED, SUCCEEDED, or FAILED state.

Requires the recommender.*.update IAM permission for the specified recommender.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires one of the following IAM permissions on the name resource, depending on the resource type:

  • recommender.usageCommitmentRecommendations.update
  • recommender.computeAddressIdleResourceRecommendations.update
  • recommender.computeDiskIdleResourceRecommendations.update
  • recommender.computeImageIdleResourceRecommendations.update
  • recommender.computeInstanceGroupManagerMachineTypeRecommendations.update
  • recommender.computeInstanceIdleResourceRecommendations.update
  • recommender.computeInstanceMachineTypeRecommendations.update
  • recommender.containerDiagnosisRecommendations.update
  • recommender.iamPolicyRecommendations.update
  • recommender.resourcemanagerProjectUtilizationRecommendations.update

For more information, see the IAM documentation.
UpdateInsightTypeConfig

rpc UpdateInsightTypeConfig(UpdateInsightTypeConfigRequest) returns (InsightTypeConfig)

Updates an InsightTypeConfig change. This will create a new revision of the config.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
UpdateRecommenderConfig

rpc UpdateRecommenderConfig(UpdateRecommenderConfigRequest) returns (RecommenderConfig)

Updates a Recommender Config. This will create a new revision of the config.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

CostProjection

Contains metadata about how much money a recommendation can save or incur.

Fields
cost

Money

An approximate projection on amount saved or amount incurred. Negative cost units indicate cost savings and positive cost units indicate increase. See google.type.Money documentation for positive/negative units.

A user's permissions may affect whether the cost is computed using list prices or custom contract prices.
duration

Duration

Duration for which this cost applies.
cost_in_local_currency

Money

The approximate cost savings in the billing account's local currency.

GetInsightRequest

Request to the GetInsight method.

Fields
name

string

Required. Name of the insight.

GetInsightTypeConfigRequest

Request for the GetInsightTypeConfig` method.

Fields
name

string

Required. Name of the InsightTypeConfig to get.

Acceptable formats:

  • projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]/config

  • projects/[PROJECT_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]/config

  • organizations/[ORGANIZATION_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]/config

  • billingAccounts/[BILLING_ACCOUNT_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]/config

GetRecommendationRequest

Request to the GetRecommendation method.

Fields
name

string

Required. Name of the recommendation.

GetRecommenderConfigRequest

Request for the GetRecommenderConfig` method.

Fields
name

string

Required. Name of the Recommendation Config to get.

Acceptable formats:

  • projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/config

  • projects/[PROJECT_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/config

  • organizations/[ORGANIZATION_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/config

  • billingAccounts/[BILLING_ACCOUNT_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/config

Impact

Contains the impact a recommendation can have for a given category.

Fields
category

Category

Category that is being targeted.
Union field projection. Contains projections (if any) for this category. projection can be only one of the following:
cost_projection

CostProjection

Use with CategoryType.COST
security_projection

SecurityProjection

Use with CategoryType.SECURITY
sustainability_projection

SustainabilityProjection

Use with CategoryType.SUSTAINABILITY
reliability_projection

ReliabilityProjection

Use with CategoryType.RELIABILITY

Category

The category of the impact.

Enums
CATEGORY_UNSPECIFIED Default unspecified category. Don't use directly.
COST Indicates a potential increase or decrease in cost.
SECURITY Indicates a potential increase or decrease in security.
PERFORMANCE Indicates a potential increase or decrease in performance.
MANAGEABILITY Indicates a potential increase or decrease in manageability.
SUSTAINABILITY Indicates a potential increase or decrease in sustainability.
RELIABILITY Indicates a potential increase or decrease in reliability.

Insight

An insight along with the information used to derive the insight. The insight may have associated recommendations as well.

Fields
name

string

Name of the insight.
description

string

Free-form human readable summary in English. The maximum length is 500 characters.
target_resources[]

string

Fully qualified resource names that this insight is targeting.
insight_subtype

string

Insight subtype. Insight content schema will be stable for a given subtype.
content

Struct

A struct of custom fields to explain the insight. Example: "grantedPermissionsCount": "1000"
last_refresh_time

Timestamp

Timestamp of the latest data used to generate the insight.
observation_period

Duration

Observation period that led to the insight. The source data used to generate the insight ends at last_refresh_time and begins at (last_refresh_time - observation_period).
state_info

InsightStateInfo

Information state and metadata.
category

Category

Category being targeted by the insight.
severity

Severity

Insight's severity.
etag

string

Fingerprint of the Insight. Provides optimistic locking when updating states.
associated_recommendations[]

RecommendationReference

Recommendations derived from this insight.

Category

Insight category.

Enums
CATEGORY_UNSPECIFIED Unspecified category.
COST The insight is related to cost.
SECURITY The insight is related to security.
PERFORMANCE The insight is related to performance.
MANAGEABILITY This insight is related to manageability.
SUSTAINABILITY The insight is related to sustainability.
RELIABILITY This insight is related to reliability.

RecommendationReference

Reference to an associated recommendation.

Fields
recommendation

string

Recommendation resource name, e.g. projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/recommendations/[RECOMMENDATION_ID]

Severity

Insight severity levels.

Enums
SEVERITY_UNSPECIFIED Insight has unspecified severity.
LOW Insight has low severity.
MEDIUM Insight has medium severity.
HIGH Insight has high severity.
CRITICAL Insight has critical severity.

InsightStateInfo

Information related to insight state.

Fields
state

State

Insight state.
state_metadata

map<string, string>

A map of metadata for the state, provided by user or automations systems.

State

Represents insight state.

Enums
STATE_UNSPECIFIED Unspecified state.
ACTIVE Insight is active. Content for ACTIVE insights can be updated by Google. ACTIVE insights can be marked DISMISSED OR ACCEPTED.
ACCEPTED Some action has been taken based on this insight. Insights become accepted when a recommendation derived from the insight has been marked CLAIMED, SUCCEEDED, or FAILED. ACTIVE insights can also be marked ACCEPTED explicitly. Content for ACCEPTED insights is immutable. ACCEPTED insights can only be marked ACCEPTED (which may update state metadata).
DISMISSED Insight is dismissed. Content for DISMISSED insights can be updated by Google. DISMISSED insights can be marked as ACTIVE.

InsightTypeConfig

Configuration for an InsightType.

Fields
name

string

Name of insight type config. Eg, projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]/config
insight_type_generation_config

InsightTypeGenerationConfig

InsightTypeGenerationConfig which configures the generation of insights for this insight type.
etag

string

Fingerprint of the InsightTypeConfig. Provides optimistic locking when updating.
update_time

Timestamp

Last time when the config was updated.
revision_id

string

Output only. Immutable. The revision ID of the config. A new revision is committed whenever the config is changed in any way. The format is an 8-character hexadecimal string.
annotations

map<string, string>

Allows clients to store small amounts of arbitrary data. Annotations must follow the Kubernetes syntax. The total size of all keys and values combined is limited to 256k. Key can have 2 segments: prefix (optional) and name (required), separated by a slash (/). Prefix must be a DNS subdomain. Name must be 63 characters or less, begin and end with alphanumerics, with dashes (-), underscores (_), dots (.), and alphanumerics between.
display_name

string

A user-settable field to provide a human-readable name to be used in user interfaces.

InsightTypeGenerationConfig

A configuration to customize the generation of insights. Eg, customizing the lookback period considered when generating a insight.

Fields
params

Struct

Parameters for this InsightTypeGenerationConfig. These configs can be used by or are applied to all subtypes.

ListInsightsRequest

Request for the ListInsights method.

Fields
parent

string

Required. The container resource on which to execute the request. Acceptable formats:

  • projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]

  • projects/[PROJECT_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]

  • billingAccounts/[BILLING_ACCOUNT_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]

  • folders/[FOLDER_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]

  • organizations/[ORGANIZATION_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]

LOCATION here refers to GCP Locations: https://cloud.google.com/about/locations/ INSIGHT_TYPE_ID refers to supported insight types: https://cloud.google.com/recommender/docs/insights/insight-types.
page_size

int32

Optional. The maximum number of results to return from this request. Non-positive values are ignored. If not specified, the server will determine the number of results to return.
page_token

string

Optional. If present, retrieves the next batch of results from the preceding call to this method. page_token must be the value of next_page_token from the previous response. The values of other method parameters must be identical to those in the previous call.
filter

string

Optional. Filter expression to restrict the insights returned. Supported filter fields:

  • stateInfo.state

  • insightSubtype

  • severity

  • targetResources

Examples:

  • stateInfo.state = ACTIVE OR stateInfo.state = DISMISSED

  • insightSubtype = PERMISSIONS_USAGE

  • severity = CRITICAL OR severity = HIGH

  • targetResources : //compute.googleapis.com/projects/1234/zones/us-central1-a/instances/instance-1

  • stateInfo.state = ACTIVE AND (severity = CRITICAL OR severity = HIGH)

The max allowed filter length is 500 characters.

(These expressions are based on the filter language described at https://google.aip.dev/160)

ListInsightsResponse

Response to the ListInsights method.

Fields
insights[]

Insight

The set of insights for the parent resource.
next_page_token

string

A token that can be used to request the next page of results. This field is empty if there are no additional results.

ListRecommendationsRequest

Request for the ListRecommendations method.

Fields
parent

string

Required. The container resource on which to execute the request. Acceptable formats:

  • projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]

  • projects/[PROJECT_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]

  • billingAccounts/[BILLING_ACCOUNT_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]

  • folders/[FOLDER_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]

  • organizations/[ORGANIZATION_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]

LOCATION here refers to GCP Locations: https://cloud.google.com/about/locations/ RECOMMENDER_ID refers to supported recommenders: https://cloud.google.com/recommender/docs/recommenders.
page_size

int32

Optional. The maximum number of results to return from this request. Non-positive values are ignored. If not specified, the server will determine the number of results to return.
page_token

string

Optional. If present, retrieves the next batch of results from the preceding call to this method. page_token must be the value of next_page_token from the previous response. The values of other method parameters must be identical to those in the previous call.
filter

string

Filter expression to restrict the recommendations returned. Supported filter fields:

  • state_info.state

  • recommenderSubtype

  • priority

  • targetResources

Examples:

  • stateInfo.state = ACTIVE OR stateInfo.state = DISMISSED

  • recommenderSubtype = REMOVE_ROLE OR recommenderSubtype = REPLACE_ROLE

  • priority = P1 OR priority = P2

  • targetResources : //compute.googleapis.com/projects/1234/zones/us-central1-a/instances/instance-1

  • stateInfo.state = ACTIVE AND (priority = P1 OR priority = P2)

The max allowed filter length is 500 characters.

(These expressions are based on the filter language described at https://google.aip.dev/160)

ListRecommendationsResponse

Response to the ListRecommendations method.

Fields
recommendations[]

Recommendation

The set of recommendations for the parent resource.
next_page_token

string

A token that can be used to request the next page of results. This field is empty if there are no additional results.

MarkInsightAcceptedRequest

Request for the MarkInsightAccepted method.

Fields
name

string

Required. Name of the insight.
state_metadata

map<string, string>

Optional. State properties user wish to include with this state. Full replace of the current state_metadata.
etag

string

Required. Fingerprint of the Insight. Provides optimistic locking.

MarkRecommendationClaimedRequest

Request for the MarkRecommendationClaimed Method.

Fields
name

string

Required. Name of the recommendation.
state_metadata

map<string, string>

State properties to include with this state. Overwrites any existing state_metadata. Keys must match the regex /^[a-z0-9][a-z0-9_.-]{0,62}$/. Values must match the regex /^[a-zA-Z0-9_./-]{0,255}$/.
etag

string

Required. Fingerprint of the Recommendation. Provides optimistic locking.

MarkRecommendationDismissedRequest

Request for the MarkRecommendationDismissed Method.

Fields
name

string

Required. Name of the recommendation.
etag

string

Fingerprint of the Recommendation. Provides optimistic locking.

MarkRecommendationFailedRequest

Request for the MarkRecommendationFailed Method.

Fields
name

string

Required. Name of the recommendation.
state_metadata

map<string, string>

State properties to include with this state. Overwrites any existing state_metadata. Keys must match the regex /^[a-z0-9][a-z0-9_.-]{0,62}$/. Values must match the regex /^[a-zA-Z0-9_./-]{0,255}$/.
etag

string

Required. Fingerprint of the Recommendation. Provides optimistic locking.

MarkRecommendationSucceededRequest

Request for the MarkRecommendationSucceeded Method.

Fields
name

string

Required. Name of the recommendation.
state_metadata

map<string, string>

State properties to include with this state. Overwrites any existing state_metadata. Keys must match the regex /^[a-z0-9][a-z0-9_.-]{0,62}$/. Values must match the regex /^[a-zA-Z0-9_./-]{0,255}$/.
etag

string

Required. Fingerprint of the Recommendation. Provides optimistic locking.

Operation

Contains an operation for a resource loosely based on the JSON-PATCH format with support for:

  • Custom filters for describing partial array patch.
  • Extended path values for describing nested arrays.
  • Custom fields for describing the resource for which the operation is being described.
  • Allows extension to custom operations not natively supported by RFC6902. See https://tools.ietf.org/html/rfc6902 for details on the original RFC.
Fields
action

string

Type of this operation. Contains one of 'add', 'remove', 'replace', 'move', 'copy', 'test' and custom operations. This field is case-insensitive and always populated.
resource_type

string

Type of GCP resource being modified/tested. This field is always populated. Example: cloudresourcemanager.googleapis.com/Project, compute.googleapis.com/Instance
resource

string

Contains the fully qualified resource name. This field is always populated. ex: //cloudresourcemanager.googleapis.com/projects/foo.
path

string

Path to the target field being operated on. If the operation is at the resource level, then path should be "/". This field is always populated.
source_resource

string

Can be set with action 'copy' to copy resource configuration across different resources of the same type. Example: A resource clone can be done via action = 'copy', path = "/", from = "/", source_resource = and resource_name = . This field is empty for all other values of action.
source_path

string

Can be set with action 'copy' or 'move' to indicate the source field within resource or source_resource, ignored if provided for other operation types.
path_filters

map<string, Value>

Set of filters to apply if path refers to array elements or nested array elements in order to narrow down to a single unique element that is being tested/modified. This is intended to be an exact match per filter. To perform advanced matching, use path_value_matchers.

  • Example:
{
  "/versions/*/name" : "it-123"
  "/versions/*/targetSize/percent": 20
}
  • Example:
{
  "/bindings/*/role": "roles/owner"
  "/bindings/*/condition" : null
}
  • Example:
{
  "/bindings/*/role": "roles/owner"
  "/bindings/*/members/*" : ["x@example.com", "y@example.com"]
}

When both path_filters and path_value_matchers are set, an implicit AND must be performed.
path_value_matchers

map<string, ValueMatcher>

Similar to path_filters, this contains set of filters to apply if path field refers to array elements. This is meant to support value matching beyond exact match. To perform exact match, use path_filters. When both path_filters and path_value_matchers are set, an implicit AND must be performed.
Union field path_value. One of the fields in the following block will be set and intend to describe a value for 'path' field. path_value can be only one of the following:
value

Value

Value for the path field. Will be set for actions:'add'/'replace'. Maybe set for action: 'test'. Either this or value_matcher will be set for 'test' operation. An exact match must be performed.
value_matcher

ValueMatcher

Can be set for action 'test' for advanced matching for the value of 'path' field. Either this or value will be set for 'test' operation.

OperationGroup

Group of operations that need to be performed atomically.

Fields
operations[]

Operation

List of operations across one or more resources that belong to this group. Loosely based on RFC6902 and should be performed in the order they appear.

Recommendation

A recommendation along with a suggested action. E.g., a rightsizing recommendation for an underutilized VM, IAM role recommendations, etc

Fields
name

string

Name of recommendation.
description

string

Free-form human readable summary in English. The maximum length is 500 characters.
recommender_subtype

string

Contains an identifier for a subtype of recommendations produced for the same recommender. Subtype is a function of content and impact, meaning a new subtype might be added when significant changes to content or primary_impact.category are introduced. See the Recommenders section to see a list of subtypes for a given Recommender.

Examples: For recommender = "google.iam.policy.Recommender", recommender_subtype can be one of "REMOVE_ROLE"/"REPLACE_ROLE"
last_refresh_time

Timestamp

Last time this recommendation was refreshed by the system that created it in the first place.
primary_impact

Impact

The primary impact that this recommendation can have while trying to optimize for one category.
additional_impact[]

Impact

Optional set of additional impact that this recommendation may have when trying to optimize for the primary category. These may be positive or negative.
priority

Priority

Recommendation's priority.
content

RecommendationContent

Content of the recommendation describing recommended changes to resources.
state_info

RecommendationStateInfo

Information for state. Contains state and metadata.
etag

string

Fingerprint of the Recommendation. Provides optimistic locking when updating states.
associated_insights[]

InsightReference

Insights that led to this recommendation.
xor_group_id

string

Corresponds to a mutually exclusive group ID within a recommender. A non-empty ID indicates that the recommendation belongs to a mutually exclusive group. This means that only one recommendation within the group is suggested to be applied.

InsightReference

Reference to an associated insight.

Fields
insight

string

Insight resource name, e.g. projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]/insights/[INSIGHT_ID]

Priority

Recommendation priority levels.

Enums
PRIORITY_UNSPECIFIED Recommendation has unspecified priority.
P4 Recommendation has P4 priority (lowest priority).
P3 Recommendation has P3 priority (second lowest priority).
P2 Recommendation has P2 priority (second highest priority).
P1 Recommendation has P1 priority (highest priority).

RecommendationContent

Contains what resources are changing and how they are changing.

Fields
operation_groups[]

OperationGroup

Operations to one or more Google Cloud resources grouped in such a way that, all operations within one group are expected to be performed atomically and in an order.
overview

Struct

Condensed overview information about the recommendation.

RecommendationStateInfo

Information for state. Contains state and metadata.

Fields
state

State

The state of the recommendation, Eg ACTIVE, SUCCEEDED, FAILED.
state_metadata

map<string, string>

A map of metadata for the state, provided by user or automations systems.

State

Represents Recommendation State.

Enums
STATE_UNSPECIFIED Default state. Don't use directly.
ACTIVE

Recommendation is active and can be applied. Recommendations content can be updated by Google.

ACTIVE recommendations can be marked as CLAIMED, SUCCEEDED, or FAILED.
CLAIMED

Recommendation is in claimed state. Recommendations content is immutable and cannot be updated by Google.

CLAIMED recommendations can be marked as CLAIMED, SUCCEEDED, or FAILED.
SUCCEEDED

Recommendation is in succeeded state. Recommendations content is immutable and cannot be updated by Google.

SUCCEEDED recommendations can be marked as SUCCEEDED, or FAILED.
FAILED

Recommendation is in failed state. Recommendations content is immutable and cannot be updated by Google.

FAILED recommendations can be marked as SUCCEEDED, or FAILED.
DISMISSED

Recommendation is in dismissed state. Recommendation content can be updated by Google.

DISMISSED recommendations can be marked as ACTIVE.

RecommenderConfig

Configuration for a Recommender.

Fields
name

string

Name of recommender config. Eg, projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/config
recommender_generation_config

RecommenderGenerationConfig

RecommenderGenerationConfig which configures the Generation of recommendations for this recommender.
etag

string

Fingerprint of the RecommenderConfig. Provides optimistic locking when updating.
update_time

Timestamp

Last time when the config was updated.
revision_id

string

Output only. Immutable. The revision ID of the config. A new revision is committed whenever the config is changed in any way. The format is an 8-character hexadecimal string.
annotations

map<string, string>

Allows clients to store small amounts of arbitrary data. Annotations must follow the Kubernetes syntax. The total size of all keys and values combined is limited to 256k. Key can have 2 segments: prefix (optional) and name (required), separated by a slash (/). Prefix must be a DNS subdomain. Name must be 63 characters or less, begin and end with alphanumerics, with dashes (-), underscores (_), dots (.), and alphanumerics between.
display_name

string

A user-settable field to provide a human-readable name to be used in user interfaces.

RecommenderGenerationConfig

A Configuration to customize the generation of recommendations. Eg, customizing the lookback period considered when generating a recommendation.

Fields
params

Struct

Parameters for this RecommenderGenerationConfig. These configs can be used by or are applied to all subtypes.

ReliabilityProjection

Contains information on the impact of a reliability recommendation.

Fields
risks[]

RiskType

Reliability risks mitigated by this recommendation.
details

Struct

Per-recommender projection.

RiskType

The risk associated with the reliability issue.

Enums
RISK_TYPE_UNSPECIFIED Default unspecified risk. Don't use directly.
SERVICE_DISRUPTION Potential service downtime.
DATA_LOSS Potential data loss.
ACCESS_DENY Potential access denial. The service is still up but some or all clients can't access it.

SecurityProjection

Contains various ways of describing the impact on Security.

Fields
details

Struct

Additional security impact details that is provided by the recommender.

SustainabilityProjection

Contains metadata about how much sustainability a recommendation can save or incur.

Fields
kg_c_o2e

double

Carbon Footprint generated in kg of CO2 equivalent. Chose kg_c_o2e so that the name renders correctly in camelCase (kgCO2e).
duration

Duration

Duration for which this sustainability applies.

UpdateInsightTypeConfigRequest

Request for the UpdateInsightTypeConfig method.

Fields
insight_type_config

InsightTypeConfig

Required. The InsightTypeConfig to update.
update_mask

FieldMask

The list of fields to be updated.
validate_only

bool

If true, validate the request and preview the change, but do not actually update it.

UpdateRecommenderConfigRequest

Request for the UpdateRecommenderConfig method.

Fields
recommender_config

RecommenderConfig

Required. The RecommenderConfig to update.
update_mask

FieldMask

The list of fields to be updated.
validate_only

bool

If true, validate the request and preview the change, but do not actually update it.

ValueMatcher

Contains various matching options for values for a GCP resource field.

Fields

Union field match_variant.

match_variant can be only one of the following:
matches_pattern

string

To be used for full regex matching. The regular expression is using the Google RE2 syntax (https://github.com/google/re2/wiki/Syntax), so to be used with RE2::FullMatch