From fa1f59af6600b6ad969c959b492969ef9903a888 Mon Sep 17 00:00:00 2001 From: "gcf-owl-bot[bot]" <78513119+gcf-owl-bot[bot]@users.noreply.github.com> Date: Wed, 14 Aug 2024 17:25:39 -0700 Subject: [PATCH] docs: Batch CentOS images and HPC CentOS images are EOS (#7597) docs: Clarify required fields for Runnable.Container docs: Clarify required oneof fields for Runnable.Script docs: Clarify TaskSpec requires one or more runnables PiperOrigin-RevId: 662559250 Source-Link: https://github.com/googleapis/googleapis/commit/906736032699b7e943ef2155edbda05470723647 Source-Link: https://github.com/googleapis/googleapis-gen/commit/e7287e10ac26decb4c72aace4adc27685d3ecd95 Copy-Tag: eyJwIjoiQmF0Y2gvLk93bEJvdC55YW1sIiwiaCI6ImU3Mjg3ZTEwYWMyNmRlY2I0YzcyYWFjZTRhZGMyNzY4NWQzZWNkOTUifQ== --- Batch/src/V1/AllocationPolicy/Disk.php | 6 -- Batch/src/V1/Runnable/Barrier.php | 3 +- Batch/src/V1/Runnable/Container.php | 120 ++++++++++++++----------- Batch/src/V1/Runnable/Script.php | 90 ++++++++++--------- Batch/src/V1/TaskSpec.php | 40 +++++---- 5 files changed, 142 insertions(+), 117 deletions(-) diff --git a/Batch/src/V1/AllocationPolicy/Disk.php b/Batch/src/V1/AllocationPolicy/Disk.php index 42bc722299f..88f8afbc3d7 100644 --- a/Batch/src/V1/AllocationPolicy/Disk.php +++ b/Batch/src/V1/AllocationPolicy/Disk.php @@ -79,9 +79,7 @@ class Disk extends \Google\Protobuf\Internal\Message * You can also use Batch customized image in short names. * The following image values are supported for a boot disk: * * `batch-debian`: use Batch Debian images. - * * `batch-centos`: use Batch CentOS images. * * `batch-cos`: use Batch Container-Optimized images. - * * `batch-hpc-centos`: use Batch HPC CentOS images. * * `batch-hpc-rocky`: use Batch HPC Rocky Linux images. * @type string $snapshot * Name of a snapshot used as the data source. @@ -134,9 +132,7 @@ public function __construct($data = NULL) { * You can also use Batch customized image in short names. * The following image values are supported for a boot disk: * * `batch-debian`: use Batch Debian images. - * * `batch-centos`: use Batch CentOS images. * * `batch-cos`: use Batch Container-Optimized images. - * * `batch-hpc-centos`: use Batch HPC CentOS images. * * `batch-hpc-rocky`: use Batch HPC Rocky Linux images. * * Generated from protobuf field string image = 4; @@ -162,9 +158,7 @@ public function hasImage() * You can also use Batch customized image in short names. * The following image values are supported for a boot disk: * * `batch-debian`: use Batch Debian images. - * * `batch-centos`: use Batch CentOS images. * * `batch-cos`: use Batch Container-Optimized images. - * * `batch-hpc-centos`: use Batch HPC CentOS images. * * `batch-hpc-rocky`: use Batch HPC Rocky Linux images. * * Generated from protobuf field string image = 4; diff --git a/Batch/src/V1/Runnable/Barrier.php b/Batch/src/V1/Runnable/Barrier.php index 16b142b5743..2ec1652a039 100644 --- a/Batch/src/V1/Runnable/Barrier.php +++ b/Batch/src/V1/Runnable/Barrier.php @@ -9,7 +9,8 @@ use Google\Protobuf\Internal\GPBUtil; /** - * Barrier runnable blocks until all tasks in a taskgroup reach it. + * A barrier runnable automatically blocks the execution of subsequent + * runnables until all the tasks in the task group reach the barrier. * * Generated from protobuf message google.cloud.batch.v1.Runnable.Barrier */ diff --git a/Batch/src/V1/Runnable/Container.php b/Batch/src/V1/Runnable/Container.php index 470fca278e7..76f1c83e3e8 100644 --- a/Batch/src/V1/Runnable/Container.php +++ b/Batch/src/V1/Runnable/Container.php @@ -16,43 +16,47 @@ class Container extends \Google\Protobuf\Internal\Message { /** - * The URI to pull the container image from. + * Required. The URI to pull the container image from. * * Generated from protobuf field string image_uri = 1; */ protected $image_uri = ''; /** - * Overrides the `CMD` specified in the container. If there is an ENTRYPOINT - * (either in the container image or with the entrypoint field below) then - * commands are appended as arguments to the ENTRYPOINT. + * Required for some container images. Overrides the `CMD` specified in the + * container. If there is an `ENTRYPOINT` (either in the container image or + * with the `entrypoint` field below) then these commands are appended as + * arguments to the `ENTRYPOINT`. * * Generated from protobuf field repeated string commands = 2; */ private $commands; /** - * Overrides the `ENTRYPOINT` specified in the container. + * Required for some container images. Overrides the `ENTRYPOINT` specified + * in the container. * * Generated from protobuf field string entrypoint = 3; */ protected $entrypoint = ''; /** * Volumes to mount (bind mount) from the host machine files or directories - * into the container, formatted to match docker run's --volume option, - * e.g. /foo:/bar, or /foo:/bar:ro + * into the container, formatted to match `--volume` option for the + * `docker run` command—for example, `/foo:/bar` or `/foo:/bar:ro`. * If the `TaskSpec.Volumes` field is specified but this field is not, Batch * will mount each volume from the host machine to the container with the * same mount path by default. In this case, the default mount option for - * containers will be read-only (ro) for existing persistent disks and - * read-write (rw) for other volume types, regardless of the original mount - * options specified in `TaskSpec.Volumes`. If you need different mount - * settings, you can explicitly configure them in this field. + * containers will be read-only (`ro`) for existing persistent disks and + * read-write (`rw`) for other volume types, regardless of the original + * mount options specified in `TaskSpec.Volumes`. If you need different + * mount settings, you can explicitly configure them in this field. * * Generated from protobuf field repeated string volumes = 7; */ private $volumes; /** - * Arbitrary additional options to include in the "docker run" command when - * running this container, e.g. "--network host". + * Required for some container images. Arbitrary additional options to + * include in the `docker run` command when running this container—for + * example, `--network host`. For the `--volume` option, use the `volumes` + * field for the container. * * Generated from protobuf field string options = 8; */ @@ -128,27 +132,31 @@ class Container extends \Google\Protobuf\Internal\Message * Optional. Data for populating the Message object. * * @type string $image_uri - * The URI to pull the container image from. + * Required. The URI to pull the container image from. * @type array|\Google\Protobuf\Internal\RepeatedField $commands - * Overrides the `CMD` specified in the container. If there is an ENTRYPOINT - * (either in the container image or with the entrypoint field below) then - * commands are appended as arguments to the ENTRYPOINT. + * Required for some container images. Overrides the `CMD` specified in the + * container. If there is an `ENTRYPOINT` (either in the container image or + * with the `entrypoint` field below) then these commands are appended as + * arguments to the `ENTRYPOINT`. * @type string $entrypoint - * Overrides the `ENTRYPOINT` specified in the container. + * Required for some container images. Overrides the `ENTRYPOINT` specified + * in the container. * @type array|\Google\Protobuf\Internal\RepeatedField $volumes * Volumes to mount (bind mount) from the host machine files or directories - * into the container, formatted to match docker run's --volume option, - * e.g. /foo:/bar, or /foo:/bar:ro + * into the container, formatted to match `--volume` option for the + * `docker run` command—for example, `/foo:/bar` or `/foo:/bar:ro`. * If the `TaskSpec.Volumes` field is specified but this field is not, Batch * will mount each volume from the host machine to the container with the * same mount path by default. In this case, the default mount option for - * containers will be read-only (ro) for existing persistent disks and - * read-write (rw) for other volume types, regardless of the original mount - * options specified in `TaskSpec.Volumes`. If you need different mount - * settings, you can explicitly configure them in this field. + * containers will be read-only (`ro`) for existing persistent disks and + * read-write (`rw`) for other volume types, regardless of the original + * mount options specified in `TaskSpec.Volumes`. If you need different + * mount settings, you can explicitly configure them in this field. * @type string $options - * Arbitrary additional options to include in the "docker run" command when - * running this container, e.g. "--network host". + * Required for some container images. Arbitrary additional options to + * include in the `docker run` command when running this container—for + * example, `--network host`. For the `--volume` option, use the `volumes` + * field for the container. * @type bool $block_external_network * If set to true, external network access to and from container will be * blocked, containers that are with block_external_network as true can @@ -204,7 +212,7 @@ public function __construct($data = NULL) { } /** - * The URI to pull the container image from. + * Required. The URI to pull the container image from. * * Generated from protobuf field string image_uri = 1; * @return string @@ -215,7 +223,7 @@ public function getImageUri() } /** - * The URI to pull the container image from. + * Required. The URI to pull the container image from. * * Generated from protobuf field string image_uri = 1; * @param string $var @@ -230,9 +238,10 @@ public function setImageUri($var) } /** - * Overrides the `CMD` specified in the container. If there is an ENTRYPOINT - * (either in the container image or with the entrypoint field below) then - * commands are appended as arguments to the ENTRYPOINT. + * Required for some container images. Overrides the `CMD` specified in the + * container. If there is an `ENTRYPOINT` (either in the container image or + * with the `entrypoint` field below) then these commands are appended as + * arguments to the `ENTRYPOINT`. * * Generated from protobuf field repeated string commands = 2; * @return \Google\Protobuf\Internal\RepeatedField @@ -243,9 +252,10 @@ public function getCommands() } /** - * Overrides the `CMD` specified in the container. If there is an ENTRYPOINT - * (either in the container image or with the entrypoint field below) then - * commands are appended as arguments to the ENTRYPOINT. + * Required for some container images. Overrides the `CMD` specified in the + * container. If there is an `ENTRYPOINT` (either in the container image or + * with the `entrypoint` field below) then these commands are appended as + * arguments to the `ENTRYPOINT`. * * Generated from protobuf field repeated string commands = 2; * @param array|\Google\Protobuf\Internal\RepeatedField $var @@ -260,7 +270,8 @@ public function setCommands($var) } /** - * Overrides the `ENTRYPOINT` specified in the container. + * Required for some container images. Overrides the `ENTRYPOINT` specified + * in the container. * * Generated from protobuf field string entrypoint = 3; * @return string @@ -271,7 +282,8 @@ public function getEntrypoint() } /** - * Overrides the `ENTRYPOINT` specified in the container. + * Required for some container images. Overrides the `ENTRYPOINT` specified + * in the container. * * Generated from protobuf field string entrypoint = 3; * @param string $var @@ -287,15 +299,15 @@ public function setEntrypoint($var) /** * Volumes to mount (bind mount) from the host machine files or directories - * into the container, formatted to match docker run's --volume option, - * e.g. /foo:/bar, or /foo:/bar:ro + * into the container, formatted to match `--volume` option for the + * `docker run` command—for example, `/foo:/bar` or `/foo:/bar:ro`. * If the `TaskSpec.Volumes` field is specified but this field is not, Batch * will mount each volume from the host machine to the container with the * same mount path by default. In this case, the default mount option for - * containers will be read-only (ro) for existing persistent disks and - * read-write (rw) for other volume types, regardless of the original mount - * options specified in `TaskSpec.Volumes`. If you need different mount - * settings, you can explicitly configure them in this field. + * containers will be read-only (`ro`) for existing persistent disks and + * read-write (`rw`) for other volume types, regardless of the original + * mount options specified in `TaskSpec.Volumes`. If you need different + * mount settings, you can explicitly configure them in this field. * * Generated from protobuf field repeated string volumes = 7; * @return \Google\Protobuf\Internal\RepeatedField @@ -307,15 +319,15 @@ public function getVolumes() /** * Volumes to mount (bind mount) from the host machine files or directories - * into the container, formatted to match docker run's --volume option, - * e.g. /foo:/bar, or /foo:/bar:ro + * into the container, formatted to match `--volume` option for the + * `docker run` command—for example, `/foo:/bar` or `/foo:/bar:ro`. * If the `TaskSpec.Volumes` field is specified but this field is not, Batch * will mount each volume from the host machine to the container with the * same mount path by default. In this case, the default mount option for - * containers will be read-only (ro) for existing persistent disks and - * read-write (rw) for other volume types, regardless of the original mount - * options specified in `TaskSpec.Volumes`. If you need different mount - * settings, you can explicitly configure them in this field. + * containers will be read-only (`ro`) for existing persistent disks and + * read-write (`rw`) for other volume types, regardless of the original + * mount options specified in `TaskSpec.Volumes`. If you need different + * mount settings, you can explicitly configure them in this field. * * Generated from protobuf field repeated string volumes = 7; * @param array|\Google\Protobuf\Internal\RepeatedField $var @@ -330,8 +342,10 @@ public function setVolumes($var) } /** - * Arbitrary additional options to include in the "docker run" command when - * running this container, e.g. "--network host". + * Required for some container images. Arbitrary additional options to + * include in the `docker run` command when running this container—for + * example, `--network host`. For the `--volume` option, use the `volumes` + * field for the container. * * Generated from protobuf field string options = 8; * @return string @@ -342,8 +356,10 @@ public function getOptions() } /** - * Arbitrary additional options to include in the "docker run" command when - * running this container, e.g. "--network host". + * Required for some container images. Arbitrary additional options to + * include in the `docker run` command when running this container—for + * example, `--network host`. For the `--volume` option, use the `volumes` + * field for the container. * * Generated from protobuf field string options = 8; * @param string $var diff --git a/Batch/src/V1/Runnable/Script.php b/Batch/src/V1/Runnable/Script.php index f010fdde7c2..235d362d63f 100644 --- a/Batch/src/V1/Runnable/Script.php +++ b/Batch/src/V1/Runnable/Script.php @@ -24,21 +24,23 @@ class Script extends \Google\Protobuf\Internal\Message * Optional. Data for populating the Message object. * * @type string $path - * Script file path on the host VM. - * To specify an interpreter, please add a `#!`(also known as - * [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix))) as the - * 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 executed by - * `/bin/sh`. + * The path to a script file that is accessible from the host VM(s). + * Unless the script file supports the default `#!/bin/sh` shell + * interpreter, you must specify an interpreter by including a + * [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix) as the + * first line of the file. For example, to execute the script using bash, + * include `#!/bin/bash` as the first line of the file. Alternatively, + * to execute the script using Python3, include `#!/usr/bin/env python3` + * as the first line of the file. * @type string $text - * Shell script text. - * To specify an interpreter, please add a `#!\n` at the - * 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 executed by `/bin/sh`. + * The text for a script. + * Unless the script text supports the default `#!/bin/sh` shell + * interpreter, you must specify an interpreter by including a + * [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix) at the + * beginning of the text. For example, to execute the script using bash, + * include `#!/bin/bash\n` at the beginning of the text. Alternatively, + * to execute the script using Python3, include `#!/usr/bin/env python3\n` + * at the beginning of the text. * } */ public function __construct($data = NULL) { @@ -47,14 +49,14 @@ public function __construct($data = NULL) { } /** - * Script file path on the host VM. - * To specify an interpreter, please add a `#!`(also known as - * [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix))) as the - * 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 executed by - * `/bin/sh`. + * The path to a script file that is accessible from the host VM(s). + * Unless the script file supports the default `#!/bin/sh` shell + * interpreter, you must specify an interpreter by including a + * [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix) as the + * first line of the file. For example, to execute the script using bash, + * include `#!/bin/bash` as the first line of the file. Alternatively, + * to execute the script using Python3, include `#!/usr/bin/env python3` + * as the first line of the file. * * Generated from protobuf field string path = 1; * @return string @@ -70,14 +72,14 @@ public function hasPath() } /** - * Script file path on the host VM. - * To specify an interpreter, please add a `#!`(also known as - * [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix))) as the - * 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 executed by - * `/bin/sh`. + * The path to a script file that is accessible from the host VM(s). + * Unless the script file supports the default `#!/bin/sh` shell + * interpreter, you must specify an interpreter by including a + * [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix) as the + * first line of the file. For example, to execute the script using bash, + * include `#!/bin/bash` as the first line of the file. Alternatively, + * to execute the script using Python3, include `#!/usr/bin/env python3` + * as the first line of the file. * * Generated from protobuf field string path = 1; * @param string $var @@ -92,12 +94,14 @@ public function setPath($var) } /** - * Shell script text. - * To specify an interpreter, please add a `#!\n` at the - * 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 executed by `/bin/sh`. + * The text for a script. + * Unless the script text supports the default `#!/bin/sh` shell + * interpreter, you must specify an interpreter by including a + * [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix) at the + * beginning of the text. For example, to execute the script using bash, + * include `#!/bin/bash\n` at the beginning of the text. Alternatively, + * to execute the script using Python3, include `#!/usr/bin/env python3\n` + * at the beginning of the text. * * Generated from protobuf field string text = 2; * @return string @@ -113,12 +117,14 @@ public function hasText() } /** - * Shell script text. - * To specify an interpreter, please add a `#!\n` at the - * 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 executed by `/bin/sh`. + * The text for a script. + * Unless the script text supports the default `#!/bin/sh` shell + * interpreter, you must specify an interpreter by including a + * [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix) at the + * beginning of the text. For example, to execute the script using bash, + * include `#!/bin/bash\n` at the beginning of the text. Alternatively, + * to execute the script using Python3, include `#!/usr/bin/env python3\n` + * at the beginning of the text. * * Generated from protobuf field string text = 2; * @param string $var diff --git a/Batch/src/V1/TaskSpec.php b/Batch/src/V1/TaskSpec.php index ff38c4b463b..a76f190671f 100644 --- a/Batch/src/V1/TaskSpec.php +++ b/Batch/src/V1/TaskSpec.php @@ -16,10 +16,12 @@ class TaskSpec extends \Google\Protobuf\Internal\Message { /** - * The sequence of scripts or containers to run for this Task. Each Task using - * this TaskSpec executes its list of runnables in order. The Task succeeds if - * all of its runnables either exit with a zero status or any that exit with a - * non-zero status have the ignore_exit_status flag. + * Required. The sequence of one or more runnables (executable scripts, + * executable containers, and/or barriers) for each task in this task group to + * run. Each task runs this list of runnables in order. For a task to succeed, + * all of its script and container runnables each must either exit with a zero + * status or enable the `ignore_exit_status` subfield and exit with any + * status. * Background runnables are killed automatically (if they have not already * exited) a short time after all foreground runnables have completed. Even * though this is likely to result in a non-zero exit status for the @@ -97,10 +99,12 @@ class TaskSpec extends \Google\Protobuf\Internal\Message * Optional. Data for populating the Message object. * * @type array<\Google\Cloud\Batch\V1\Runnable>|\Google\Protobuf\Internal\RepeatedField $runnables - * The sequence of scripts or containers to run for this Task. Each Task using - * this TaskSpec executes its list of runnables in order. The Task succeeds if - * all of its runnables either exit with a zero status or any that exit with a - * non-zero status have the ignore_exit_status flag. + * Required. The sequence of one or more runnables (executable scripts, + * executable containers, and/or barriers) for each task in this task group to + * run. Each task runs this list of runnables in order. For a task to succeed, + * all of its script and container runnables each must either exit with a zero + * status or enable the `ignore_exit_status` subfield and exit with any + * status. * Background runnables are killed automatically (if they have not already * exited) a short time after all foreground runnables have completed. Even * though this is likely to result in a non-zero exit status for the @@ -145,10 +149,12 @@ public function __construct($data = NULL) { } /** - * The sequence of scripts or containers to run for this Task. Each Task using - * this TaskSpec executes its list of runnables in order. The Task succeeds if - * all of its runnables either exit with a zero status or any that exit with a - * non-zero status have the ignore_exit_status flag. + * Required. The sequence of one or more runnables (executable scripts, + * executable containers, and/or barriers) for each task in this task group to + * run. Each task runs this list of runnables in order. For a task to succeed, + * all of its script and container runnables each must either exit with a zero + * status or enable the `ignore_exit_status` subfield and exit with any + * status. * Background runnables are killed automatically (if they have not already * exited) a short time after all foreground runnables have completed. Even * though this is likely to result in a non-zero exit status for the @@ -164,10 +170,12 @@ public function getRunnables() } /** - * The sequence of scripts or containers to run for this Task. Each Task using - * this TaskSpec executes its list of runnables in order. The Task succeeds if - * all of its runnables either exit with a zero status or any that exit with a - * non-zero status have the ignore_exit_status flag. + * Required. The sequence of one or more runnables (executable scripts, + * executable containers, and/or barriers) for each task in this task group to + * run. Each task runs this list of runnables in order. For a task to succeed, + * all of its script and container runnables each must either exit with a zero + * status or enable the `ignore_exit_status` subfield and exit with any + * status. * Background runnables are killed automatically (if they have not already * exited) a short time after all foreground runnables have completed. Even * though this is likely to result in a non-zero exit status for the