REST Resource: projects.locations.recommenders.recommendations

Resource: Recommendation

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

JSON representation 
{
  "name": string,
  "description": string,
  "recommenderSubtype": string,
  "lastRefreshTime": string,
  "primaryImpact": {
    object (Impact)
  },
  "additionalImpact": [
    {
      object (Impact)
    }
  ],
  "content": {
    object (RecommendationContent)
  },
  "stateInfo": {
    object (RecommendationStateInfo)
  },
  "etag": string,
  "associatedInsights": [
    {
      object (InsightReference)
    }
  ]
}
Fields
name

string

Name of recommendation.
description

string

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

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 primaryImpact.category are introduced. See the Recommenders section to see a list of subtypes for a given Recommender.

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

string (Timestamp format)

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

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".
primaryImpact

object (Impact)

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

object (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

object (RecommendationContent)

Content of the recommendation describing recommended changes to resources.
stateInfo

object (RecommendationStateInfo)

Information for state. Contains state and metadata.
etag

string

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

object (InsightReference)

Insights that led to this recommendation.

Impact

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

JSON representation 
{
  "category": enum (Category),
  "costProjection": {
    object (CostProjection)
  }
}
Fields
category

enum (Category)

Category that is being targeted.
costProjection

object (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.

CostProjection

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

JSON representation 
{
  "cost": {
    object (Money)
  },
  "duration": string
}
Fields
cost

object (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

string (Duration format)

Duration for which this cost applies.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

RecommendationContent

Contains what resources are changing and how they are changing.

JSON representation 
{
  "operationGroups": [
    {
      object (OperationGroup)
    }
  ]
}
Fields
operationGroups[]

object (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.

OperationGroup

Group of operations that need to be performed atomically.

JSON representation 
{
  "operations": [
    {
      object (Operation)
    }
  ]
}
Fields
operations[]

object (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.

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.
JSON representation 
{
  "action": string,
  "resourceType": string,
  "resource": string,
  "path": string,
  "sourceResource": string,
  "sourcePath": string,
  "pathFilters": {
    string: value,
    ...
  },
  "pathValueMatchers": {
    string: {
      object(ValueMatcher)
    },
    ...
  },

  // Union field path_value can be only one of the following:
  "value": value,
  "valueMatcher": {
    object (ValueMatcher)
  }
  // End of list of possible types for union field path_value.
}
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.
resourceType

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

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 = "/", sourceResource = and resourceName = . This field is empty for all other values of action.
sourcePath

string

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

map (key: string, value: value (Value format))

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

  • 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 pathFilters and pathValueMatchers are set, an implicit AND must be performed.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
pathValueMatchers

map (key: string, value: object (ValueMatcher))

Similar to pathFilters, 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 pathFilters. When both pathFilters and pathValueMatchers are set, an implicit AND must be performed.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
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 format)

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

object (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.

ValueMatcher

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

JSON representation 
{
  "matchesPattern": string
}
Fields
matchesPattern

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

RecommendationStateInfo

Information for state. Contains state and metadata.

JSON representation 
{
  "state": enum (State),
  "stateMetadata": {
    string: string,
    ...
  }
}
Fields
state

enum (State)

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

map (key: string, value: string)

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

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

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.

InsightReference

Reference to an associated insight.

JSON representation 
{
  "insight": string
}
Fields
insight

string

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

Methods

get

 Gets the requested recommendation.

list

 Lists recommendations for a Cloud project.

markClaimed

 Marks the Recommendation State as Claimed.

markFailed

 Marks the Recommendation State as Failed.

markSucceeded

 Marks the Recommendation State as Succeeded.