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
googleapis · Jan 26, 2022 · 2060f89 · 2060f89
1 parent 4b6b01f
commit 2060f89
Show file tree

Hide file tree

Showing 3 changed files with 138 additions and 25 deletions.
diff --git a/google/cloud/recommender/v1/insight.proto b/google/cloud/recommender/v1/insight.proto
@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -46,13 +46,6 @@ message Insight {
     pattern: "organizations/{organization}/locations/{location}/insightTypes/{insight_type}/insights/{insight}"
   };
 
-  // Reference to an associated recommendation.
-  message RecommendationReference {
-    // Recommendation resource name, e.g.
-    // projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/recommendations/[RECOMMENDATION_ID]
-    string recommendation = 1;
-  }
-
   // Insight category.
   enum Category {
     // Unspecified category.
@@ -71,6 +64,31 @@ message Insight {
     MANAGEABILITY = 4;
   }
 
+  // Insight severity levels.
+  enum Severity {
+    // Insight has unspecified severity.
+    SEVERITY_UNSPECIFIED = 0;
+
+    // Insight has low severity.
+    LOW = 1;
+
+    // Insight has medium severity.
+    MEDIUM = 2;
+
+    // Insight has high severity.
+    HIGH = 3;
+
+    // Insight has critical severity.
+    CRITICAL = 4;
+  }
+
+  // Reference to an associated recommendation.
+  message RecommendationReference {
+    // Recommendation resource name, e.g.
+    // projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/recommendations/[RECOMMENDATION_ID]
+    string recommendation = 1;
+  }
+
   // Name of the insight.
   string name = 1;
 
@@ -102,6 +120,9 @@ message Insight {
   // Category being targeted by the insight.
   Category category = 7;
 
+  // Insight's severity.
+  Severity severity = 15;
+
   // Fingerprint of the Insight. Provides optimistic locking when updating
   // states.
   string etag = 11;

diff --git a/google/cloud/recommender/v1/recommendation.proto b/google/cloud/recommender/v1/recommendation.proto
@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -46,6 +46,24 @@ message Recommendation {
     pattern: "organizations/{organization}/locations/{location}/recommenders/{recommender}/recommendations/{recommendation}"
   };
 
+  // Recommendation priority levels.
+  enum Priority {
+    // Recommendation has unspecified priority.
+    PRIORITY_UNSPECIFIED = 0;
+
+    // Recommendation has P4 priority (lowest priority).
+    P4 = 1;
+
+    // Recommendation has P3 priority (second lowest priority).
+    P3 = 2;
+
+    // Recommendation has P2 priority (second highest priority).
+    P2 = 3;
+
+    // Recommendation has P1 priority (highest priority).
+    P1 = 4;
+  }
+
   // Reference to an associated insight.
   message InsightReference {
     // Insight resource name, e.g.
@@ -84,6 +102,9 @@ message Recommendation {
   // or negative.
   repeated Impact additional_impact = 6;
 
+  // Recommendation's priority.
+  Priority priority = 17;
+
   // Content of the recommendation describing recommended changes to resources.
   RecommendationContent content = 7;
 
@@ -96,6 +117,12 @@ message Recommendation {
 
   // Insights that led to this recommendation.
   repeated InsightReference associated_insights = 14;
+
+  // 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.
+  string xor_group_id = 18;
 }
 
 // Contains what resources are changing and how they are changing.
@@ -104,6 +131,9 @@ message RecommendationContent {
   // that, all operations within one group are expected to be performed
   // atomically and in an order.
   repeated OperationGroup operation_groups = 2;
+
+  // Condensed overview information about the recommendation.
+  google.protobuf.Struct overview = 3;
 }
 
 // Group of operations that need to be performed atomically.
@@ -123,7 +153,7 @@ message OperationGroup {
 // * Allows extension to custom operations not natively supported by RFC6902.
 // See https://tools.ietf.org/html/rfc6902 for details on the original RFC.
 message Operation {
-  // Type of this operation. Contains one of 'and', 'remove', 'replace', 'move',
+  // Type of this operation. Contains one of 'add', 'remove', 'replace', 'move',
   // 'copy', 'test' and custom operations. This field is case-insensitive and
   // always populated.
   string action = 1;
@@ -197,7 +227,7 @@ message Operation {
   map<string, google.protobuf.Value> path_filters = 8;
 
   // 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
+  // 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.
@@ -219,12 +249,21 @@ message CostProjection {
   // 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.
   google.type.Money cost = 1;
 
   // Duration for which this cost applies.
   google.protobuf.Duration duration = 2;
 }
 
+// Contains various ways of describing the impact on Security.
+message SecurityProjection {
+  // Additional security impact details that is provided by the recommender.
+  google.protobuf.Struct details = 2;
+}
+
 // Contains the impact a recommendation can have for a given category.
 message Impact {
   // The category of the impact.
@@ -252,6 +291,9 @@ message Impact {
   oneof projection {
     // Use with CategoryType.COST
     CostProjection cost_projection = 100;
+
+    // Use with CategoryType.SECURITY
+    SecurityProjection security_projection = 101;
   }
 }
 

diff --git a/google/cloud/recommender/v1/recommender_service.proto b/google/cloud/recommender/v1/recommender_service.proto
@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -38,8 +38,8 @@ service Recommender {
   option (google.api.default_host) = "recommender.googleapis.com";
   option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
 
-  // Lists insights for a Cloud project. Requires the recommender.*.list IAM
-  // permission for the specified insight type.
+  // Lists insights for the specified Cloud Resource. Requires the
+  // recommender.*.list IAM permission for the specified insight type.
   rpc ListInsights(ListInsightsRequest) returns (ListInsightsResponse) {
     option (google.api.http) = {
       get: "/v1/{parent=projects/*/locations/*/insightTypes/*}/insights"
@@ -100,8 +100,8 @@ service Recommender {
     option (google.api.method_signature) = "name,state_metadata,etag";
   }
 
-  // Lists recommendations for a Cloud project. Requires the recommender.*.list
-  // IAM permission for the specified recommender.
+  // Lists recommendations for the specified Cloud Resource. Requires the
+  // recommender.*.list IAM permission for the specified recommender.
   rpc ListRecommendations(ListRecommendationsRequest) returns (ListRecommendationsResponse) {
     option (google.api.http) = {
       get: "/v1/{parent=projects/*/locations/*/recommenders/*}/recommendations"
@@ -235,13 +235,20 @@ message ListInsightsRequest {
   // Required. The container resource on which to execute the request.
   // Acceptable formats:
   //
-  // 1.
-  // "projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]",
+  // * `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.)
+  // https://cloud.google.com/recommender/docs/insights/insight-types.
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -261,8 +268,26 @@ message ListInsightsRequest {
   string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
 
   // Optional. Filter expression to restrict the insights returned. Supported
-  // filter fields: state
-  // Eg: `state:"DISMISSED" or state:"ACTIVE"
+  // filter fields:
+  //
+  // * `stateInfo.state`
+  //
+  // * `insightSubtype`
+  //
+  // * `severity`
+  //
+  // Examples:
+  //
+  // * `stateInfo.state = ACTIVE OR stateInfo.state = DISMISSED`
+  //
+  // * `insightSubtype = PERMISSIONS_USAGE`
+  //
+  // * `severity = CRITICAL OR severity = HIGH`
+  //
+  // * `stateInfo.state = ACTIVE AND (severity = CRITICAL OR severity = HIGH)`
+  //
+  // (These expressions are based on the filter language described at
+  // https://google.aip.dev/160)
   string filter = 4 [(google.api.field_behavior) = OPTIONAL];
 }
 
@@ -310,8 +335,15 @@ message ListRecommendationsRequest {
   // Required. The container resource on which to execute the request.
   // Acceptable formats:
   //
-  // 1.
-  // "projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]",
+  // * `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/
@@ -336,8 +368,26 @@ message ListRecommendationsRequest {
   string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
 
   // Filter expression to restrict the recommendations returned. Supported
-  // filter fields: state_info.state
-  // Eg: `state_info.state:"DISMISSED" or state_info.state:"FAILED"
+  // filter fields:
+  //
+  // * `state_info.state`
+  //
+  // * `recommenderSubtype`
+  //
+  // * `priority`
+  //
+  // Examples:
+  //
+  // * `stateInfo.state = ACTIVE OR stateInfo.state = DISMISSED`
+  //
+  // * `recommenderSubtype = REMOVE_ROLE OR recommenderSubtype = REPLACE_ROLE`
+  //
+  // * `priority = P1 OR priority = P2`
+  //
+  // * `stateInfo.state = ACTIVE AND (priority = P1 OR priority = P2)`
+  //
+  // (These expressions are based on the filter language described at
+  // https://google.aip.dev/160)
   string filter = 5;
 }