spec: Move AccessMode to VolumeCapability

This patch moved `AccessMode` to `VolumeCapability`, because access mode
is strongly related to the filesystem type. For instance, a plugin might
support `SINGLE_NODE_WRITER` for `xfs`, and `MULTI_NODE_READER_ONLY` for
`gfs2`.

This patch also removed `VolumeCapability` fields from
`ControllerGetCapabilities` and `NodeGetCapabilities` RPCs. It becomes
very tedious to ask the plugins to enumerate all volume capabilities
that a plugin supports, and probably provides less value. To check the
capablities of a volume, the CO should use `ValidateVolumeCapabilities`.
This applies to both newly provisioned volumes and pre-existing volumes.

See discussion in #61.

Author: jieyu

csi.proto

@@ -165,9 +165,12 @@ message CreateVolumeResponse {
 
 // Specify a capability of a volume.
 message VolumeCapability {
+  // Indicate that the volume will be accessed via the block device API.
   message BlockVolume {
     // Intentionally empty, for now.
   }
+
+  // Indicate that the volume will be accessed via the filesystem API.
   message MountVolume {
     // The filesystem type. This field is OPTIONAL.
     string fs_type = 1;
@@ -179,11 +182,41 @@ message VolumeCapability {
     repeated string mount_flags = 2;    
   }
 
-  // One of the following fields MUST be specified.
-  oneof value {
+  // Specify how a volume can be accessed.
+  message AccessMode {
+    enum Mode {
+      UNKNOWN = 0;
+
+      // Can be published as read/write at one node at a time.
+      SINGLE_NODE_WRITER = 1;
+
+      // Can be published as readonly at one node at a time.
+      SINGLE_NODE_READER_ONLY = 2;
+
+      // Can be published as readonly at multiple nodes simultaneously.
+      MULTI_NODE_READER_ONLY = 3;
+
+      // Can be published at multiple nodes simultaneously. Only one of
+      // the node can be used as read/write. The rest will be readonly.
+      MULTI_NODE_SINGLE_WRITER = 4;
+
+      // Can be published as read/write at multiple nodes simultaneously.
+      MULTI_NODE_MULTI_WRITER = 5;
+    }
+
+    // This field is REQUIRED.
+    Mode mode = 1;
+  }
+
+  // Specifies what API the volume will be accessed using. One of the
+  // following fields MUST be specified.
+  oneof access_type {
     BlockVolume block = 1;
     MountVolume mount = 2;
   }
+
+  // This is a REQUIRED field.
+  AccessMode access_mode = 3;
 }
 
 // The capacity of the storage space in bytes. To specify an exact size,
@@ -204,10 +237,6 @@ message VolumeInfo {
   // NFS share). If set, it MUST be non-zero.
   uint64 capacity_bytes = 1;
 
-  // Contains information about how the volume can be accessed. This
-  // field is REQUIRED.
-  AccessMode access_mode = 2;
-
   // 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.
@@ -219,32 +248,6 @@ message VolumeInfo {
   VolumeMetadata metadata = 5;
 }
 
-// Specify how a volume can be accessed.
-message AccessMode {
-  enum Mode {
-    UNKNOWN = 0;
-    
-    // Can be published as read/write at one node at a time.
-    SINGLE_NODE_WRITER = 1;
-
-    // Can be published as readonly at one node at a time.
-    SINGLE_NODE_READER_ONLY = 2;
-
-    // Can be published as readonly at multiple nodes simultaneously.
-    MULTI_NODE_READER_ONLY = 3;
-
-    // Can be published at multiple nodes simultaneously. Only one of
-    // the node can be used as read/write. The rest will be readonly.
-    MULTI_NODE_SINGLE_WRITER = 4;
-
-    // Can be published as read/write at multiple nodes simultaneously.    
-    MULTI_NODE_MULTI_WRITER = 5;
-  }
-
-  // This field is REQUIRED.
-  Mode mode = 1;
-}
-
 // The identity of the volume.
 message VolumeID {
   // The identity of the provisioned volume specified by the Plugin in
@@ -306,6 +309,10 @@ message ControllerPublishVolumeRequest {
   // in such cases the CO SHALL NOT specify this field.
   NodeID node_id = 4;
 
+  // The capability of the volume the CO expects the volume to have.
+  // This is a REQUIRED field.
+  VolumeCapability volume_capability = 6;
+
   // Whether to publish the volume in readonly mode. This field is
   // REQUIRED.
   bool readonly = 5;
@@ -510,12 +517,6 @@ message ControllerServiceCapability {
   oneof type {
     // RPC that the controller supports.
     RPC rpc = 1;
-    
-    // Volume capability the Controller Plugin supports. An SP SHOULD
-    // avoid setting different volume capability for Controller and Node
-    // Plugins if possible. If this happens during the upgrade of the
-    // Plugins, the behavior is UNDEFINED. 
-    VolumeCapability volume_capability = 2;
   }
 }
 ////////
@@ -542,8 +543,8 @@ message NodePublishVolumeRequest {
   // request. This is a REQUIRED field.
   string target_path = 5;
 
-  // The capability of the volume to be published. This is a REQUIRED
-  // field.
+  // The capability of the volume the CO expects the volume to have.
+  // This is a REQUIRED field.
   VolumeCapability volume_capability = 6;
 
   // Whether to publish the volume in readonly mode. This field is
@@ -659,12 +660,6 @@ message NodeServiceCapability {
   oneof type {
     // RPC that the controller supports.
     RPC rpc = 1;
-    
-    // Volume capability the Node Plugin supports. An SP SHOULD avoid
-    // setting different volume capability for Controller and Node
-    // Plugins if possible. If this happens during the upgrade of the
-    // Plugins, the behavior is UNDEFINED. 
-    VolumeCapability volume_capability = 2;
   }
 }
 ////////
@@ -971,6 +966,10 @@ message Error {
       // retrying with exponential backoff.
       MAX_ATTACHED_NODES = 8;
 
+      UNSUPPORTED_MOUNT_FLAGS = 10;
+      UNSUPPORTED_VOLUME_TYPE = 11;
+      UNSUPPORTED_FS_TYPE = 12;
+
       // Indicates that the specified `NodeID` is not allowed or
       // understood by the Plugin, or the Plugin does not support the
       // operation without a `NodeID`. More human-readable information