feat: [batch] add support for placement policies

packages/google-cloud-batch/README.md

@@ -2,7 +2,7 @@
 [//]: # "To regenerate it, use `python -m synthtool`."
 <img src="https://avatars2.githubusercontent.com/u/2810941?v=3&s=96" alt="Google Cloud Platform logo" title="Google Cloud Platform" align="right" height="96" width="96"/>
 
-# [Batch: Node.js Client](https://github.com/googleapis/google-cloud-node)
+# [Batch: Node.js Client](https://github.com/googleapis/google-cloud-node/tree/main/packages/google-cloud-batch)
 
 [![release level](https://img.shields.io/badge/release%20level-preview-yellow.svg?style=flat)](https://cloud.google.com/terms/launch-stages)
 [![npm version](https://img.shields.io/npm/v/@google-cloud/batch.svg)](https://www.npmjs.org/package/@google-cloud/batch)
@@ -107,24 +107,23 @@ callListJobs();
 
 ## Samples
 
-Samples are in the [`samples/`](https://github.com/googleapis/google-cloud-node/tree/main/samples) directory. Each sample's `README.md` has instructions for running its sample.
+Samples are in the [`samples/`](https://github.com/googleapis/google-cloud-node/tree/main/packages/google-cloud-batch/samples) directory. Each sample's `README.md` has instructions for running its sample.
 
 | Sample                      | Source Code                       | Try it |
 | --------------------------- | --------------------------------- | ------ |
-| Batch_service.create_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1/batch_service.create_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1/batch_service.create_job.js,samples/README.md) |
-| Batch_service.delete_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1/batch_service.delete_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1/batch_service.delete_job.js,samples/README.md) |
-| Batch_service.get_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1/batch_service.get_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1/batch_service.get_job.js,samples/README.md) |
-| Batch_service.get_task | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1/batch_service.get_task.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1/batch_service.get_task.js,samples/README.md) |
-| Batch_service.list_jobs | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1/batch_service.list_jobs.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1/batch_service.list_jobs.js,samples/README.md) |
-| Batch_service.list_tasks | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1/batch_service.list_tasks.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1/batch_service.list_tasks.js,samples/README.md) |
-| Batch_service.create_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1alpha/batch_service.create_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1alpha/batch_service.create_job.js,samples/README.md) |
-| Batch_service.delete_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1alpha/batch_service.delete_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1alpha/batch_service.delete_job.js,samples/README.md) |
-| Batch_service.get_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1alpha/batch_service.get_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1alpha/batch_service.get_job.js,samples/README.md) |
-| Batch_service.get_task | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1alpha/batch_service.get_task.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1alpha/batch_service.get_task.js,samples/README.md) |
-| Batch_service.list_jobs | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1alpha/batch_service.list_jobs.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1alpha/batch_service.list_jobs.js,samples/README.md) |
-| Batch_service.list_tasks | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1alpha/batch_service.list_tasks.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1alpha/batch_service.list_tasks.js,samples/README.md) |
-| Quickstart | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/quickstart.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/quickstart.js,samples/README.md) |
-| Quickstart | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/test/quickstart.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/test/quickstart.js,samples/README.md) |
+| Batch_service.create_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1/batch_service.create_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1/batch_service.create_job.js,packages/google-cloud-batch/samples/README.md) |
+| Batch_service.delete_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1/batch_service.delete_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1/batch_service.delete_job.js,packages/google-cloud-batch/samples/README.md) |
+| Batch_service.get_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1/batch_service.get_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1/batch_service.get_job.js,packages/google-cloud-batch/samples/README.md) |
+| Batch_service.get_task | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1/batch_service.get_task.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1/batch_service.get_task.js,packages/google-cloud-batch/samples/README.md) |
+| Batch_service.list_jobs | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1/batch_service.list_jobs.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1/batch_service.list_jobs.js,packages/google-cloud-batch/samples/README.md) |
+| Batch_service.list_tasks | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1/batch_service.list_tasks.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1/batch_service.list_tasks.js,packages/google-cloud-batch/samples/README.md) |
+| Batch_service.create_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1alpha/batch_service.create_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1alpha/batch_service.create_job.js,packages/google-cloud-batch/samples/README.md) |
+| Batch_service.delete_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1alpha/batch_service.delete_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1alpha/batch_service.delete_job.js,packages/google-cloud-batch/samples/README.md) |
+| Batch_service.get_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1alpha/batch_service.get_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1alpha/batch_service.get_job.js,packages/google-cloud-batch/samples/README.md) |
+| Batch_service.get_task | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1alpha/batch_service.get_task.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1alpha/batch_service.get_task.js,packages/google-cloud-batch/samples/README.md) |
+| Batch_service.list_jobs | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1alpha/batch_service.list_jobs.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1alpha/batch_service.list_jobs.js,packages/google-cloud-batch/samples/README.md) |
+| Batch_service.list_tasks | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/generated/v1alpha/batch_service.list_tasks.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/generated/v1alpha/batch_service.list_tasks.js,packages/google-cloud-batch/samples/README.md) |
+| Quickstart | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-batch/samples/quickstart.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-batch/samples/quickstart.js,packages/google-cloud-batch/samples/README.md) |
 
 
 

packages/google-cloud-batch/protos/google/cloud/batch/v1/job.proto

@@ -225,12 +225,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",
@@ -241,25 +243,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;
     }
 
@@ -270,6 +276,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,
@@ -324,7 +331,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;
 
@@ -334,8 +341,9 @@ 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.
@@ -366,18 +374,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
@@ -396,6 +408,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.
@@ -437,6 +466,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
@@ -457,11 +489,12 @@ 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;
 
   // An array of environment variable mappings, which are passed to Tasks with