Skip to content

Commit 2060f89

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: Recommendation Priority / Insight Severity
feat: Recommendation xor_group_id feat: Recommendation security projection Incorporate above new features, as well as update .bazel files. PiperOrigin-RevId: 424391246
1 parent 4b6b01f commit 2060f89

3 files changed

Lines changed: 138 additions & 25 deletions

File tree

‎google/cloud/recommender/v1/insight.proto‎

Lines changed: 29 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2020 Google LLC
1+
// Copyright 2022 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -46,13 +46,6 @@ message Insight {
4646
pattern: "organizations/{organization}/locations/{location}/insightTypes/{insight_type}/insights/{insight}"
4747
};
4848

49-
// Reference to an associated recommendation.
50-
message RecommendationReference {
51-
// Recommendation resource name, e.g.
52-
// projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/recommendations/[RECOMMENDATION_ID]
53-
string recommendation = 1;
54-
}
55-
5649
// Insight category.
5750
enum Category {
5851
// Unspecified category.
@@ -71,6 +64,31 @@ message Insight {
7164
MANAGEABILITY = 4;
7265
}
7366

67+
// Insight severity levels.
68+
enum Severity {
69+
// Insight has unspecified severity.
70+
SEVERITY_UNSPECIFIED = 0;
71+
72+
// Insight has low severity.
73+
LOW = 1;
74+
75+
// Insight has medium severity.
76+
MEDIUM = 2;
77+
78+
// Insight has high severity.
79+
HIGH = 3;
80+
81+
// Insight has critical severity.
82+
CRITICAL = 4;
83+
}
84+
85+
// Reference to an associated recommendation.
86+
message RecommendationReference {
87+
// Recommendation resource name, e.g.
88+
// projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/recommendations/[RECOMMENDATION_ID]
89+
string recommendation = 1;
90+
}
91+
7492
// Name of the insight.
7593
string name = 1;
7694

@@ -102,6 +120,9 @@ message Insight {
102120
// Category being targeted by the insight.
103121
Category category = 7;
104122

123+
// Insight's severity.
124+
Severity severity = 15;
125+
105126
// Fingerprint of the Insight. Provides optimistic locking when updating
106127
// states.
107128
string etag = 11;

‎google/cloud/recommender/v1/recommendation.proto‎

Lines changed: 45 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2020 Google LLC
1+
// Copyright 2022 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -46,6 +46,24 @@ message Recommendation {
4646
pattern: "organizations/{organization}/locations/{location}/recommenders/{recommender}/recommendations/{recommendation}"
4747
};
4848

49+
// Recommendation priority levels.
50+
enum Priority {
51+
// Recommendation has unspecified priority.
52+
PRIORITY_UNSPECIFIED = 0;
53+
54+
// Recommendation has P4 priority (lowest priority).
55+
P4 = 1;
56+
57+
// Recommendation has P3 priority (second lowest priority).
58+
P3 = 2;
59+
60+
// Recommendation has P2 priority (second highest priority).
61+
P2 = 3;
62+
63+
// Recommendation has P1 priority (highest priority).
64+
P1 = 4;
65+
}
66+
4967
// Reference to an associated insight.
5068
message InsightReference {
5169
// Insight resource name, e.g.
@@ -84,6 +102,9 @@ message Recommendation {
84102
// or negative.
85103
repeated Impact additional_impact = 6;
86104

105+
// Recommendation's priority.
106+
Priority priority = 17;
107+
87108
// Content of the recommendation describing recommended changes to resources.
88109
RecommendationContent content = 7;
89110

@@ -96,6 +117,12 @@ message Recommendation {
96117

97118
// Insights that led to this recommendation.
98119
repeated InsightReference associated_insights = 14;
120+
121+
// Corresponds to a mutually exclusive group ID within a recommender.
122+
// A non-empty ID indicates that the recommendation belongs to a mutually
123+
// exclusive group. This means that only one recommendation within the group
124+
// is suggested to be applied.
125+
string xor_group_id = 18;
99126
}
100127

101128
// Contains what resources are changing and how they are changing.
@@ -104,6 +131,9 @@ message RecommendationContent {
104131
// that, all operations within one group are expected to be performed
105132
// atomically and in an order.
106133
repeated OperationGroup operation_groups = 2;
134+
135+
// Condensed overview information about the recommendation.
136+
google.protobuf.Struct overview = 3;
107137
}
108138

109139
// Group of operations that need to be performed atomically.
@@ -123,7 +153,7 @@ message OperationGroup {
123153
// * Allows extension to custom operations not natively supported by RFC6902.
124154
// See https://tools.ietf.org/html/rfc6902 for details on the original RFC.
125155
message Operation {
126-
// Type of this operation. Contains one of 'and', 'remove', 'replace', 'move',
156+
// Type of this operation. Contains one of 'add', 'remove', 'replace', 'move',
127157
// 'copy', 'test' and custom operations. This field is case-insensitive and
128158
// always populated.
129159
string action = 1;
@@ -197,7 +227,7 @@ message Operation {
197227
map<string, google.protobuf.Value> path_filters = 8;
198228

199229
// Similar to path_filters, this contains set of filters to apply if `path`
200-
// field referes to array elements. This is meant to support value matching
230+
// field refers to array elements. This is meant to support value matching
201231
// beyond exact match. To perform exact match, use path_filters.
202232
// When both path_filters and path_value_matchers are set, an implicit AND
203233
// must be performed.
@@ -219,12 +249,21 @@ message CostProjection {
219249
// An approximate projection on amount saved or amount incurred. Negative cost
220250
// units indicate cost savings and positive cost units indicate increase.
221251
// See google.type.Money documentation for positive/negative units.
252+
//
253+
// A user's permissions may affect whether the cost is computed using list
254+
// prices or custom contract prices.
222255
google.type.Money cost = 1;
223256

224257
// Duration for which this cost applies.
225258
google.protobuf.Duration duration = 2;
226259
}
227260

261+
// Contains various ways of describing the impact on Security.
262+
message SecurityProjection {
263+
// Additional security impact details that is provided by the recommender.
264+
google.protobuf.Struct details = 2;
265+
}
266+
228267
// Contains the impact a recommendation can have for a given category.
229268
message Impact {
230269
// The category of the impact.
@@ -252,6 +291,9 @@ message Impact {
252291
oneof projection {
253292
// Use with CategoryType.COST
254293
CostProjection cost_projection = 100;
294+
295+
// Use with CategoryType.SECURITY
296+
SecurityProjection security_projection = 101;
255297
}
256298
}
257299

‎google/cloud/recommender/v1/recommender_service.proto‎

Lines changed: 64 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2020 Google LLC
1+
// Copyright 2022 Google LLC
22
//
33
// Licensed under the Apache License, Version 2.0 (the "License");
44
// you may not use this file except in compliance with the License.
@@ -38,8 +38,8 @@ service Recommender {
3838
option (google.api.default_host) = "recommender.googleapis.com";
3939
option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
4040

41-
// Lists insights for a Cloud project. Requires the recommender.*.list IAM
42-
// permission for the specified insight type.
41+
// Lists insights for the specified Cloud Resource. Requires the
42+
// recommender.*.list IAM permission for the specified insight type.
4343
rpc ListInsights(ListInsightsRequest) returns (ListInsightsResponse) {
4444
option (google.api.http) = {
4545
get: "/v1/{parent=projects/*/locations/*/insightTypes/*}/insights"
@@ -100,8 +100,8 @@ service Recommender {
100100
option (google.api.method_signature) = "name,state_metadata,etag";
101101
}
102102

103-
// Lists recommendations for a Cloud project. Requires the recommender.*.list
104-
// IAM permission for the specified recommender.
103+
// Lists recommendations for the specified Cloud Resource. Requires the
104+
// recommender.*.list IAM permission for the specified recommender.
105105
rpc ListRecommendations(ListRecommendationsRequest) returns (ListRecommendationsResponse) {
106106
option (google.api.http) = {
107107
get: "/v1/{parent=projects/*/locations/*/recommenders/*}/recommendations"
@@ -235,13 +235,20 @@ message ListInsightsRequest {
235235
// Required. The container resource on which to execute the request.
236236
// Acceptable formats:
237237
//
238-
// 1.
239-
// "projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]",
238+
// * `projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]`
239+
//
240+
// * `projects/[PROJECT_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]`
241+
//
242+
// * `billingAccounts/[BILLING_ACCOUNT_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]`
243+
//
244+
// * `folders/[FOLDER_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]`
245+
//
246+
// * `organizations/[ORGANIZATION_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]`
240247
//
241248
// LOCATION here refers to GCP Locations:
242249
// https://cloud.google.com/about/locations/
243250
// INSIGHT_TYPE_ID refers to supported insight types:
244-
// https://cloud.google.com/recommender/docs/insights/insight-types.)
251+
// https://cloud.google.com/recommender/docs/insights/insight-types.
245252
string parent = 1 [
246253
(google.api.field_behavior) = REQUIRED,
247254
(google.api.resource_reference) = {
@@ -261,8 +268,26 @@ message ListInsightsRequest {
261268
string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
262269

263270
// Optional. Filter expression to restrict the insights returned. Supported
264-
// filter fields: state
265-
// Eg: `state:"DISMISSED" or state:"ACTIVE"
271+
// filter fields:
272+
//
273+
// * `stateInfo.state`
274+
//
275+
// * `insightSubtype`
276+
//
277+
// * `severity`
278+
//
279+
// Examples:
280+
//
281+
// * `stateInfo.state = ACTIVE OR stateInfo.state = DISMISSED`
282+
//
283+
// * `insightSubtype = PERMISSIONS_USAGE`
284+
//
285+
// * `severity = CRITICAL OR severity = HIGH`
286+
//
287+
// * `stateInfo.state = ACTIVE AND (severity = CRITICAL OR severity = HIGH)`
288+
//
289+
// (These expressions are based on the filter language described at
290+
// https://google.aip.dev/160)
266291
string filter = 4 [(google.api.field_behavior) = OPTIONAL];
267292
}
268293

@@ -310,8 +335,15 @@ message ListRecommendationsRequest {
310335
// Required. The container resource on which to execute the request.
311336
// Acceptable formats:
312337
//
313-
// 1.
314-
// "projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]",
338+
// * `projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]`
339+
//
340+
// * `projects/[PROJECT_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]`
341+
//
342+
// * `billingAccounts/[BILLING_ACCOUNT_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]`
343+
//
344+
// * `folders/[FOLDER_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]`
345+
//
346+
// * `organizations/[ORGANIZATION_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]`
315347
//
316348
// LOCATION here refers to GCP Locations:
317349
// https://cloud.google.com/about/locations/
@@ -336,8 +368,26 @@ message ListRecommendationsRequest {
336368
string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
337369

338370
// Filter expression to restrict the recommendations returned. Supported
339-
// filter fields: state_info.state
340-
// Eg: `state_info.state:"DISMISSED" or state_info.state:"FAILED"
371+
// filter fields:
372+
//
373+
// * `state_info.state`
374+
//
375+
// * `recommenderSubtype`
376+
//
377+
// * `priority`
378+
//
379+
// Examples:
380+
//
381+
// * `stateInfo.state = ACTIVE OR stateInfo.state = DISMISSED`
382+
//
383+
// * `recommenderSubtype = REMOVE_ROLE OR recommenderSubtype = REPLACE_ROLE`
384+
//
385+
// * `priority = P1 OR priority = P2`
386+
//
387+
// * `stateInfo.state = ACTIVE AND (priority = P1 OR priority = P2)`
388+
//
389+
// (These expressions are based on the filter language described at
390+
// https://google.aip.dev/160)
341391
string filter = 5;
342392
}
343393

0 commit comments

Comments
 (0)