docs: [batch] clarify options for logs (#5864)

* docs: clarify options for logs
docs: Clarify the custom instance template needs to be in the same project

PiperOrigin-RevId: 702966613

Source-Link: googleapis/googleapis@2cb4e7a

Source-Link: googleapis/googleapis-gen@14a9205
Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLWJhdGNoLy5Pd2xCb3QueWFtbCIsImgiOiIxNGE5MjA1MjAxYjgwMDBhMmZlZGRhODk0ZTEwNTI1NmNlZWQ5MDc1In0=

* 🦉 Updates from OwlBot post-processor

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

* docs: clarify options for logs
docs: clarify the custom instance template needs to be in the same project

PiperOrigin-RevId: 703266926

Source-Link: googleapis/googleapis@3735100

Source-Link: googleapis/googleapis-gen@4190d79
Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLWJhdGNoLy5Pd2xCb3QueWFtbCIsImgiOiI0MTkwZDc5YzViOGU4ZjYyZjY2ZGIwZTFjMTgyMzA4YjgwMzdiOTRhIn0=

* 🦉 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: d-goog <188102366+d-goog@users.noreply.github.com>

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

@@ -90,13 +90,15 @@ message Job {
   repeated JobNotification notifications = 14;
 }
 
-// LogsPolicy describes how outputs from a Job's Tasks (stdout/stderr) will be
-// preserved.
+// LogsPolicy describes if and how a job's logs are preserved. Logs include
+// information that is automatically written by the Batch service agent and any
+// information that you configured the job's runnables to write to the `stdout`
+// or `stderr` streams.
 message LogsPolicy {
   // `CloudLoggingOption` contains additional settings for Cloud Logging logs
   // generated by Batch job.
   message CloudLoggingOption {
-    // Optional. Set this flag to true to change the [monitored resource
+    // Optional. Set this field to `true` to change the [monitored resource
     // type](https://cloud.google.com/monitoring/api/resources) for
     // Cloud Logging logs generated by this Batch job from
     // the
@@ -110,26 +112,32 @@ message LogsPolicy {
 
   // The destination (if any) for logs.
   enum Destination {
-    // Logs are not preserved.
+    // (Default) Logs are not preserved.
     DESTINATION_UNSPECIFIED = 0;
 
-    // Logs are streamed to Cloud Logging.
+    // Logs are streamed to Cloud Logging. Optionally, you can configure
+    // additional settings in the `cloudLoggingOption` field.
     CLOUD_LOGGING = 1;
 
-    // Logs are saved to a file path.
+    // Logs are saved to the file path specified in the `logsPath` field.
     PATH = 2;
   }
 
-  // Where logs should be saved.
+  // If and where logs should be saved.
   Destination destination = 1;
 
-  // The path to which logs are saved when the destination = PATH. This can be a
-  // local file path on the VM, or under the mount point of a Persistent Disk or
-  // Filestore, or a Cloud Storage path.
+  // When `destination` is set to `PATH`, you must set this field to the path
+  // where you want logs to be saved. This path can point to a local directory
+  // on the VM or (if congifured) a directory under the mount path of any
+  // Cloud Storage bucket, network file system (NFS), or writable persistent
+  // disk that is mounted to the job. For example, if the job has a bucket with
+  // `mountPath` set to `/mnt/disks/my-bucket`, you can write logs to the
+  // root directory of the `remotePath` of that bucket by setting this field to
+  // `/mnt/disks/my-bucket/`.
   string logs_path = 2;
 
-  // Optional. Additional settings for Cloud Logging. It will only take effect
-  // when the destination of `LogsPolicy` is set to `CLOUD_LOGGING`.
+  // Optional. When `destination` is set to `CLOUD_LOGGING`, you can optionally
+  // set this field to configure additional settings for Cloud Logging.
   CloudLoggingOption cloud_logging_option = 3
       [(google.api.field_behavior) = OPTIONAL];
 }
@@ -429,7 +437,8 @@ message AllocationPolicy {
       // Named the field as 'instance_template' instead of 'template' to avoid
       // C++ keyword conflict.
       //
-      // Batch only supports global instance templates.
+      // Batch only supports global instance templates from the same project as
+      // the job.
       // You can specify the global instance template as a full or partial URL.
       string instance_template = 2;
     }

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

@@ -113,13 +113,15 @@ message Job {
   repeated JobNotification notifications = 14;
 }
 
-// LogsPolicy describes how outputs from a Job's Tasks (stdout/stderr) will be
-// preserved.
+// LogsPolicy describes if and how a job's logs are preserved. Logs include
+// information that is automatically written by the Batch service agent and any
+// information that you configured the job's runnables to write to the `stdout`
+// or `stderr` streams.
 message LogsPolicy {
   // `CloudLoggingOption` contains additional settings for Cloud Logging logs
   // generated by Batch job.
   message CloudLoggingOption {
-    // Optional. Set this flag to true to change the [monitored resource
+    // Optional. Set this field to `true` to change the [monitored resource
     // type](https://cloud.google.com/monitoring/api/resources) for
     // Cloud Logging logs generated by this Batch job from
     // the
@@ -133,26 +135,32 @@ message LogsPolicy {
 
   // The destination (if any) for logs.
   enum Destination {
-    // Logs are not preserved.
+    // (Default) Logs are not preserved.
     DESTINATION_UNSPECIFIED = 0;
 
-    // Logs are streamed to Cloud Logging.
+    // Logs are streamed to Cloud Logging. Optionally, you can configure
+    // additional settings in the `cloudLoggingOption` field.
     CLOUD_LOGGING = 1;
 
-    // Logs are saved to a file path.
+    // Logs are saved to the file path specified in the `logsPath` field.
     PATH = 2;
   }
 
-  // Where logs should be saved.
+  // If and where logs should be saved.
   Destination destination = 1;
 
-  // The path to which logs are saved when the destination = PATH. This can be a
-  // local file path on the VM, or under the mount point of a Persistent Disk or
-  // Filestore, or a Cloud Storage path.
+  // When `destination` is set to `PATH`, you must set this field to the path
+  // where you want logs to be saved. This path can point to a local directory
+  // on the VM or (if congifured) a directory under the mount path of any
+  // Cloud Storage bucket, network file system (NFS), or writable persistent
+  // disk that is mounted to the job. For example, if the job has a bucket with
+  // `mountPath` set to `/mnt/disks/my-bucket`, you can write logs to the
+  // root directory of the `remotePath` of that bucket by setting this field to
+  // `/mnt/disks/my-bucket/`.
   string logs_path = 2;
 
-  // Optional. Additional settings for Cloud Logging. It will only take effect
-  // when the destination of `LogsPolicy` is set to `CLOUD_LOGGING`.
+  // Optional. When `destination` is set to `CLOUD_LOGGING`, you can optionally
+  // set this field to configure additional settings for Cloud Logging.
   CloudLoggingOption cloud_logging_option = 3
       [(google.api.field_behavior) = OPTIONAL];
 }
@@ -504,7 +512,8 @@ message AllocationPolicy {
       // Named the field as 'instance_template' instead of 'template' to avoid
       // C++ keyword conflict.
       //
-      // Batch only supports global instance templates.
+      // Batch only supports global instance templates from the same project as
+      // the job.
       // You can specify the global instance template as a full or partial URL.
       string instance_template = 2;
     }