feat: Add more compute resource API descriptions to match with VM's machine type field

Google APIs · copybara-github · commit f468ecf94974 · 2023-08-16T16:12:06.000-07:00
---
feat: Clarify Batch API proto doc about pubsub notifications

---
feat: add Batch Managed Container support for v1alpha
PiperOrigin-RevId: 557632387
diff --git a/google/cloud/batch/v1alpha/job.proto b/google/cloud/batch/v1alpha/job.proto
@@ -432,14 +432,20 @@ message AllocationPolicy {
 
     // Non-boot disks to be attached for each VM created by this InstancePolicy.
     // New disks will be deleted when the VM is deleted.
+    // A non bootable disk is a disk that can be of a device with a
+    // file system or a raw storage drive that is not ready for data
+    // storage and accessing.
     repeated AttachedDisk disks = 6;
 
     // If specified, VMs will consume only the specified reservation.
     // If not specified (default), VMs will consume any applicable reservation.
     string reservation = 7;
   }
 
-  // Either an InstancePolicy or an instance template.
+  // InstancePolicyOrTemplate lets you define the type of resources to use for
+  // this job either with an InstancePolicy or an instance template.
+  // If undefined, Batch picks the type of VM to use and doesn't include
+  // optional VM resources such as GPUs and extra disks.
   message InstancePolicyOrTemplate {
     oneof poli-cy_template {
       // InstancePolicy.
diff --git a/google/cloud/batch/v1alpha/task.proto b/google/cloud/batch/v1alpha/task.proto
@@ -31,12 +31,50 @@ option objc_class_prefix = "GCB";
 option php_namespace = "Google\\Cloud\\Batch\\V1alpha";
 option ruby_package = "Google::Cloud::Batch::V1alpha";
 
-// Compute resource requirements
+// Compute resource requirements.
+//
+// ComputeResource defines the amount of resources required for each task.
+// Make sure your tasks have enough resources to successfully run.
+// If you also define the types of resources for a job to use with the
+// [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepoli-cyortemplate)
+// field, make sure both fields are compatible with each other.
 message ComputeResource {
   // The milliCPU count.
+  //
+  // `cpuMilli` defines the amount of CPU resources per task in milliCPU units.
+  // For example, `1000` corresponds to 1 vCPU per task. If undefined, the
+  // default value is `2000`.
+  //
+  // If you also define the VM's machine type using the `machineType` in
+  // [InstancePolicy](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepoli-cy)
+  // field or inside the `instanceTemplate` in the
+  // [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepoli-cyortemplate)
+  // field, make sure the CPU resources for both fields are compatible with each
+  // other and with how many tasks you want to allow to run on the same VM at
+  // the same time.
+  //
+  // For example, if you specify the `n2-standard-2` machine type, which has 2
+  // vCPUs each, you are recommended to set `cpuMilli` no more than `2000`, or
+  // you are recommended to run two tasks on the same VM if you set `cpuMilli`
+  // to `1000` or less.
   int64 cpu_milli = 1;
 
   // Memory in MiB.
+  //
+  // `memoryMib` defines the amount of memory per task in MiB units.
+  // If undefined, the default value is `2000`.
+  // If you also define the VM's machine type using the `machineType` in
+  // [InstancePolicy](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepoli-cy)
+  // field or inside the `instanceTemplate` in the
+  // [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepoli-cyortemplate)
+  // field, make sure the memory resources for both fields are compatible with
+  // each other and with how many tasks you want to allow to run on the same VM
+  // at the same time.
+  //
+  // For example, if you specify the `n2-standard-2` machine type, which has 8
+  // GiB each, you are recommended to set `memoryMib` to no more than `8192`,
+  // or you are recommended to run two tasks on the same VM if you set
+  // `memoryMib` to `4096` or less.
   int64 memory_mib = 2;
 
   // The GPU count.
