feat: Adds named reservation to InstancePolicy (#3672)

* feat: Adds named reservation to InstancePolicy

---
docs:Remove "not yet implemented" for Accelerator & Refine Volume API docs

---
docs: update the job id format requirement

PiperOrigin-RevId: 489501779

Source-Link: googleapis/googleapis@488a4bd

Source-Link: googleapis/googleapis-gen@5b3d3a5
Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLWJhdGNoLy5Pd2xCb3QueWFtbCIsImgiOiI1YjNkM2E1NTAwMTVlOTM2N2FkMTNlZTVmOWZlYmUwYzNmODRjZjMzIn0=

* feat: Adds named reservation to InstancePolicy

---
docs:Remove "not yet implemented" for Accelerator & Refine Volume API docs

---
docs: update the job id format requirement

PiperOrigin-RevId: 489502315

Source-Link: googleapis/googleapis@db1cc11

Source-Link: googleapis/googleapis-gen@fcc564e
Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLWJhdGNoLy5Pd2xCb3QueWFtbCIsImgiOiJmY2M1NjRlZjA2NGM3ZGZmMzFkNzk3MGUxMjMxOGFkMDg0NzAzYWM2In0=

* docs: fix minor docstring formatting

PiperOrigin-RevId: 490003354

Source-Link: googleapis/googleapis@9afb89b

Source-Link: googleapis/googleapis-gen@c51774c
Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLWJhdGNoLy5Pd2xCb3QueWFtbCIsImgiOiJjNTE3NzRjZDhkZDU4MDRkNWVjNmYzMzViMTg1NWMyOGQxMTcxYTU2In0=

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
Co-authored-by: sofisl <55454395+sofisl@users.noreply.github.com>

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

@@ -107,8 +107,9 @@ message CreateJobRequest {
   ];
 
   // ID used to uniquely identify the Job within its parent scope.
-  // This field should contain at most 63 characters.
-  // Only alphanumeric characters or '-' are accepted.
+  // This field should contain at most 63 characters and must start with
+  // lowercase characters.
+  // Only lowercase characters, numbers and '-' are accepted.
   // The '-' character cannot be the first or the last one.
   // A system generated ID will be used if the field is not set.
   //

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

@@ -263,7 +263,7 @@ message AllocationPolicy {
     string disk_interface = 6;
   }
 
-  // A new or an existing persistent disk or a local ssd attached to a VM
+  // A new or an existing persistent disk (PD) or a local ssd attached to a VM
   // instance.
   message AttachedDisk {
     oneof attached {
@@ -280,7 +280,7 @@ message AllocationPolicy {
     string device_name = 3;
   }
 
-  // Accelerator describes Compute Engine accelerators to be attached to VMs.
+  // Accelerator describes Compute Engine accelerators to be attached to the VM.
   message Accelerator {
     // The accelerator type. For example, "nvidia-tesla-t4".
     // See `gcloud compute accelerator-types list`.
@@ -309,11 +309,10 @@ message AllocationPolicy {
     ProvisioningModel provisioning_model = 4;
 
     // The accelerators attached to each VM instance.
-    // Not yet implemented.
     repeated Accelerator accelerators = 5;
 
     // Non-boot disks to be attached for each VM created by this InstancePolicy.
-    // New disks will be deleted when the attached VM is deleted.
+    // New disks will be deleted when the VM is deleted.
     repeated AttachedDisk disks = 6;
   }
 

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

@@ -25,46 +25,50 @@ option objc_class_prefix = "GCB";
 option php_namespace = "Google\\Cloud\\Batch\\V1";
 option ruby_package = "Google::Cloud::Batch::V1";
 
-// Volume and mount parameters to be associated with a TaskSpec. A TaskSpec
-// might describe zero, one, or multiple volumes to be mounted as part of the
-// task.
+// Volume describes a volume and parameters for it to be mounted to a VM.
 message Volume {
   // The source for the volume.
   oneof source {
-    // An NFS source for the volume (could be a Filestore, for example).
+    // A Network File System (NFS) volume. For example, a
+    // Filestore file share.
     NFS nfs = 1;
 
-    // A Google Cloud Storage source for the volume.
+    // A Google Cloud Storage (GCS) volume.
     GCS gcs = 3;
 
-    // Device name of an attached disk
+    // Device name of an attached disk volume, which should align with a
+    // device_name specified by
+    // job.allocation_policy.instances[0].policy.disks[i].device_name or
+    // defined by the given instance template in
+    // job.allocation_policy.instances[0].instance_template.
     string device_name = 6;
   }
 
-  // Mount path for the volume, e.g. /mnt/share
+  // The mount path for the volume, e.g. /mnt/disks/share.
   string mount_path = 4;
 
-  // Mount options
-  // For Google Cloud Storage, mount options are the global options supported by
-  // gcsfuse tool. Batch will use them to mount the volume with the following
-  // command:
-  // "gcsfuse [global options] bucket mountpoint".
-  // For PD, NFS, mount options are these supported by /etc/fstab. Batch will
-  // use Fstab to mount such volumes.
-  // https://help.ubuntu.com/community/Fstab
+  // For Google Cloud Storage (GCS), mount options are the options supported by
+  // the gcsfuse tool (https://github.com/GoogleCloudPlatform/gcsfuse).
+  // For existing persistent disks, mount options provided by the
+  // mount command (https://man7.org/linux/man-pages/man8/mount.8.html) except
+  // writing are supported. This is due to restrictions of multi-writer mode
+  // (https://cloud.google.com/compute/docs/disks/sharing-disks-between-vms).
+  // For other attached disks and Network File System (NFS), mount options are
+  // these supported by the mount command
+  // (https://man7.org/linux/man-pages/man8/mount.8.html).
   repeated string mount_options = 5;
 }
 
-// Represents an NFS server and remote path: <server>:<remote_path>
+// Represents an NFS volume.
 message NFS {
-  // URI of the NFS server, e.g. an IP address.
+  // The IP address of the NFS.
   string server = 1;
 
-  // Remote source path exported from NFS, e.g., "/share".
+  // Remote source path exported from the NFS, e.g., "/share".
   string remote_path = 2;
 }
 
-// Represents a Google Cloud Storage volume source config.
+// Represents a Google Cloud Storage volume.
 message GCS {
   // Remote path, either a bucket name or a subdirectory of a bucket, e.g.:
   // bucket_name, bucket_name/subdirectory/

packages/google-cloud-batch/protos/google/cloud/batch/v1alpha/batch.proto

@@ -107,8 +107,9 @@ message CreateJobRequest {
   ];
 
   // ID used to uniquely identify the Job within its parent scope.
-  // This field should contain at most 63 characters.
-  // Only alphanumeric characters or '-' are accepted.
+  // This field should contain at most 63 characters and must start with
+  // lowercase characters.
+  // Only lowercase characters, numbers and '-' are accepted.
   // The '-' character cannot be the first or the last one.
   // A system generated ID will be used if the field is not set.
   //

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

@@ -318,7 +318,7 @@ message AllocationPolicy {
     string disk_interface = 6;
   }
 
-  // A new or an existing persistent disk or a local ssd attached to a VM
+  // A new or an existing persistent disk (PD) or a local ssd attached to a VM
   // instance.
   message AttachedDisk {
     oneof attached {
@@ -335,7 +335,7 @@ message AllocationPolicy {
     string device_name = 3;
   }
 
-  // Accelerator describes Compute Engine accelerators to be attached to VMs.
+  // Accelerator describes Compute Engine accelerators to be attached to the VM.
   message Accelerator {
     // The accelerator type. For example, "nvidia-tesla-t4".
     // See `gcloud compute accelerator-types list`.
@@ -367,12 +367,14 @@ message AllocationPolicy {
     ProvisioningModel provisioning_model = 4;
 
     // The accelerators attached to each VM instance.
-    // Not yet implemented.
     repeated Accelerator accelerators = 5;
 
     // Non-boot disks to be attached for each VM created by this InstancePolicy.
-    // New disks will be deleted when the attached VM is deleted.
+    // 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.
+    string reservation = 7;
   }
 
   // Either an InstancePolicy or an instance template.
@@ -451,7 +453,7 @@ message AllocationPolicy {
   // Deprecated: please use instances[0].template instead.
   repeated string instance_templates = 3 [deprecated = true];
 
-  // Deprecated: please use instances[i].policy.provisioning_model instead.
+  // Deprecated: please use instances[0].policy.provisioning_model instead.
   repeated ProvisioningModel provisioning_models = 4 [deprecated = true];
 
   // Deprecated: please use service_account instead.

packages/google-cloud-batch/protos/google/cloud/batch/v1alpha/volume.proto

@@ -25,49 +25,53 @@ option objc_class_prefix = "GCB";
 option php_namespace = "Google\\Cloud\\Batch\\V1alpha";
 option ruby_package = "Google::Cloud::Batch::V1alpha";
 
-// Volume and mount parameters to be associated with a TaskSpec. A TaskSpec
-// might describe zero, one, or multiple volumes to be mounted as part of the
-// task.
+// Volume describes a volume and parameters for it to be mounted to a VM.
 message Volume {
   // The source for the volume.
   oneof source {
-    // An NFS source for the volume (could be a Filestore, for example).
+    // A Network File System (NFS) volume. For example, a
+    // Filestore file share.
     NFS nfs = 1;
 
-    // A persistent disk source for the volume.
+    // Deprecated: please use device_name instead.
     PD pd = 2 [deprecated = true];
 
-    // A Google Cloud Storage source for the volume.
+    // A Google Cloud Storage (GCS) volume.
     GCS gcs = 3;
 
-    // Device name of an attached disk
+    // Device name of an attached disk volume, which should align with a
+    // device_name specified by
+    // job.allocation_policy.instances[0].policy.disks[i].device_name or
+    // defined by the given instance template in
+    // job.allocation_policy.instances[0].instance_template.
     string device_name = 6;
   }
 
-  // Mount path for the volume, e.g. /mnt/share
+  // The mount path for the volume, e.g. /mnt/disks/share.
   string mount_path = 4;
 
-  // Mount options
-  // For Google Cloud Storage, mount options are the global options supported by
-  // gcsfuse tool. Batch will use them to mount the volume with the following
-  // command:
-  // "gcsfuse [global options] bucket mountpoint".
-  // For PD, NFS, mount options are these supported by /etc/fstab. Batch will
-  // use Fstab to mount such volumes.
-  // https://help.ubuntu.com/community/Fstab
+  // For Google Cloud Storage (GCS), mount options are the options supported by
+  // the gcsfuse tool (https://github.com/GoogleCloudPlatform/gcsfuse).
+  // For existing persistent disks, mount options provided by the
+  // mount command (https://man7.org/linux/man-pages/man8/mount.8.html) except
+  // writing are supported. This is due to restrictions of multi-writer mode
+  // (https://cloud.google.com/compute/docs/disks/sharing-disks-between-vms).
+  // For other attached disks and Network File System (NFS), mount options are
+  // these supported by the mount command
+  // (https://man7.org/linux/man-pages/man8/mount.8.html).
   repeated string mount_options = 5;
 }
 
-// Represents an NFS server and remote path: <server>:<remote_path>
+// Represents an NFS volume.
 message NFS {
-  // URI of the NFS server, e.g. an IP address.
+  // The IP address of the NFS.
   string server = 1;
 
-  // Remote source path exported from NFS, e.g., "/share".
+  // Remote source path exported from the NFS, e.g., "/share".
   string remote_path = 2;
 }
 
-// Represents a GCP persistent disk
+// Deprecated: please use device_name instead.
 message PD {
   // PD disk name, e.g. pd-1.
   string disk = 1;
@@ -82,7 +86,7 @@ message PD {
   bool existing = 3 [deprecated = true];
 }
 
-// Represents a Google Cloud Storage volume source config.
+// Represents a Google Cloud Storage volume.
 message GCS {
   // Remote path, either a bucket name or a subdirectory of a bucket, e.g.:
   // bucket_name, bucket_name/subdirectory/

packages/google-cloud-batch/samples/generated/v1/batch_service.create_job.js

@@ -35,8 +35,9 @@ function main(parent, job) {
   // const parent = 'abc123'
   /**
    *  ID used to uniquely identify the Job within its parent scope.
-   *  This field should contain at most 63 characters.
-   *  Only alphanumeric characters or '-' are accepted.
+   *  This field should contain at most 63 characters and must start with
+   *  lowercase characters.
+   *  Only lowercase characters, numbers and '-' are accepted.
    *  The '-' character cannot be the first or the last one.
    *  A system generated ID will be used if the field is not set.
    *  The job.name field in the request will be ignored and the created resource

packages/google-cloud-batch/samples/generated/v1/snippet_metadata.google.cloud.batch.v1.json

@@ -22,7 +22,7 @@
             "segments": [
                 {
                     "start": 25,
-                    "end": 83,
+                    "end": 84,
                     "type": "FULL"
                 }
             ],

packages/google-cloud-batch/samples/generated/v1alpha/batch_service.create_job.js

@@ -35,8 +35,9 @@ function main(parent, job) {
   // const parent = 'abc123'
   /**
    *  ID used to uniquely identify the Job within its parent scope.
-   *  This field should contain at most 63 characters.
-   *  Only alphanumeric characters or '-' are accepted.
+   *  This field should contain at most 63 characters and must start with
+   *  lowercase characters.
+   *  Only lowercase characters, numbers and '-' are accepted.
    *  The '-' character cannot be the first or the last one.
    *  A system generated ID will be used if the field is not set.
    *  The job.name field in the request will be ignored and the created resource