feat(v1): add recommendation priority / insight severity

google/cloud/recommender/__init__.py

@@ -28,6 +28,7 @@
 from google.cloud.recommender_v1.types.recommendation import Recommendation
 from google.cloud.recommender_v1.types.recommendation import RecommendationContent
 from google.cloud.recommender_v1.types.recommendation import RecommendationStateInfo
+from google.cloud.recommender_v1.types.recommendation import SecurityProjection
 from google.cloud.recommender_v1.types.recommendation import ValueMatcher
 from google.cloud.recommender_v1.types.recommender_service import GetInsightRequest
 from google.cloud.recommender_v1.types.recommender_service import (
@@ -66,6 +67,7 @@
  "Recommendation",
  "RecommendationContent",
  "RecommendationStateInfo",
+ "SecurityProjection",
  "ValueMatcher",
  "GetInsightRequest",
  "GetRecommendationRequest",

google/cloud/recommender_v1/__init__.py

@@ -26,6 +26,7 @@
 from .types.recommendation import Recommendation
 from .types.recommendation import RecommendationContent
 from .types.recommendation import RecommendationStateInfo
+from .types.recommendation import SecurityProjection
 from .types.recommendation import ValueMatcher
 from .types.recommender_service import GetInsightRequest
 from .types.recommender_service import GetRecommendationRequest
@@ -60,5 +61,6 @@
  "RecommendationContent",
  "RecommendationStateInfo",
  "RecommenderClient",
+ "SecurityProjection",
  "ValueMatcher",
 )

google/cloud/recommender_v1/services/recommender/async_client.py

@@ -225,7 +225,7 @@ async def list_insights(
  timeout: float = None,
  metadata: Sequence[Tuple[str, str]] = (),
  ) -> pagers.ListInsightsAsyncPager:
- r"""Lists insights for a Cloud project. Requires the
+ r"""Lists insights for the specified Cloud Resource. Requires the
  recommender.*.list IAM permission for the specified insight
  type.
 
@@ -237,14 +237,20 @@ async def list_insights(
  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.
 
  This corresponds to the ``parent`` field
  on the ``request`` instance; if ``request`` is provided, this
@@ -508,8 +514,9 @@ async def list_recommendations(
  timeout: float = None,
  metadata: Sequence[Tuple[str, str]] = (),
  ) -> pagers.ListRecommendationsAsyncPager:
- r"""Lists recommendations for a Cloud project. Requires the
- recommender.*.list IAM permission for the specified recommender.
+ r"""Lists recommendations for the specified Cloud Resource. Requires
+ the recommender.*.list IAM permission for the specified
+ recommender.
 
  Args:
  request (Union[google.cloud.recommender_v1.types.ListRecommendationsRequest, dict]):
@@ -519,9 +526,15 @@ async def list_recommendations(
  Required. The container resource on which to execute the
  request. Acceptable formats:
 
- 1.
+ - ``projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]``
+
+ - ``projects/[PROJECT_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]``
 
- "projects/[PROJECT_NUMBER]/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/ RECOMMENDER_ID
@@ -533,9 +546,26 @@ async def list_recommendations(
  should not be set.
  filter (:class:`str`):
  Filter expression to restrict the recommendations
- returned. Supported filter fields: state_info.state Eg:
- \`state_info.state:"DISMISSED" or
- state_info.state:"FAILED"
+ returned. Supported 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)
 
  This corresponds to the ``filter`` field
  on the ``request`` instance; if ``request`` is provided, this

google/cloud/recommender_v1/services/recommender/client.py

@@ -474,7 +474,7 @@ def list_insights(
  timeout: float = None,
  metadata: Sequence[Tuple[str, str]] = (),
  ) -> pagers.ListInsightsPager:
- r"""Lists insights for a Cloud project. Requires the
+ r"""Lists insights for the specified Cloud Resource. Requires the
  recommender.*.list IAM permission for the specified insight
  type.
 
@@ -486,14 +486,20 @@ def list_insights(
  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.
 
  This corresponds to the ``parent`` field
  on the ``request`` instance; if ``request`` is provided, this
@@ -736,8 +742,9 @@ def list_recommendations(
  timeout: float = None,
  metadata: Sequence[Tuple[str, str]] = (),
  ) -> pagers.ListRecommendationsPager:
- r"""Lists recommendations for a Cloud project. Requires the
- recommender.*.list IAM permission for the specified recommender.
+ r"""Lists recommendations for the specified Cloud Resource. Requires
+ the recommender.*.list IAM permission for the specified
+ recommender.
 
  Args:
  request (Union[google.cloud.recommender_v1.types.ListRecommendationsRequest, dict]):
@@ -747,9 +754,15 @@ def list_recommendations(
  Required. The container resource on which to execute the
  request. Acceptable formats:
 
- 1.
+ - ``projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]``
+
+ - ``projects/[PROJECT_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]``
 
- "projects/[PROJECT_NUMBER]/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/ RECOMMENDER_ID
@@ -761,9 +774,26 @@ def list_recommendations(
  should not be set.
  filter (str):
  Filter expression to restrict the recommendations
- returned. Supported filter fields: state_info.state Eg:
- \`state_info.state:"DISMISSED" or
- state_info.state:"FAILED"
+ returned. Supported 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)
 
  This corresponds to the ``filter`` field
  on the ``request`` instance; if ``request`` is provided, this

google/cloud/recommender_v1/services/recommender/transports/grpc.py

@@ -240,7 +240,7 @@ def list_insights(
  ]:
  r"""Return a callable for the list insights method over gRPC.
 
- Lists insights for a Cloud project. Requires the
+ Lists insights for the specified Cloud Resource. Requires the
  recommender.*.list IAM permission for the specified insight
  type.
 
@@ -331,8 +331,9 @@ def list_recommendations(
  ]:
  r"""Return a callable for the list recommendations method over gRPC.
 
- 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.
 
  Returns:
  Callable[[~.ListRecommendationsRequest],

google/cloud/recommender_v1/services/recommender/transports/grpc_asyncio.py

@@ -242,7 +242,7 @@ def list_insights(
  ]:
  r"""Return a callable for the list insights method over gRPC.
 
- Lists insights for a Cloud project. Requires the
+ Lists insights for the specified Cloud Resource. Requires the
  recommender.*.list IAM permission for the specified insight
  type.
 
@@ -335,8 +335,9 @@ def list_recommendations(
  ]:
  r"""Return a callable for the list recommendations method over gRPC.
 
- 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.
 
  Returns:
  Callable[[~.ListRecommendationsRequest],

google/cloud/recommender_v1/types/__init__.py

@@ -25,6 +25,7 @@
  Recommendation,
  RecommendationContent,
  RecommendationStateInfo,
+ SecurityProjection,
  ValueMatcher,
 )
 from .recommender_service import (
@@ -50,6 +51,7 @@
  "Recommendation",
  "RecommendationContent",
  "RecommendationStateInfo",
+ "SecurityProjection",
  "ValueMatcher",
  "GetInsightRequest",
  "GetRecommendationRequest",

google/cloud/recommender_v1/types/insight.py

@@ -56,6 +56,8 @@ class Insight(proto.Message):
  Information state and metadata.
  category (google.cloud.recommender_v1.types.Insight.Category):
  Category being targeted by the insight.
+ severity (google.cloud.recommender_v1.types.Insight.Severity):
+ Insight's severity.
  etag (str):
  Fingerprint of the Insight. Provides
  optimistic locking when updating states.
@@ -71,6 +73,14 @@ class Category(proto.Enum):
  PERFORMANCE = 3
  MANAGEABILITY = 4
 
+ class Severity(proto.Enum):
+ r"""Insight severity levels."""
+ SEVERITY_UNSPECIFIED = 0
+ LOW = 1
+ MEDIUM = 2
+ HIGH = 3
+ CRITICAL = 4
+
  class RecommendationReference(proto.Message):
  r"""Reference to an associated recommendation.
 
@@ -95,6 +105,7 @@ class RecommendationReference(proto.Message):
  )
  state_info = proto.Field(proto.MESSAGE, number=6, message="InsightStateInfo",)
  category = proto.Field(proto.ENUM, number=7, enum=Category,)
+ severity = proto.Field(proto.ENUM, number=15, enum=Severity,)
  etag = proto.Field(proto.STRING, number=11,)
  associated_recommendations = proto.RepeatedField(
  proto.MESSAGE, number=8, message=RecommendationReference,