feat: add TaskStatus's new terminated state UNEXECUTED

feat: add scheduling_policy IN_ORDER enum to support sequential task executions
docs: update comments on boot disk fields for clearer usage scope
feat: add support for placement policies
docs: update block_external_network field comment to reduce confusion
docs: update disk and network field comment for better readability
docs: fix `book disk` typo
docs: Update reservation field API doc

PiperOrigin-RevId: 524883955

Author: Google APIs

google/cloud/batch/v1alpha/batch_v1alpha.yaml

@@ -13,7 +13,7 @@ types:
 
 documentation:
   summary: An API to manage the running of batch jobs on Google Cloud Platform.
-  overview: '(== google/cloud/batch/doc/overview.md ==)'
+  overview: '(include == google/cloud/batch/doc/overview.md ==)'
   rules:
   - selector: google.cloud.location.Locations.GetLocation
     description: Gets information about a location.
@@ -38,11 +38,6 @@ http:
     get: '/v1alpha/{name=projects/*/locations/*}'
   - selector: google.cloud.location.Locations.ListLocations
     get: '/v1alpha/{name=projects/*}/locations'
-  - selector: google.longrunning.Operations.CancelOperation
-    post: '/v1alpha/{name=projects/*/locations/*/operations/*}:cancel'
-    body: '*'
-  - selector: google.longrunning.Operations.DeleteOperation
-    delete: '/v1alpha/{name=projects/*/locations/*/operations/*}'
   - selector: google.longrunning.Operations.GetOperation
     get: '/v1alpha/{name=projects/*/locations/*/operations/*}'
   - selector: google.longrunning.Operations.ListOperations
@@ -66,13 +61,3 @@ authentication:
     oauth:
       canonical_scopes: |-
         https://www.googleapis.com/auth/cloud-platform
-
-publishing:
-  organization: CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED
-  new_issue_uri: ''
-  documentation_uri: ''
-  api_short_name: ''
-  github_label: ''
-  doc_tag_prefix: ''
-  codeowner_github_teams:
-  library_settings:

google/cloud/batch/v1alpha/job.proto

@@ -284,12 +284,14 @@ message JobNotification {
 message AllocationPolicy {
   message LocationPolicy {
     // A list of allowed location names represented by internal URLs.
+    //
     // Each location can be a region or a zone.
     // Only one region or multiple zones in one region is supported now.
     // For example,
     // ["regions/us-central1"] allow VMs in any zones in region us-central1.
     // ["zones/us-central1-a", "zones/us-central1-c"] only allow VMs
     // in zones us-central1-a and us-central1-c.
+    //
     // All locations end up in different regions would cause errors.
     // For example,
     // ["regions/us-central1", "zones/us-central1-a", "zones/us-central1-b",
@@ -305,25 +307,29 @@ message AllocationPolicy {
 
   // A new persistent disk or a local ssd.
   // A VM can only have one local SSD setting but multiple local SSD partitions.
-  // https://cloud.google.com/compute/docs/disks#pdspecs.
+  // See https://cloud.google.com/compute/docs/disks#pdspecs and
   // https://cloud.google.com/compute/docs/disks#localssds.
   message Disk {
     // A data source from which a PD will be created.
     oneof data_source {
       // Name of a public or custom image used as the data source.
       // For example, the following are all valid URLs:
-      // (1) Specify the image by its family name:
+      //
+      // * Specify the image by its family name:
       // projects/{project}/global/images/family/{image_family}
-      // (2) Specify the image version:
+      // * Specify the image version:
       // projects/{project}/global/images/{image_version}
+      //
       // You can also use Batch customized image in short names.
       // The following image values are supported for a boot disk:
-      // "batch-debian": use Batch Debian images.
-      // "batch-centos": use Batch CentOS images.
-      // "batch-cos": use Batch Container-Optimized images.
+      //
+      // * "batch-debian": use Batch Debian images.
+      // * "batch-centos": use Batch CentOS images.
+      // * "batch-cos": use Batch Container-Optimized images.
       string image = 4;
 
       // Name of a snapshot used as the data source.
+      // Snapshot is not supported as boot disk now.
       string snapshot = 5;
     }
 
@@ -334,6 +340,7 @@ message AllocationPolicy {
     string type = 1;
 
     // Disk size in GB.
+    //
     // For persistent disk, this field is ignored if `data_source` is `image` or
     // `snapshot`.
     // For local SSD, size_gb should be a multiple of 375GB,
@@ -391,7 +398,7 @@ message AllocationPolicy {
 
     // The minimum CPU platform.
     // See
-    // `https://cloud.google.com/compute/docs/instances/specify-min-cpu-platform`.
+    // https://cloud.google.com/compute/docs/instances/specify-min-cpu-platform.
     // Not yet implemented.
     string min_cpu_platform = 3;
 
@@ -401,15 +408,17 @@ message AllocationPolicy {
     // The accelerators attached to each VM instance.
     repeated Accelerator accelerators = 5;
 
-    // Book disk to be created and attached to each VM by this InstancePolicy.
+    // Boot disk to be created and attached to each VM by this InstancePolicy.
     // Boot disk will be deleted when the VM is deleted.
+    // Batch API now only supports booting from image.
     Disk boot_disk = 8;
 
     // Non-boot disks to be attached for each VM created by this InstancePolicy.
     // New disks will be deleted when the VM is deleted.
     repeated AttachedDisk disks = 6;
 
-    // If specified, VMs will be allocated only inside the matching reservation.
+    // If specified, VMs will consume only the specified reservation.
+    // If not specified (default), VMs will consume any applicable reservation.
     string reservation = 7;
   }
 
@@ -436,18 +445,22 @@ message AllocationPolicy {
   message NetworkInterface {
     // The URL of an existing network resource.
     // You can specify the network as a full or partial URL.
+    //
     // For example, the following are all valid URLs:
-    // https://www.googleapis.com/compute/v1/projects/{project}/global/networks/{network}
-    // projects/{project}/global/networks/{network}
-    // global/networks/{network}
+    //
+    // * https://www.googleapis.com/compute/v1/projects/{project}/global/networks/{network}
+    // * projects/{project}/global/networks/{network}
+    // * global/networks/{network}
     string network = 1;
 
     // The URL of an existing subnetwork resource in the network.
     // You can specify the subnetwork as a full or partial URL.
+    //
     // For example, the following are all valid URLs:
-    // https://www.googleapis.com/compute/v1/projects/{project}/regions/{region}/subnetworks/{subnetwork}
-    // projects/{project}/regions/{region}/subnetworks/{subnetwork}
-    // regions/{region}/subnetworks/{subnetwork}
+    //
+    // * https://www.googleapis.com/compute/v1/projects/{project}/regions/{region}/subnetworks/{subnetwork}
+    // * projects/{project}/regions/{region}/subnetworks/{subnetwork}
+    // * regions/{region}/subnetworks/{subnetwork}
     string subnetwork = 2;
 
     // Default is false (with an external IP address). Required if
@@ -466,6 +479,23 @@ message AllocationPolicy {
     repeated NetworkInterface network_interfaces = 1;
   }
 
+  // PlacementPolicy describes a group placement policy for the VMs controlled
+  // by this AllocationPolicy.
+  message PlacementPolicy {
+    // UNSPECIFIED vs. COLLOCATED (default UNSPECIFIED). Use COLLOCATED when you
+    // want VMs to be located close to each other for low network latency
+    // between the VMs. No placement policy will be generated when collocation
+    // is UNSPECIFIED.
+    string collocation = 1;
+
+    // When specified, causes the job to fail if more than max_distance logical
+    // switches are required between VMs. Batch uses the most compact possible
+    // placement of VMs even when max_distance is not specified. An explicit
+    // max_distance makes that level of compactness a strict requirement.
+    // Not yet implemented
+    int64 max_distance = 2;
+  }
+
   // Compute Engine VM instance provisioning model.
   enum ProvisioningModel {
     // Unspecified.
@@ -519,6 +549,9 @@ message AllocationPolicy {
 
   // The network policy.
   NetworkPolicy network = 7;
+
+  // The placement policy.
+  PlacementPolicy placement = 10;
 }
 
 // A TaskGroup contains one or multiple Tasks that share the same
@@ -535,7 +568,15 @@ message TaskGroup {
     SCHEDULING_POLICY_UNSPECIFIED = 0;
 
     // Run Tasks as soon as resources are available.
+    //
+    // Tasks might be executed in parallel depending on parallelism and
+    // task_count values.
     AS_SOON_AS_POSSIBLE = 1;
+
+    // Run Tasks sequentially with increased task index.
+    //
+    // Not yet implemented.
+    IN_ORDER = 2;
   }
 
   // Output only. TaskGroup name.
@@ -548,14 +589,16 @@ message TaskGroup {
   TaskSpec task_spec = 3 [(google.api.field_behavior) = REQUIRED];
 
   // Number of Tasks in the TaskGroup.
-  // default is 1
+  // Default is 1.
   int64 task_count = 4;
 
   // Max number of tasks that can run in parallel.
   // Default to min(task_count, 1000).
+  // Field parallelism must be 1 if the scheduling_policy is IN_ORDER.
   int64 parallelism = 5;
 
   // Scheduling policy for Tasks in the TaskGroup.
+  // The default value is AS_SOON_AS_POSSIBLE.
   SchedulingPolicy scheduling_policy = 6;
 
   // Compute resource allocation for the TaskGroup.

google/cloud/batch/v1alpha/task.proto

@@ -77,7 +77,7 @@ message TaskExecution {
 message TaskStatus {
   // Task states.
   enum State {
-    // unknown state
+    // Unknown state.
     STATE_UNSPECIFIED = 0;
 
     // The Task is created and waiting for resources.
@@ -94,6 +94,9 @@ message TaskStatus {
 
     // The Task has succeeded.
     SUCCEEDED = 5;
+
+    // The Task has not been executed when the Job finishes.
+    UNEXECUTED = 6;
   }
 
   // Task state
@@ -139,8 +142,9 @@ message Runnable {
     string options = 8;
 
     // If set to true, external network access to and from container will be
-    // blocked. The container will use the default internal network
-    // 'goog-internal'.
+    // blocked, containers that are with block_external_network as true can
+    // still communicate with each other, network cannot be specified in the
+    // `container.options` field.
     bool block_external_network = 9;
 
     // Optional username for logging in to a docker registry. If username