docs: [google-cloud-batch] add caution messages for container runnable username and password fields (#12330)

gcf-owl-bot[bot] · ohmayr · web-flow · commit 9379366e9173 · 2024-02-21T18:20:20.000-05:00
BEGIN_COMMIT_OVERRIDE docs: refine proto comment for run_as_non_root docs: add caution messages for container runnable username and password fields END_COMMIT_OVERRIDE - [ ] Regenerate this pull request now. --- docs: refine proto comment for run_as_non_root PiperOrigin-RevId: 608664745 Source-Link: googleapis/googleapis@254e61a Source-Link: googleapis/googleapis-gen@4526911 Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLWJhdGNoLy5Pd2xCb3QueWFtbCIsImgiOiI0NTI2OTExYzdkZDU4NjJkMTgzNzI1NTRkZGQ4MjBmOTQ4MjdmMzNhIn0= BEGIN_NESTED_COMMIT docs: [google-cloud-batch] refine proto comment for run_as_non_root docs: add caution messages for container runnable username and password fields PiperOrigin-RevId: 608240389 Source-Link: googleapis/googleapis@6f599f0 Source-Link: googleapis/googleapis-gen@6af0d38 Copy-Tag: eyJwIjoicGFja2FnZXMvZ29vZ2xlLWNsb3VkLWJhdGNoLy5Pd2xCb3QueWFtbCIsImgiOiI2YWYwZDM4ZDk1M2U3YTVmOTQyN2Q2NTBlYmNkMzcyNmZlMjg2ZGNlIn0= END_NESTED_COMMIT --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: ohmayr <omairnaveed@ymail.com>
diff --git a/packages/google-cloud-batch/google/cloud/batch_v1/types/job.py b/packages/google-cloud-batch/google/cloud/batch_v1/types/job.py
@@ -981,19 +981,18 @@ class TaskGroup(proto.Message):
             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.
+            false. The host file supports up to 1000 VMs.
         permissive_ssh (bool):
             When true, Batch will configure SSH to allow
             passwordless login between VMs running the Batch
             tasks in the same TaskGroup.
         run_as_non_root (bool):
-            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>`__.
     """
 
     class SchedulingPolicy(proto.Enum):
diff --git a/packages/google-cloud-batch/google/cloud/batch_v1/types/task.py b/packages/google-cloud-batch/google/cloud/batch_v1/types/task.py
@@ -318,13 +318,43 @@ class Container(proto.Message):
                 each other, network cannot be specified in the
                 ``container.options`` field.
             username (str):
-                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>`__.
             password (str):
-                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>`__.
             enable_image_streaming (bool):
                 Optional. If set to true, this container runnable uses Image
                 streaming.
@@ -406,7 +436,7 @@ class Script(proto.Message):
                 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
+                file.) Otherwise, the file will by default be executed by
                 ``/bin/sh``.
 
                 This field is a member of `oneof`_ ``command``.
@@ -418,7 +448,7 @@ class Script(proto.Message):
                 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``.
+                the script will by default be executed by ``/bin/sh``.
 
                 This field is a member of `oneof`_ ``command``.
         """
diff --git a/packages/google-cloud-batch/google/cloud/batch_v1alpha/types/job.py b/packages/google-cloud-batch/google/cloud/batch_v1alpha/types/job.py
@@ -1136,19 +1136,18 @@ class TaskGroup(proto.Message):
             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.
+            false. The host file supports up to 1000 VMs.
         permissive_ssh (bool):
             When true, Batch will configure SSH to allow
             passwordless login between VMs running the Batch
             tasks in the same TaskGroup.
         run_as_non_root (bool):
-            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>`__.
     """
 
     class SchedulingPolicy(proto.Enum):
diff --git a/packages/google-cloud-batch/google/cloud/batch_v1alpha/types/task.py b/packages/google-cloud-batch/google/cloud/batch_v1alpha/types/task.py
@@ -358,13 +358,43 @@ class Container(proto.Message):
                 each other, network cannot be specified in the
                 ``container.options`` field.
             username (str):
-                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>`__.
             password (str):
-                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>`__.
             enable_image_streaming (bool):
                 Optional. If set to true, this container runnable uses Image
                 streaming.
@@ -446,7 +476,7 @@ class Script(proto.Message):
                 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
+                file.) Otherwise, the file will by default be executed by
                 ``/bin/sh``.
 
                 This field is a member of `oneof`_ ``command``.
@@ -458,7 +488,7 @@ class Script(proto.Message):
                 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``.
+                the script will by default be executed by ``/bin/sh``.
 
                 This field is a member of `oneof`_ ``command``.
         """
