Skip to content

Commit e5c46f5

Browse files
gcf-owl-bot[bot]gcf-owl-bot[bot]
authored
docs(batch-v1): Clarify several type descriptions (googleapis#22824)
1 parent 6d5ae02 commit e5c46f5

3 files changed

Lines changed: 72 additions & 27 deletions

File tree

‎google-cloud-batch-v1/proto_docs/google/api/field_behavior.rb‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,20 @@ module FieldBehavior
6666
# a non-empty value will be returned. The user will not be aware of what
6767
# non-empty value to expect.
6868
NON_EMPTY_DEFAULT = 7
69+
70+
# Denotes that the field in a resource (a message annotated with
71+
# google.api.resource) is used in the resource name to uniquely identify the
72+
# resource. For AIP-compliant APIs, this should only be applied to the
73+
# `name` field on the resource.
74+
#
75+
# This behavior should not be applied to references to other resources within
76+
# the message.
77+
#
78+
# The identifier field of resources often have different field behavior
79+
# depending on the request it is embedded in (e.g. for Create methods name
80+
# is optional and unused, while for Update methods it is required). Instead
81+
# of method-specific annotations, only `IDENTIFIER` is required.
82+
IDENTIFIER = 8
6983
end
7084
end
7185
end

‎google-cloud-batch-v1/proto_docs/google/cloud/batch/v1/job.rb‎

Lines changed: 19 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -314,17 +314,14 @@ class LocationPolicy
314314
# https://cloud.google.com/compute/docs/disks#localssds.
315315
# @!attribute [rw] image
316316
# @return [::String]
317-
# Name of an image used as the data source.
317+
# URL for a VM image to use as the data source for this disk.
318318
# For example, the following are all valid URLs:
319319
#
320320
# * Specify the image by its family name:
321-
# <pre><code>projects/<var
322-
# class="apiparam">project</var>/global/images/family/<var
323-
# class="apiparam">image_family</var></code></pre>
321+
# projects/\\{project}/global/images/family/\\{image_family}
324322
# * Specify the image version:
325-
# <pre>projects/<var
326-
# class="apiparam">project</var>/global/images/<var
327-
# class="apiparam">image_version</var></code></pre>
323+
# projects/\\{project}/global/images/\\{image_version}
324+
#
328325
# You can also use Batch customized image in short names.
329326
# The following image values are supported for a boot disk:
330327
#
@@ -432,12 +429,18 @@ class Accelerator
432429
# @return [::Array<::Google::Cloud::Batch::V1::AllocationPolicy::AttachedDisk>]
433430
# Non-boot disks to be attached for each VM created by this InstancePolicy.
434431
# New disks will be deleted when the VM is deleted.
432+
# A non-boot disk is a disk that can be of a device with a
433+
# file system or a raw storage drive that is not ready for data
434+
# storage and accessing.
435435
class InstancePolicy
436436
include ::Google::Protobuf::MessageExts
437437
extend ::Google::Protobuf::MessageExts::ClassMethods
438438
end
439439

440-
# Either an InstancePolicy or an instance template.
440+
# InstancePolicyOrTemplate lets you define the type of resources to use for
441+
# this job either with an InstancePolicy or an instance template.
442+
# If undefined, Batch picks the type of VM to use and doesn't include
443+
# optional VM resources such as GPUs and extra disks.
441444
# @!attribute [rw] policy
442445
# @return [::Google::Cloud::Batch::V1::AllocationPolicy::InstancePolicy]
443446
# InstancePolicy.
@@ -470,30 +473,20 @@ class InstancePolicyOrTemplate
470473
# You can specify the network as a full or partial URL.
471474
#
472475
# For example, the following are all valid URLs:
473-
# <pre><code>https://www.googleapis.com/compute/v1/projects/<var
474-
# class="apiparam">project</var>/global/networks/<var
475-
# class="apiparam">network</var></code></pre>
476-
# <pre><code>projects/<var
477-
# class="apiparam">project</var>/global/networks/<var
478-
# class="apiparam">network</var></code></pre>
479-
# <pre><code>global/networks/<var
480-
# class="apiparam">network</var></code></pre>
476+
#
477+
# * https://www.googleapis.com/compute/v1/projects/\\{project}/global/networks/\\{network}
478+
# * projects/\\{project}/global/networks/\\{network}
479+
# * global/networks/\\{network}
481480
# @!attribute [rw] subnetwork
482481
# @return [::String]
483482
# The URL of an existing subnetwork resource in the network.
484483
# You can specify the subnetwork as a full or partial URL.
485484
#
486485
# For example, the following are all valid URLs:
487-
# <pre><code>https://www.googleapis.com/compute/v1/projects/<var
488-
# class="apiparam">project</var>/regions/<var
489-
# class="apiparam">region</var>/subnetworks/<var
490-
# class="apiparam">subnetwork</var></code></pre>
491-
# <pre><code>projects/<var class="apiparam">project</var>/regions/<var
492-
# class="apiparam">region</var>/subnetworks/<var
493-
# class="apiparam">subnetwork</var></code></pre>
494-
# <pre><code>regions/<var
495-
# class="apiparam">region</var>/subnetworks/<var
496-
# class="apiparam">subnetwork</var></code></pre>
486+
#
487+
# * https://www.googleapis.com/compute/v1/projects/\\{project}/regions/\\{region}/subnetworks/\\{subnetwork}
488+
# * projects/\\{project}/regions/\\{region}/subnetworks/\\{subnetwork}
489+
# * regions/\\{region}/subnetworks/\\{subnetwork}
497490
# @!attribute [rw] no_external_ip_address
498491
# @return [::Boolean]
499492
# Default is false (with an external IP address). Required if

‎google-cloud-batch-v1/proto_docs/google/cloud/batch/v1/task.rb‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,51 @@ module Google
2121
module Cloud
2222
module Batch
2323
module V1
24-
# Compute resource requirements
24+
# Compute resource requirements.
25+
#
26+
# ComputeResource defines the amount of resources required for each task.
27+
# Make sure your tasks have enough resources to successfully run.
28+
# If you also define the types of resources for a job to use with the
29+
# [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicyortemplate)
30+
# field, make sure both fields are compatible with each other.
2531
# @!attribute [rw] cpu_milli
2632
# @return [::Integer]
2733
# The milliCPU count.
34+
#
35+
# `cpuMilli` defines the amount of CPU resources per task in milliCPU units.
36+
# For example, `1000` corresponds to 1 vCPU per task. If undefined, the
37+
# default value is `2000`.
38+
#
39+
# If you also define the VM's machine type using the `machineType` in
40+
# [InstancePolicy](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicy)
41+
# field or inside the `instanceTemplate` in the
42+
# [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicyortemplate)
43+
# field, make sure the CPU resources for both fields are compatible with each
44+
# other and with how many tasks you want to allow to run on the same VM at
45+
# the same time.
46+
#
47+
# For example, if you specify the `n2-standard-2` machine type, which has 2
48+
# vCPUs each, you are recommended to set `cpuMilli` no more than `2000`, or
49+
# you are recommended to run two tasks on the same VM if you set `cpuMilli`
50+
# to `1000` or less.
2851
# @!attribute [rw] memory_mib
2952
# @return [::Integer]
3053
# Memory in MiB.
54+
#
55+
# `memoryMib` defines the amount of memory per task in MiB units.
56+
# If undefined, the default value is `2000`.
57+
# If you also define the VM's machine type using the `machineType` in
58+
# [InstancePolicy](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicy)
59+
# field or inside the `instanceTemplate` in the
60+
# [InstancePolicyOrTemplate](https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#instancepolicyortemplate)
61+
# field, make sure the memory resources for both fields are compatible with
62+
# each other and with how many tasks you want to allow to run on the same VM
63+
# at the same time.
64+
#
65+
# For example, if you specify the `n2-standard-2` machine type, which has 8
66+
# GiB each, you are recommended to set `memoryMib` to no more than `8192`,
67+
# or you are recommended to run two tasks on the same VM if you set
68+
# `memoryMib` to `4096` or less.
3169
# @!attribute [rw] boot_disk_mib
3270
# @return [::Integer]
3371
# Extra boot disk size in MiB for each task.

0 commit comments

Comments
 (0)