docs: Refine GPU drivers installation proto description

Google APIs · copybara-github · commit e981f84f8a33 · 2022-10-14T19:37:11.000-07:00
docs: Refine comments for deprecated proto fields
docs: Update the API comments about the device_name

PiperOrigin-RevId: 481282173
diff --git a/google/cloud/batch/v1alpha/job.proto b/google/cloud/batch/v1alpha/job.proto
@@ -92,7 +92,7 @@ message Job {
   // Output only. Job status. It is read only for users.
   JobStatus status = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Job notification.
+  // Deprecated: please use notifications instead.
   JobNotification notification = 10 [deprecated = true];
 
   // Output only. When the Job was created.
@@ -329,7 +329,9 @@ message AllocationPolicy {
     }
 
     // Device name that the guest operating system will see.
-    // If not specified, this is default to the disk name.
+    // It is used by Runnable.volumes field to mount disks. So please specify
+    // the device_name if you want Batch to help mount the disk, and it should
+    // match the device_name field in volumes.
     string device_name = 3;
   }
 
@@ -342,12 +344,14 @@ message AllocationPolicy {
     // The number of accelerators of this type.
     int64 count = 2;
 
+    // Deprecated: please use instances[0].install_gpu_drivers instead.
     bool install_gpu_drivers = 3 [deprecated = true];
   }
 
   // InstancePolicy describes an instance type and resources attached to each VM
   // created by this InstancePolicy.
   message InstancePolicy {
+    // Deprecated: please use machine_type instead.
     repeated string allowed_machine_types = 1 [deprecated = true];
 
     // The Compute Engine machine type.
@@ -383,6 +387,10 @@ message AllocationPolicy {
       string instance_template = 2;
     }
 
+    // Set this field true if users want Batch to help fetch drivers from a
+    // third party location and install them for GPUs specified in
+    // policy.accelerators or instance_template on their behalf. Default is
+    // false.
     bool install_gpu_drivers = 3;
   }
 
@@ -433,29 +441,23 @@ message AllocationPolicy {
   // Location where compute resources should be allocated for the Job.
   LocationPolicy location = 1;
 
-  // Create only instances allowed by this policy.
+  // Deprecated: please use instances[0].policy instead.
   InstancePolicy instance = 2 [deprecated = true];
 
   // Describe instances that can be created by this AllocationPolicy.
   // Only instances[0] is supported now.
   repeated InstancePolicyOrTemplate instances = 8;
 
-  // Instance templates that are used to VMs.
-  // If specified, only instance_templates[0] is used.
+  // Deprecated: please use instances[0].template instead.
   repeated string instance_templates = 3 [deprecated = true];
 
-  // Create only instances in the listed provisiong models.
-  // Default to allow all.
-  //
-  // Currently only the first model of the provisioning_models list will be
-  // considered; specifying additional models (e.g., 2nd, 3rd, etc.) is a no-op.
+  // Deprecated: please use instances[i].policy.provisioning_model instead.
   repeated ProvisioningModel provisioning_models = 4 [deprecated = true];
 
-  // Email of the service account that VMs will run as.
+  // Deprecated: please use service_account instead.
   string service_account_email = 5 [deprecated = true];
 
   // Service account that VMs will run as.
-  // Not yet implemented.
   ServiceAccount service_account = 9;
 
   // Labels applied to all VM instances and other resources
@@ -551,10 +553,12 @@ message TaskGroup {
 // Carries information about a Google Cloud service account.
 message ServiceAccount {
   // Email address of the service account. If not specified, the default
-  // Compute Engine service account for the project will be used.
+  // Compute Engine service account for the project will be used. If instance
+  // template is being used, the service account has to be specified in the
+  // instance template and it has to match the email field here.
   string email = 1;
 
   // List of scopes to be enabled for this service account on the VM, in
   // addition to the cloud-platform API scope that will be added by default.
-  repeated string scopes = 2;
+  repeated string scopes = 2 [deprecated = true];
 }
