Clarify ID (volume, snapshot, & node) requirements.

Author: saad-ali

csi.proto

@@ -350,17 +350,22 @@ message CapacityRange {
   int64 limit_bytes = 2;
 }
 
-// The information about a provisioned volume.
+// Information about a specific volume.
 message Volume {
   // The capacity of the volume in bytes. This field is OPTIONAL. If not
   // set (value of 0), it indicates that the capacity of the volume is
   // unknown (e.g., NFS share).
   // The value of this field MUST NOT be negative.
   int64 capacity_bytes = 1;
 
-  // Contains identity information for the created volume. This field is
-  // REQUIRED. The identity information will be used by the CO in
-  // subsequent calls to refer to the provisioned volume.
+  // The identifier for this volume, generated by the plugin.
+  // This field is REQUIRED.
+  // This field MUST contain enough information to uniquely identify
+  // this specific volume vs all other volumes supported by this plugin.
+  // This field SHALL be used by the CO in subsequent calls to refer to
+  // this volume.
+  // The SP is NOT responsible for global uniqueness of volume_id across
+  // multiple SPs.
   string volume_id = 2;
 
   // Opaque static properties of the volume. SP MAY use this field to
@@ -860,7 +865,7 @@ message CreateSnapshotResponse {
   Snapshot snapshot = 1;
 }
 
-// The information about a provisioned snapshot.
+// Information about a specific snapshot.
 message Snapshot {
   // This is the complete size of the snapshot in bytes. The purpose of
   // this field is to give CO guidance on how much space is needed to
@@ -871,10 +876,15 @@ message Snapshot {
   // zero means it is unspecified.
   int64 size_bytes = 1;
 
-  // Uniquely identifies a snapshot and is generated by the plugin. It
-  // will not change over time. This field is REQUIRED. The identity
-  // information will be used by the CO in subsequent calls to refer to
-  // the provisioned snapshot.
+  // The identifier for this snapshot, generated by the plugin.
+  // This field is REQUIRED.
+  // This field MUST contain enough information to uniquely identify
+  // this specific snapshot vs all other snapshots supported by this
+  // plugin.
+  // This field SHALL be used by the CO in subsequent calls to refer to
+  // this snapshot.
+  // The SP is NOT responsible for global uniqueness of snapshot_id
+  // across multiple SPs.
   string snapshot_id = 2;
 
   // Identity information for the source volume. Note that creating a
@@ -1143,9 +1153,14 @@ message NodeGetInfoRequest {
 }
 
 message NodeGetInfoResponse {
-  // The ID of the node as understood by the SP which SHALL be used by
-  // CO in subsequent calls to `ControllerPublishVolume`.
-  // This is a REQUIRED field.
+  // The identifier of the node as understood by the SP.
+  // This field is REQUIRED.
+  // This field MUST contain enough information to uniquely identify
+  // this specific node vs all other nodes supported by this plugin.
+  // This field SHALL be used by the CO in subsequent calls, including
+  // `ControllerPublishVolume`, to refer to this node.
+  // The SP is NOT responsible for global uniqueness of node_id across
+  // multiple SPs.
   string node_id = 1;
 
   // Maximum number of volumes that controller can publish to the node.