Merge pull request #318 from saad-ali/renameVolumeAttributes

Rename volume `attributes`, `publish_info`, and `id`

Author: saad-ali

csi.proto

@@ -251,14 +251,14 @@ message VolumeContentSource {
     // This field is REQUIRED. Plugin is REQUIRED to support creating
     // volume from snapshot if it supports the capability
     // CREATE_DELETE_SNAPSHOT.
-    string id = 1;
+    string snapshot_id = 1;
   }
 
   message VolumeSource {
     // Contains identity information for the existing source volume.
     // This field is REQUIRED. Plugins reporting CLONE_VOLUME
     // capability MUST support creating a volume from another volume.
-    string id = 1;
+    string volume_id = 1;
   }
 
   oneof type {
@@ -350,28 +350,40 @@ 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.
-  string id = 2;
-
-  // Attributes reflect static properties of a volume and MUST be passed
-  // to volume validation and publishing calls.
-  // Attributes SHALL be opaque to a CO. Attributes SHALL NOT be mutable
-  // and SHALL be safe for the CO to cache. Attributes SHOULD NOT
-  // contain sensitive information. Attributes MAY NOT uniquely identify
-  // a volume. A volume uniquely identified by `id` SHALL always report
-  // the same attributes. This field is OPTIONAL and when present MUST
-  // be passed to volume validation and publishing calls.
-  map<string, string> attributes = 3;
+  // 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
+  // ensure subsequent volume validation and publishing calls have
+  // contextual information.
+  // The contents of this field SHALL be opaque to a CO.
+  // The contents of this field SHALL NOT be mutable.
+  // The contents of this field SHALL be safe for the CO to cache.
+  // The contents of this field SHOULD NOT contain sensitive
+  // information.
+  // The contents of this field SHOULD NOT be used for uniquely
+  // identifying a volume. The `volume_id` alone should be sufficient to
+  // identify the volume.
+  // A volume uniquely identified by `volume_id` SHALL always report the
+  // same volume_context.
+  // This field is OPTIONAL and when present MUST be passed to volume
+  // validation and publishing calls.
+  map<string, string> volume_context = 3;
 
   // If specified, indicates that the volume is not empty and is
   // pre-populated with data from the specified source.
@@ -609,18 +621,27 @@ message ControllerPublishVolumeRequest {
   // `Secrets Requirements` section on how to use this field.
   map<string, string> secrets = 5 [(csi_secret) = true];
 
-  // Attributes of the volume to be used on a node. This field is
-  // OPTIONAL and MUST match the attributes of the Volume identified
-  // by `volume_id`.
-  map<string, string> volume_attributes = 6;
+  // Volume context as returned by CO in CreateVolumeRequest. This field
+  // is OPTIONAL and MUST match the volume_context of the volume
+  // identified by `volume_id`.
+  map<string, string> volume_context = 6;
 }
 
 message ControllerPublishVolumeResponse {
-  // The SP specific information that will be passed to the Plugin in
-  // the subsequent `NodeStageVolume` or `NodePublishVolume` calls
-  // for the given volume.
-  // This information is opaque to the CO. This field is OPTIONAL.
-  map<string, string> publish_info = 1;
+  // Opaque static publish properties of the volume. SP MAY use this
+  // field to ensure subsequent `NodeStageVolume` or `NodePublishVolume`
+  // calls calls have contextual information.
+  // The contents of this field SHALL be opaque to a CO.
+  // The contents of this field SHALL NOT be mutable.
+  // The contents of this field SHALL be safe for the CO to cache.
+  // The contents of this field SHOULD NOT contain sensitive
+  // information.
+  // The contents of this field SHOULD NOT be used for uniquely
+  // identifying a volume. The `id` alone should be sufficient to
+  // identify the volume.
+  // This field is OPTIONAL and when present MUST be passed to
+  // subsequent `NodeStageVolume` or `NodePublishVolume` calls
+  map<string, string> publish_context = 1;
 }
 message ControllerUnpublishVolumeRequest {
   // The ID of the volume. This field is REQUIRED.
@@ -648,9 +669,10 @@ message ValidateVolumeCapabilitiesRequest {
   // The ID of the volume to check. This field is REQUIRED.
   string volume_id = 1;
 
-  // Attributes of the volume to check. This field is OPTIONAL and MUST
-  // match the attributes of the Volume identified by `volume_id`.
-  map<string, string> volume_attributes = 2;
+  // Volume context as returned by CO in CreateVolumeRequest. This field
+  // is OPTIONAL and MUST match the volume_context of the volume
+  // identified by `volume_id`.
+  map<string, string> volume_context = 2;
 
   // The capabilities that the CO wants to check for the volume. This
   // call SHALL return "confirmed" only if all the volume capabilities
@@ -669,9 +691,9 @@ message ValidateVolumeCapabilitiesRequest {
 
 message ValidateVolumeCapabilitiesResponse {
   message Confirmed {
-    // Volume attributes validated by the plugin.
+    // Volume context validated by the plugin.
     // This field is OPTIONAL.
-    map<string, string> volume_attributes = 1;
+    map<string, string> volume_context = 1;
 
     // Volume capabilities supported by the plugin.
     // This field is REQUIRED.
@@ -843,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
@@ -854,11 +876,16 @@ 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.
-  string id = 2;
+  // 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
   // snapshot from a snapshot is not supported here so the source has to
@@ -944,7 +971,7 @@ message NodeStageVolumeRequest {
   // has `PUBLISH_UNPUBLISH_VOLUME` controller capability, and SHALL be
   // left unset if the corresponding Controller Plugin does not have
   // this capability. This is an OPTIONAL field.
-  map<string, string> publish_info = 2;
+  map<string, string> publish_context = 2;
 
   // The path to which the volume MAY be staged. It MUST be an
   // absolute path in the root filesystem of the process serving this
@@ -967,10 +994,10 @@ message NodeStageVolumeRequest {
   // section on how to use this field.
   map<string, string> secrets = 5 [(csi_secret) = true];
 
-  // Attributes of the volume to stage. This field is OPTIONAL and
-  // MUST match the attributes of the `Volume` identified by
-  // `volume_id`.
-  map<string, string> volume_attributes = 6;
+  // Volume context as returned by CO in CreateVolumeRequest. This field
+  // is OPTIONAL and MUST match the volume_context of the volume
+  // identified by `volume_id`.
+  map<string, string> volume_context = 6;
 }
 
 message NodeStageVolumeResponse {
@@ -998,7 +1025,7 @@ message NodePublishVolumeRequest {
   // has `PUBLISH_UNPUBLISH_VOLUME` controller capability, and SHALL be
   // left unset if the corresponding Controller Plugin does not have
   // this capability. This is an OPTIONAL field.
-  map<string, string> publish_info = 2;
+  map<string, string> publish_context = 2;
 
   // The path to which the volume was staged by `NodeStageVolume`.
   // It MUST be an absolute path in the root filesystem of the process
@@ -1032,10 +1059,10 @@ message NodePublishVolumeRequest {
   // section on how to use this field.
   map<string, string> secrets = 7 [(csi_secret) = true];
 
-  // Attributes of the volume to publish. This field is OPTIONAL and
-  // MUST match the attributes of the Volume identified by
-  // `volume_id`.
-  map<string, string> volume_attributes = 8;
+  // Volume context as returned by CO in CreateVolumeRequest. This field
+  // is OPTIONAL and MUST match the volume_context of the volume
+  // identified by `volume_id`.
+  map<string, string> volume_context = 8;
 }
 
 message NodePublishVolumeResponse {
@@ -1126,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.