docs: [batch] Update description on size_gb in disk field (#9744)

- [ ] Regenerate this pull request now. PiperOrigin-RevId: 561181917 Source-Link: https://togithub.com/googleapis/googleapis/commit/a5482b455263371132e79a0d71d9c64e8b85c8f9 Source-Link: https://togithub.com/googleapis/googleapis-gen/commit/b316d2d224f94d01d2574c2f8e465a527a2311dd Copy-Tag: eyJwIjoiamF2YS1iYXRjaC8uT3dsQm90LnlhbWwiLCJoIjoiYjMxNmQyZDIyNGY5NGQwMWQyNTc0YzJmOGU0NjVhNTI3YTIzMTFkZCJ9 BEGIN_NESTED_COMMIT docs: [batch] Update description on size_gb in disk field PiperOrigin-RevId: 561181668 Source-Link: https://togithub.com/googleapis/googleapis/commit/e853fcb214c3b8d3912e5f0cc4fff62612333908 Source-Link: https://togithub.com/googleapis/googleapis-gen/commit/ba130c2e39cebf4dd274f2d3582d676f79b22af8 Copy-Tag: eyJwIjoiamF2YS1iYXRjaC8uT3dsQm90LnlhbWwiLCJoIjoiYmExMzBjMmUzOWNlYmY0ZGQyNzRmMmQzNTgyZDY3NmY3OWIyMmFmOCJ9 END_NESTED_COMMIT BEGIN_NESTED_COMMIT feat: [batch] add stderr_snippet to indicate the real stderr output by runnables to the execution field of status event docs: update comments PiperOrigin-RevId: 559249641 Source-Link: https://togithub.com/googleapis/googleapis/commit/83585eb73c203ea88debedb8f8b14d26902a5f41 Source-Link: https://togithub.com/googleapis/googleapis-gen/commit/411a8e33e0f1474c36aeecfadddfccb86605528f Copy-Tag: eyJwIjoiamF2YS1iYXRjaC8uT3dsQm90LnlhbWwiLCJoIjoiNDExYThlMzNlMGYxNDc0YzM2YWVlY2ZhZGRkZmNjYjg2NjA1NTI4ZiJ9 END_NESTED_COMMIT BEGIN_NESTED_COMMIT docs: [batch] Revert HTML formats in comments docs: Expand compute resource API docs to match with VM's machine type field docs: Clarify Batch API proto doc about pubsub notifications PiperOrigin-RevId: 558940776 Source-Link: https://togithub.com/googleapis/googleapis/commit/a7ee700713a504f857e347862112617aca8675ac Source-Link: https://togithub.com/googleapis/googleapis-gen/commit/4f3a485f3ceb13b67e0522b74a7fd9ccde2aa6a1 Copy-Tag: eyJwIjoiamF2YS1iYXRjaC8uT3dsQm90LnlhbWwiLCJoIjoiNGYzYTQ4NWYzY2ViMTNiNjdlMDUyMmI3NGE3ZmQ5Y2NkZTJhYTZhMSJ9 END_NESTED_COMMIT BEGIN_NESTED_COMMIT feat: [batch] Add more compute resource API descriptions to match with VM's machine type field --- feat: Clarify Batch API proto doc about pubsub notifications --- feat: add Batch Managed Container support for v1alpha PiperOrigin-RevId: 557632387 Source-Link: https://togithub.com/googleapis/googleapis/commit/f468ecf949741d817fe806aebabb7adae1609585 Source-Link: https://togithub.com/googleapis/googleapis-gen/commit/00118954974d7743ebbe312f5eda356e2cb9c79a Copy-Tag: eyJwIjoiamF2YS1iYXRjaC8uT3dsQm90LnlhbWwiLCJoIjoiMDAxMTg5NTQ5NzRkNzc0M2ViYmUzMTJmNWVkYTM1NmUyY2I5Yzc5YSJ9 END_NESTED_COMMIT BEGIN_NESTED_COMMIT feat: [batch] Clarify Batch API proto doc about pubsub notifications --- feat: add Batch Managed Container support for v1alpha PiperOrigin-RevId: 554850516 Source-Link: https://togithub.com/googleapis/googleapis/commit/28b8748b79e3b85980295751bbfaeaa28e774b96 Source-Link: https://togithub.com/googleapis/googleapis-gen/commit/69f99df3a03ebdc1dd0265bd3d99b3ed49dc57cd Copy-Tag: eyJwIjoiamF2YS1iYXRjaC8uT3dsQm90LnlhbWwiLCJoIjoiNjlmOTlkZjNhMDNlYmRjMWRkMDI2NWJkM2Q5OWIzZWQ0OWRjNTdjZCJ9 END_NESTED_COMMIT

Author: gcf-owl-bot[bot]

java-batch/README.md

@@ -23,7 +23,7 @@ If you are using Maven with [BOM][libraries-bom], add this to your pom.xml file:
  <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>libraries-bom</artifactId>
- <version>26.21.0</version>
+ <version>26.22.0</version>
  <type>pom</type>
  <scope>import</scope>
  </dependency>
@@ -201,7 +201,7 @@ Java is a registered trademark of Oracle and/or its affiliates.
 [kokoro-badge-link-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java11.html
 [stability-image]: https://img.shields.io/badge/stability-preview-yellow
 [maven-version-image]: https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-batch.svg
-[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-batch/0.22.0
+[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-batch/0.23.0
 [authentication]: https://github.com/googleapis/google-cloud-java#authentication
 [auth-scopes]: https://developers.google.com/identity/protocols/oauth2/scopes
 [predefined-iam-roles]: https://cloud.google.com/iam/docs/understanding-roles#predefined_roles

java-batch/proto-google-cloud-batch-v1/src/main/java/com/google/cloud/batch/v1/AllocationPolicy.java

@@ -22,7 +22,13 @@
  *
  *
  * <pre>
- * 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#instancepolicyortemplate)
+ * field, make sure both fields are compatible with each other.
  * </pre>
  *
  * Protobuf type {@code google.cloud.batch.v1.ComputeResource}
@@ -67,6 +73,23 @@ public static final com.google.protobuf.Descriptors.Descriptor getDescriptor() {
  *
  * <pre>
  * 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#instancepolicy)
+ * field or inside the `instanceTemplate` in the
+ * [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicyortemplate)
+ * 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.
  * </pre>
  *
  * <code>int64 cpu_milli = 1;</code>
@@ -85,6 +108,21 @@ public long getCpuMilli() {
  *
  * <pre>
  * 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#instancepolicy)
+ * field or inside the `instanceTemplate` in the
+ * [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicyortemplate)
+ * 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.
  * </pre>
  *
  * <code>int64 memory_mib = 2;</code>
@@ -295,7 +333,13 @@ protected Builder newBuilderForType(com.google.protobuf.GeneratedMessageV3.Build
  *
  *
  * <pre>
- * 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#instancepolicyortemplate)
+ * field, make sure both fields are compatible with each other.
  * </pre>
  *
  * Protobuf type {@code google.cloud.batch.v1.ComputeResource}
@@ -503,6 +547,23 @@ public Builder mergeFrom(
  *
  * <pre>
  * 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#instancepolicy)
+ * field or inside the `instanceTemplate` in the
+ * [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicyortemplate)
+ * 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.
  * </pre>
  *
  * <code>int64 cpu_milli = 1;</code>
@@ -518,6 +579,23 @@ public long getCpuMilli() {
  *
  * <pre>
  * 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#instancepolicy)
+ * field or inside the `instanceTemplate` in the
+ * [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicyortemplate)
+ * 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.
  * </pre>
  *
  * <code>int64 cpu_milli = 1;</code>
@@ -537,6 +615,23 @@ public Builder setCpuMilli(long value) {
  *
  * <pre>
  * 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#instancepolicy)
+ * field or inside the `instanceTemplate` in the
+ * [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicyortemplate)
+ * 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.
  * </pre>
  *
  * <code>int64 cpu_milli = 1;</code>
@@ -556,6 +651,21 @@ public Builder clearCpuMilli() {
  *
  * <pre>
  * 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#instancepolicy)
+ * field or inside the `instanceTemplate` in the
+ * [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicyortemplate)
+ * 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.
  * </pre>
  *
  * <code>int64 memory_mib = 2;</code>
@@ -571,6 +681,21 @@ public long getMemoryMib() {
  *
  * <pre>
  * 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#instancepolicy)
+ * field or inside the `instanceTemplate` in the
+ * [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicyortemplate)
+ * 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.
  * </pre>
  *
  * <code>int64 memory_mib = 2;</code>
@@ -590,6 +715,21 @@ public Builder setMemoryMib(long value) {
  *
  * <pre>
  * 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#instancepolicy)
+ * field or inside the `instanceTemplate` in the
+ * [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicyortemplate)
+ * 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.
  * </pre>
  *
  * <code>int64 memory_mib = 2;</code>

java-batch/proto-google-cloud-batch-v1/src/main/java/com/google/cloud/batch/v1/ComputeResource.java

@@ -28,6 +28,23 @@ public interface ComputeResourceOrBuilder
  *
  * <pre>
  * 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#instancepolicy)
+ * field or inside the `instanceTemplate` in the
+ * [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicyortemplate)
+ * 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.
  * </pre>
  *
  * <code>int64 cpu_milli = 1;</code>
@@ -41,6 +58,21 @@ public interface ComputeResourceOrBuilder
  *
  * <pre>
  * 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#instancepolicy)
+ * field or inside the `instanceTemplate` in the
+ * [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicyortemplate)
+ * 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.
  * </pre>
  *
  * <code>int64 memory_mib = 2;</code>

java-batch/proto-google-cloud-batch-v1/src/main/java/com/google/cloud/batch/v1/ComputeResourceOrBuilder.java

@@ -253,17 +253,14 @@ message AllocationPolicy {
  message Disk {
  // A data source from which a PD will be created.
  oneof data_source {
- // Name of an image used as the data source.
+ // URL for a VM image to use as the data source for this disk.
  // For example, the following are all valid URLs:
  //
  // * Specify the image by its family name:
- // <pre><code>projects/<var
- // class="apiparam">project</var>/global/images/family/<var
- // class="apiparam">image_family</var></code></pre>
+ // projects/{project}/global/images/family/{image_family}
  // * Specify the image version:
- // <pre>projects/<var
- // class="apiparam">project</var>/global/images/<var
- // class="apiparam">image_version</var></code></pre>
+ // 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:
  //
@@ -286,14 +283,23 @@ message AllocationPolicy {
 
  // 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,
- // otherwise, the final size will be the next greater multiple of 375 GB.
- // For boot disk, Batch will calculate the boot disk size based on source
+ // **Non-Boot Disk**:
+ // If the `type` specifies a persistent disk, this field
+ // is ignored if `data_source` is set as `image` or `snapshot`.
+ // If the `type` specifies a local SSD, this field should be a multiple of
+ // 375 GB, otherwise, the final size will be the next greater multiple of
+ // 375 GB.
+ //
+ // **Boot Disk**:
+ // Batch will calculate the boot disk size based on source
  // image and task requirements if you do not speicify the size.
- // If both this field and the boot_disk_mib field in task spec's
- // compute_resource are defined, Batch will only honor this field.
+ // If both this field and the `boot_disk_mib` field in task spec's
+ // `compute_resource` are defined, Batch will only honor this field.
+ // Also, this field should be no smaller than the source disk's
+ // size when the `data_source` is set as `snapshot` or `image`.
+ // For example, if you set an image as the `data_source` field and the
+ // image's default disk size 30 GB, you can only use this field to make the
+ // disk larger or equal to 30 GB.
  int64 size_gb = 2;
 
  // Local SSDs are available through both "SCSI" and "NVMe" interfaces.
@@ -365,10 +371,16 @@ 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-boot 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;
  }
 
- // 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 policy_template {
  // InstancePolicy.
@@ -399,30 +411,20 @@ message AllocationPolicy {
  // You can specify the network as a full or partial URL.
  //
  // For example, the following are all valid URLs:
- // <pre><code>https://www.googleapis.com/compute/v1/projects/<var
- // class="apiparam">project</var>/global/networks/<var
- // class="apiparam">network</var></code></pre>
- // <pre><code>projects/<var
- // class="apiparam">project</var>/global/networks/<var
- // class="apiparam">network</var></code></pre>
- // <pre><code>global/networks/<var
- // class="apiparam">network</var></code></pre>
+ //
+ // * 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:
- // <pre><code>https://www.googleapis.com/compute/v1/projects/<var
- // class="apiparam">project</var>/regions/<var
- // class="apiparam">region</var>/subnetworks/<var
- // class="apiparam">subnetwork</var></code></pre>
- // <pre><code>projects/<var class="apiparam">project</var>/regions/<var
- // class="apiparam">region</var>/subnetworks/<var
- // class="apiparam">subnetwork</var></code></pre>
- // <pre><code>regions/<var
- // class="apiparam">region</var>/subnetworks/<var
- // class="apiparam">subnetwork</var></code></pre>
+ //
+ // * 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