feat: resource usage

docs: update comments

PiperOrigin-RevId: 513425559

google/cloud/batch/v1alpha/batch.proto

@@ -23,6 +23,7 @@ import "google/api/resource.proto";
 import "google/cloud/batch/v1alpha/job.proto";
 import "google/cloud/batch/v1alpha/task.proto";
 import "google/longrunning/operations.proto";
+import "google/protobuf/empty.proto";
 import "google/protobuf/timestamp.proto";
 
 option csharp_namespace = "Google.Cloud.Batch.V1Alpha";
@@ -124,8 +125,8 @@ message CreateJobRequest {
   // ignore the request if it has already been completed. The server will
   // guarantee that for at least 60 minutes since the first request.
   //
-  // For example, consider a situation where you make an initial request and t
-  // he request times out. If you make the request again with the same request
+  // For example, consider a situation where you make an initial request and
+  // the request times out. If you make the request again with the same request
   // ID, the server can check if original operation with the same request ID
   // was received, and if so, will ignore the second request. This prevents
   // clients from accidentally creating duplicate commitments.
@@ -157,8 +158,8 @@ message DeleteJobRequest {
   // ignore the request if it has already been completed. The server will
   // guarantee that for at least 60 minutes after the first request.
   //
-  // For example, consider a situation where you make an initial request and t
-  // he request times out. If you make the request again with the same request
+  // For example, consider a situation where you make an initial request and
+  // the request times out. If you make the request again with the same request
   // ID, the server can check if original operation with the same request ID
   // was received, and if so, will ignore the second request. This prevents
   // clients from accidentally creating duplicate commitments.

google/cloud/batch/v1alpha/batch_v1alpha.yaml

@@ -6,7 +6,6 @@ title: Batch API
 apis:
 - name: google.cloud.batch.v1alpha.BatchService
 - name: google.cloud.location.Locations
-- name: google.iam.v1.IAMPolicy
 - name: google.longrunning.Operations
 
 types:
@@ -22,29 +21,6 @@ documentation:
   - selector: google.cloud.location.Locations.ListLocations
     description: Lists information about the supported locations for this service.
 
-  - selector: google.iam.v1.IAMPolicy.GetIamPolicy
-    description: |-
-      Gets the access control policy for a resource. Returns an empty policy
-      if the resource exists and does not have a policy set.
-
-  - selector: google.iam.v1.IAMPolicy.SetIamPolicy
-    description: |-
-      Sets the access control policy on the specified resource. Replaces
-      any existing policy.
-
-      Can return `NOT_FOUND`, `INVALID_ARGUMENT`, and `PERMISSION_DENIED`
-      errors.
-
-  - selector: google.iam.v1.IAMPolicy.TestIamPermissions
-    description: |-
-      Returns permissions that a caller has on the specified resource. If the
-      resource does not exist, this will return an empty set of
-      permissions, not a `NOT_FOUND` error.
-
-      Note: This operation is designed to be used for building
-      permission-aware UIs and command-line tools, not for authorization
-      checking. This operation may "fail open" without warning.
-
 backend:
   rules:
   - selector: 'google.cloud.batch.v1alpha.BatchService.*'
@@ -53,8 +29,6 @@ backend:
     deadline: 60.0
   - selector: google.cloud.location.Locations.ListLocations
     deadline: 60.0
-  - selector: 'google.iam.v1.IAMPolicy.*'
-    deadline: 60.0
   - selector: 'google.longrunning.Operations.*'
     deadline: 60.0
 
@@ -64,14 +38,6 @@ http:
     get: '/v1alpha/{name=projects/*/locations/*}'
   - selector: google.cloud.location.Locations.ListLocations
     get: '/v1alpha/{name=projects/*}/locations'
-  - selector: google.iam.v1.IAMPolicy.GetIamPolicy
-    get: '/v1alpha/{resource=projects/*/locations/*/jobs/*}:getIamPolicy'
-  - selector: google.iam.v1.IAMPolicy.SetIamPolicy
-    post: '/v1alpha/{resource=projects/*/locations/*/jobs/*}:setIamPolicy'
-    body: '*'
-  - selector: google.iam.v1.IAMPolicy.TestIamPermissions
-    post: '/v1alpha/{resource=projects/*/locations/*/jobs/*}:testIamPermissions'
-    body: '*'
   - selector: google.longrunning.Operations.CancelOperation
     post: '/v1alpha/{name=projects/*/locations/*/operations/*}:cancel'
     body: '*'
@@ -96,10 +62,6 @@ authentication:
     oauth:
       canonical_scopes: |-
         https://www.googleapis.com/auth/cloud-platform
-  - selector: 'google.iam.v1.IAMPolicy.*'
-    oauth:
-      canonical_scopes: |-
-        https://www.googleapis.com/auth/cloud-platform
   - selector: 'google.longrunning.Operations.*'
     oauth:
       canonical_scopes: |-

google/cloud/batch/v1alpha/job.proto

@@ -57,7 +57,8 @@ message Job {
   string uid = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Priority of the Job.
-  // The valid value range is [0, 100).
+  // The valid value range is [0, 100). Default value is 0.
+  // Higher value indicates higher priority.
   // A job with higher priority value is more likely to run earlier if all other
   // requirements are satisfied.
   int64 priority = 3;
@@ -227,6 +228,15 @@ message JobStatus {
 
   // The duration of time that the Job spent in status RUNNING.
   google.protobuf.Duration run_duration = 5;
+
+  // The resource usage of the job.
+  ResourceUsage resource_usage = 6;
+}
+
+// ResourceUsage describes the resource usage of the job.
+message ResourceUsage {
+  // The CPU core hours that the job consumes.
+  double core_hours = 1;
 }
 
 // Notification configurations.

google/cloud/batch/v1alpha/task.proto

@@ -60,6 +60,9 @@ message StatusEvent {
 
   // Task Execution
   TaskExecution task_execution = 4;
+
+  // Task State
+  TaskStatus.State task_state = 5;
 }
 
 // This Task Execution field includes detail information for
@@ -98,6 +101,16 @@ message TaskStatus {
 
   // Detailed info about why the state is reached.
   repeated StatusEvent status_events = 2;
+
+  // The resource usage of the task.
+  TaskResourceUsage resource_usage = 3;
+}
+
+// TaskResourceUsage describes the resource usage of the task.
+message TaskResourceUsage {
+  // The CPU core hours the task consumes based on task requirement and run
+  // time.
+  double core_hours = 1;
 }
 
 // Runnable describes instructions for executing a specific script or container
@@ -145,9 +158,23 @@ message Runnable {
   message Script {
     oneof command {
       // Script file path on the host VM.
+      //
+      // To specify an interpreter, please add a `#!<interpreter>`(also known as
+      // [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix))) as the
+      // first line of the file.(For example, to execute the script using bash,
+      // `#!/bin/bash` should be the first line of the file. To execute the
+      // script using`Python3`, `#!/usr/bin/env python3` should be the first
+      // line of the file.) Otherwise, the file will by default be excuted by
+      // `/bin/sh`.
       string path = 1;
 
       // Shell script text.
+      //
+      // To specify an interpreter, please add a `#!<interpreter>\n` at the
+      // beginning of the text.(For example, to execute the script using bash,
+      // `#!/bin/bash\n` should be added. To execute the script using`Python3`,
+      // `#!/usr/bin/env python3\n` should be added.) Otherwise, the script will
+      // by default be excuted by `/bin/sh`.
       string text = 2;
     }
   }
@@ -228,13 +255,12 @@ message TaskSpec {
   int32 max_retry_count = 5;
 
   // Lifecycle management schema when any task in a task group is failed.
-  // The valid size of lifecycle policies are [0, 10].
-  // For each lifecycle policy, when the condition is met,
-  // the action in that policy will execute.
-  // If there are multiple policies that the task execution result matches,
-  // we use the action from the first matched policy. If task execution result
-  // does not meet with any of the defined lifecycle policy, we consider it as
-  // the default policy. Default policy means if the exit code is 0, exit task.
+  // Currently we only support one lifecycle policy.
+  // When the lifecycle policy condition is met,
+  // the action in the policy will execute.
+  // If task execution result does not meet with the defined lifecycle
+  // policy, we consider it as the default policy.
+  // Default policy means if the exit code is 0, exit task.
   // If task ends with non-zero exit code, retry the task with max_retry_count.
   repeated LifecyclePolicy lifecycle_policies = 9;
 
@@ -273,6 +299,10 @@ message LifecyclePolicy {
   }
 
   // Action to execute when ActionCondition is true.
+  // When RETRY_TASK is specified, we will retry failed tasks
+  // if we notice any exit code match and fail tasks if no match is found.
+  // Likewise, when FAIL_TASK is specified, we will fail tasks
+  // if we notice any exit code match and retry tasks if no match is found.
   Action action = 1;
 
   // Conditions that decide why a task failure is dealt with a specific action.