recommendation.proto 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292
  1. // Copyright 2020 Google LLC
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. // http://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  14. syntax = "proto3";
  15. package google.cloud.recommender.v1beta1;
  16. import "google/api/resource.proto";
  17. import "google/protobuf/duration.proto";
  18. import "google/protobuf/struct.proto";
  19. import "google/protobuf/timestamp.proto";
  20. import "google/type/money.proto";
  21. option csharp_namespace = "Google.Cloud.Recommender.V1Beta1";
  22. option go_package = "google.golang.org/genproto/googleapis/cloud/recommender/v1beta1;recommender";
  23. option java_multiple_files = true;
  24. option java_package = "com.google.cloud.recommender.v1beta1";
  25. option objc_class_prefix = "CREC";
  26. option (google.api.resource_definition) = {
  27. type: "recommender.googleapis.com/Recommender"
  28. pattern: "projects/{project}/locations/{location}/recommenders/{recommender}"
  29. pattern: "billingAccounts/{billing_account}/locations/{location}/recommenders/{recommender}"
  30. pattern: "folders/{folder}/locations/{location}/recommenders/{recommender}"
  31. pattern: "organizations/{organization}/locations/{location}/recommenders/{recommender}"
  32. };
  33. // A recommendation along with a suggested action. E.g., a rightsizing
  34. // recommendation for an underutilized VM, IAM role recommendations, etc
  35. message Recommendation {
  36. option (google.api.resource) = {
  37. type: "recommender.googleapis.com/Recommendation"
  38. pattern: "projects/{project}/locations/{location}/recommenders/{recommender}/recommendations/{recommendation}"
  39. pattern: "billingAccounts/{billing_account}/locations/{location}/recommenders/{recommender}/recommendations/{recommendation}"
  40. pattern: "folders/{folder}/locations/{location}/recommenders/{recommender}/recommendations/{recommendation}"
  41. pattern: "organizations/{organization}/locations/{location}/recommenders/{recommender}/recommendations/{recommendation}"
  42. };
  43. // Reference to an associated insight.
  44. message InsightReference {
  45. // Insight resource name, e.g.
  46. // projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]/insights/[INSIGHT_ID]
  47. string insight = 1;
  48. }
  49. // Name of recommendation.
  50. string name = 1;
  51. // Free-form human readable summary in English. The maximum length is 500
  52. // characters.
  53. string description = 2;
  54. // Contains an identifier for a subtype of recommendations produced for the
  55. // same recommender. Subtype is a function of content and impact, meaning a
  56. // new subtype might be added when significant changes to `content` or
  57. // `primary_impact.category` are introduced. See the Recommenders section
  58. // to see a list of subtypes for a given Recommender.
  59. //
  60. // Examples:
  61. // For recommender = "google.iam.policy.Recommender",
  62. // recommender_subtype can be one of "REMOVE_ROLE"/"REPLACE_ROLE"
  63. string recommender_subtype = 12;
  64. // Last time this recommendation was refreshed by the system that created it
  65. // in the first place.
  66. google.protobuf.Timestamp last_refresh_time = 4;
  67. // The primary impact that this recommendation can have while trying to
  68. // optimize for one category.
  69. Impact primary_impact = 5;
  70. // Optional set of additional impact that this recommendation may have when
  71. // trying to optimize for the primary category. These may be positive
  72. // or negative.
  73. repeated Impact additional_impact = 6;
  74. // Content of the recommendation describing recommended changes to resources.
  75. RecommendationContent content = 7;
  76. // Information for state. Contains state and metadata.
  77. RecommendationStateInfo state_info = 10;
  78. // Fingerprint of the Recommendation. Provides optimistic locking when
  79. // updating states.
  80. string etag = 11;
  81. // Insights that led to this recommendation.
  82. repeated InsightReference associated_insights = 14;
  83. }
  84. // Contains what resources are changing and how they are changing.
  85. message RecommendationContent {
  86. // Operations to one or more Google Cloud resources grouped in such a way
  87. // that, all operations within one group are expected to be performed
  88. // atomically and in an order.
  89. repeated OperationGroup operation_groups = 2;
  90. }
  91. // Group of operations that need to be performed atomically.
  92. message OperationGroup {
  93. // List of operations across one or more resources that belong to this group.
  94. // Loosely based on RFC6902 and should be performed in the order they appear.
  95. repeated Operation operations = 1;
  96. }
  97. // Contains an operation for a resource loosely based on the JSON-PATCH format
  98. // with support for:
  99. //
  100. // * Custom filters for describing partial array patch.
  101. // * Extended path values for describing nested arrays.
  102. // * Custom fields for describing the resource for which the operation is being
  103. // described.
  104. // * Allows extension to custom operations not natively supported by RFC6902.
  105. // See https://tools.ietf.org/html/rfc6902 for details on the original RFC.
  106. message Operation {
  107. // Type of this operation. Contains one of 'and', 'remove', 'replace', 'move',
  108. // 'copy', 'test' and 'custom' operations. This field is case-insensitive and
  109. // always populated.
  110. string action = 1;
  111. // Type of GCP resource being modified/tested. This field is always populated.
  112. // Example: cloudresourcemanager.googleapis.com/Project,
  113. // compute.googleapis.com/Instance
  114. string resource_type = 2;
  115. // Contains the fully qualified resource name. This field is always populated.
  116. // ex: //cloudresourcemanager.googleapis.com/projects/foo.
  117. string resource = 3;
  118. // Path to the target field being operated on. If the operation is at the
  119. // resource level, then path should be "/". This field is always populated.
  120. string path = 4;
  121. // Can be set with action 'copy' to copy resource configuration across
  122. // different resources of the same type. Example: A resource clone can be
  123. // done via action = 'copy', path = "/", from = "/",
  124. // source_resource = <source> and resource_name = <target>.
  125. // This field is empty for all other values of `action`.
  126. string source_resource = 5;
  127. // Can be set with action 'copy' or 'move' to indicate the source field within
  128. // resource or source_resource, ignored if provided for other operation types.
  129. string source_path = 6;
  130. // One of the fields in the following block will be set and intend to
  131. // describe a value for 'path' field.
  132. oneof path_value {
  133. // Value for the `path` field. Will be set for actions:'add'/'replace'.
  134. // Maybe set for action: 'test'. Either this or `value_matcher` will be set
  135. // for 'test' operation. An exact match must be performed.
  136. google.protobuf.Value value = 7;
  137. // Can be set for action 'test' for advanced matching for the value of
  138. // 'path' field. Either this or `value` will be set for 'test' operation.
  139. ValueMatcher value_matcher = 10;
  140. }
  141. // Set of filters to apply if `path` refers to array elements or nested array
  142. // elements in order to narrow down to a single unique element that is being
  143. // tested/modified.
  144. // This is intended to be an exact match per filter. To perform advanced
  145. // matching, use path_value_matchers.
  146. //
  147. // * Example: {
  148. // "/versions/*/name" : "it-123"
  149. // "/versions/*/targetSize/percent": 20
  150. // }
  151. // * Example: {
  152. // "/bindings/*/role": "roles/owner"
  153. // "/bindings/*/condition" : null
  154. // }
  155. // * Example: {
  156. // "/bindings/*/role": "roles/owner"
  157. // "/bindings/*/members/*" : ["x@example.com", "y@example.com"]
  158. // }
  159. // When both path_filters and path_value_matchers are set, an implicit AND
  160. // must be performed.
  161. map<string, google.protobuf.Value> path_filters = 8;
  162. // Similar to path_filters, this contains set of filters to apply if `path`
  163. // field referes to array elements. This is meant to support value matching
  164. // beyond exact match. To perform exact match, use path_filters.
  165. // When both path_filters and path_value_matchers are set, an implicit AND
  166. // must be performed.
  167. map<string, ValueMatcher> path_value_matchers = 11;
  168. }
  169. // Contains various matching options for values for a GCP resource field.
  170. message ValueMatcher {
  171. oneof match_variant {
  172. // To be used for full regex matching. The regular expression is using the
  173. // Google RE2 syntax (https://github.com/google/re2/wiki/Syntax), so to be
  174. // used with RE2::FullMatch
  175. string matches_pattern = 1;
  176. }
  177. }
  178. // Contains metadata about how much money a recommendation can save or incur.
  179. message CostProjection {
  180. // An approximate projection on amount saved or amount incurred. Negative cost
  181. // units indicate cost savings and positive cost units indicate increase.
  182. // See google.type.Money documentation for positive/negative units.
  183. google.type.Money cost = 1;
  184. // Duration for which this cost applies.
  185. google.protobuf.Duration duration = 2;
  186. }
  187. // Contains the impact a recommendation can have for a given category.
  188. message Impact {
  189. // The category of the impact.
  190. enum Category {
  191. // Default unspecified category. Don't use directly.
  192. CATEGORY_UNSPECIFIED = 0;
  193. // Indicates a potential increase or decrease in cost.
  194. COST = 1;
  195. // Indicates a potential increase or decrease in security.
  196. SECURITY = 2;
  197. // Indicates a potential increase or decrease in performance.
  198. PERFORMANCE = 3;
  199. // Indicates a potential increase or decrease in manageability.
  200. MANAGEABILITY = 4;
  201. }
  202. // Category that is being targeted.
  203. Category category = 1;
  204. // Contains projections (if any) for this category.
  205. oneof projection {
  206. // Use with CategoryType.COST
  207. CostProjection cost_projection = 100;
  208. }
  209. }
  210. // Information for state. Contains state and metadata.
  211. message RecommendationStateInfo {
  212. // Represents Recommendation State.
  213. enum State {
  214. // Default state. Don't use directly.
  215. STATE_UNSPECIFIED = 0;
  216. // Recommendation is active and can be applied. Recommendations content can
  217. // be updated by Google.
  218. //
  219. // ACTIVE recommendations can be marked as CLAIMED, SUCCEEDED, or FAILED.
  220. ACTIVE = 1;
  221. // Recommendation is in claimed state. Recommendations content is
  222. // immutable and cannot be updated by Google.
  223. //
  224. // CLAIMED recommendations can be marked as CLAIMED, SUCCEEDED, or FAILED.
  225. CLAIMED = 6;
  226. // Recommendation is in succeeded state. Recommendations content is
  227. // immutable and cannot be updated by Google.
  228. //
  229. // SUCCEEDED recommendations can be marked as SUCCEEDED, or FAILED.
  230. SUCCEEDED = 3;
  231. // Recommendation is in failed state. Recommendations content is immutable
  232. // and cannot be updated by Google.
  233. //
  234. // FAILED recommendations can be marked as SUCCEEDED, or FAILED.
  235. FAILED = 4;
  236. // Recommendation is in dismissed state. Recommendation content can be
  237. // updated by Google.
  238. //
  239. // DISMISSED recommendations can be marked as ACTIVE.
  240. DISMISSED = 5;
  241. }
  242. // The state of the recommendation, Eg ACTIVE, SUCCEEDED, FAILED.
  243. State state = 1;
  244. // A map of metadata for the state, provided by user or automations systems.
  245. map<string, string> state_metadata = 2;
  246. }