docs: refine proto comment for run_as_non_root

docs: add caution messages for container runnable username and password fields PiperOrigin-RevId: 608240389
googleapis · Feb 19, 2024 · 6f599f0 · 6f599f0
1 parent 990a29a
commit 6f599f0
Show file tree

Hide file tree

Showing 4 changed files with 47 additions and 16 deletions.
diff --git a/google/cloud/batch/v1/batch_v1.yaml b/google/cloud/batch/v1/batch_v1.yaml
@@ -12,7 +12,7 @@ types:
 - name: google.cloud.batch.v1.OperationMetadata
 
 documentation:
- summary: An API to manage the running of batch jobs on Google Cloud Platform.
+ summary: An API to manage the running of batch resources on Google Cloud Platform.
  overview: '(include == google/cloud/batch/doc/overview.md ==)'
  rules:
  - selector: google.cloud.location.Locations.GetLocation

diff --git a/google/cloud/batch/v1/batch_v1_grpc_service_config.json b/google/cloud/batch/v1/batch_v1_grpc_service_config.json
@@ -3,8 +3,10 @@
  "name": [
  { "service": "google.cloud.batch.v1.BatchService", "method": "ListJobs" },
  { "service": "google.cloud.batch.v1.BatchService", "method": "ListTasks" },
+ { "service": "google.cloud.batch.v1.BatchService", "method": "ListResourceAllowances" },
  { "service": "google.cloud.batch.v1.BatchService", "method": "GetJob" },
- { "service": "google.cloud.batch.v1.BatchService", "method": "GetTask" }
+ { "service": "google.cloud.batch.v1.BatchService", "method": "GetTask" },
+ { "service": "google.cloud.batch.v1.BatchService", "method": "GetResourceAllowance" }
  ],
  "timeout": "60s",
  "retryPolicy": {
@@ -19,7 +21,10 @@
  "name": [
  { "service": "google.cloud.batch.v1.BatchService", "method": "CreateJob" },
  { "service": "google.cloud.batch.v1.BatchService", "method": "DeleteJob" },
- { "service": "google.cloud.batch.v1.BatchService", "method": "CancelJob"}
+ { "service": "google.cloud.batch.v1.BatchService", "method": "CancelJob"},
+ { "service": "google.cloud.batch.v1.BatchService", "method": "CreateResourceAllowance" },
+ { "service": "google.cloud.batch.v1.BatchService", "method": "DeleteResourceAllowance" },
+ { "service": "google.cloud.batch.v1.BatchService", "method": "UpdateResourceAllowance"}
  ],
  "timeout": "60s"
  }]

diff --git a/google/cloud/batch/v1/job.proto b/google/cloud/batch/v1/job.proto
@@ -607,17 +607,18 @@ message TaskGroup {
 
  // When true, Batch will populate a file with a list of all VMs assigned to
  // the TaskGroup and set the BATCH_HOSTS_FILE environment variable to the path
- // of that file. Defaults to false.
+ // of that file. Defaults to false. The host file supports up to 1000 VMs.
  bool require_hosts_file = 11;
 
  // When true, Batch will configure SSH to allow passwordless login between
  // VMs running the Batch tasks in the same TaskGroup.
  bool permissive_ssh = 12;
 
- // Optional. If not set or set to false, Batch will use root user to execute
- // runnables. If set to true, Batch will make sure to run the runnables using
- // non-root user. Currently, the non-root user Batch used is generated by OS
- // login. Reference: https://cloud.google.com/compute/docs/oslogin
+ // Optional. If not set or set to false, Batch uses the root user to execute
+ // runnables. If set to true, Batch runs the runnables using a non-root user.
+ // Currently, the non-root user Batch used is generated by OS Login. For more
+ // information, see [About OS
+ // Login](https://cloud.google.com/compute/docs/oslogin).
  bool run_as_non_root = 14 [(google.api.field_behavior) = OPTIONAL];
 }
 

diff --git a/google/cloud/batch/v1/task.proto b/google/cloud/batch/v1/task.proto
@@ -179,14 +179,39 @@ message Runnable {
  // `container.options` field.
  bool block_external_network = 9;
 
- // Optional username for logging in to a docker registry. If username
- // matches `projects/*/secrets/*/versions/*` then Batch will read the
- // username from the Secret Manager.
+ // Required if the container image is from a private Docker registry. The
+ // username to login to the Docker registry that contains the image.
+ //
+ // You can either specify the username directly by using plain text or
+ // specify an encrypted username by using a Secret Manager secret:
+ // `projects/*/secrets/*/versions/*`. However, using a secret is
+ // recommended for enhanced security.
+ //
+ // Caution: If you specify the username using plain text, you risk the
+ // username being exposed to any users who can view the job or its logs.
+ // To avoid this risk, specify a secret that contains the username instead.
+ //
+ // Learn more about [Secret
+ // Manager](https://cloud.google.com/secret-manager/docs/) and [using
+ // Secret Manager with
+ // Batch](https://cloud.google.com/batch/docs/create-run-job-secret-manager).
  string username = 10;
 
- // Optional password for logging in to a docker registry. If password
- // matches `projects/*/secrets/*/versions/*` then Batch will read the
- // password from the Secret Manager;
+ // Required if the container image is from a private Docker registry. The
+ // password to login to the Docker registry that contains the image.
+ //
+ // For security, it is strongly recommended to specify an
+ // encrypted password by using a Secret Manager secret:
+ // `projects/*/secrets/*/versions/*`.
+ //
+ // Warning: If you specify the password using plain text, you risk the
+ // password being exposed to any users who can view the job or its logs.
+ // To avoid this risk, specify a secret that contains the password instead.
+ //
+ // Learn more about [Secret
+ // Manager](https://cloud.google.com/secret-manager/docs/) and [using
+ // Secret Manager with
+ // Batch](https://cloud.google.com/batch/docs/create-run-job-secret-manager).
  string password = 11;
 
  // Optional. If set to true, this container runnable uses Image streaming.
@@ -219,7 +244,7 @@ message Runnable {
  // first line of the file.(For example, to execute the script using bash,
  // `#!/bin/bash` should be the first line of the file. To execute the
  // script using`Python3`, `#!/usr/bin/env python3` should be the first
- // line of the file.) Otherwise, the file will by default be excuted by
+ // line of the file.) Otherwise, the file will by default be executed by
  // `/bin/sh`.
  string path = 1;
 
@@ -229,7 +254,7 @@ message Runnable {
  // beginning of the text.(For example, to execute the script using bash,
  // `#!/bin/bash\n` should be added. To execute the script using`Python3`,
  // `#!/usr/bin/env python3\n` should be added.) Otherwise, the script will
- // by default be excuted by `/bin/sh`.
+ // by default be executed by `/bin/sh`.
  string text = 2;
  }
  }