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.iamPolicyInsights.get
  • recommender.iamServiceAccountInsights.get

For more information, see the IAM documentation.
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.iamPolicyRecommendations.get

For more information, see the IAM documentation.
ListInsights

rpc ListInsights(ListInsightsRequest) returns (ListInsightsResponse)

Lists insights for a Cloud project. 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 one of the following IAM permissions on the parent resource, depending on the resource type:

  • 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 a Cloud project. 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 one of the following IAM permissions on the parent resource, depending on the resource type:

  • 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.iamPolicyInsights.update
  • recommender.iamServiceAccountInsights.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.iamPolicyRecommendations.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.iamPolicyRecommendations.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.iamPolicyRecommendations.update

For more information, see the IAM documentation.

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.
duration

Duration

Duration for which this cost applies.

GetInsightRequest

Request to the GetInsight method.

Fields
name

string

Required. Name of the insight.

GetRecommendationRequest

Request to the GetRecommendation method.

Fields
name

string

Required. Name of the recommendation.

Impact

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

Fields
category

Category

Category that is being targeted.
cost_projection

CostProjection

Use with CategoryType.COST

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.

Insight

An insight along with the information used to derive the insight. The insight may have associated recomendations 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.
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.

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]

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.

ListInsightsRequest

Request for the ListInsights method.

Fields
parent

string

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

1. "projects/[PROJECT_NUMBER]/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: state Eg: `state:"DISMISSED" or state:"ACTIVE"

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:

1. "projects/[PROJECT_NUMBER]/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 Eg: `state_info.state:"DISMISSED" or state_info.state:"FAILED"

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.

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 'and', '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 referes 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.
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.

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]

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.

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.

ValueMatcher

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

Fields
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