diff --git a/google/cloud/recommender/v1/insight.proto b/google/cloud/recommender/v1/insight.proto index e561b8381800d..0fdc0fdaeef7e 100644 --- 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 index 8d75134d688f1..5d72be18d4ab6 100644 --- 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 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 index c6475eaa3c661..73ca4f8debfbe 100644 --- 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; }