NodePublishDevice

This patch handles issue container-storage-interface#119 by adding two new RPCs,
"NodePublishDevice" and "NodeUnpublishDevice". These RPCs MUST be called
by the CO if the Node Plugin advertises the "PUBLISH_UNPUBLISH_DEVICE"
capability. Plugins that advertise this capability SHOULD defer volume
reference counting to the CO.

Author: akutz

csi.proto

@@ -38,6 +38,12 @@ service Controller {
 }
 
 service Node {
+  rpc NodePublishDevice (NodePublishDeviceRequest)
+    returns (NodePublishDeviceResponse) {}
+
+  rpc NodeUnpublishDevice (NodeUnpublishDeviceRequest)
+    returns (NodeUnpublishDeviceResponse) {}
+
   rpc NodePublishVolume (NodePublishVolumeRequest)
     returns (NodePublishVolumeResponse) {}
 
@@ -322,7 +328,8 @@ message ControllerPublishVolumeRequest {
 message ControllerPublishVolumeResponse {
   message Result {
     // The SP specific information that will be passed to the Plugin in
-    // the subsequent `NodePublishVolume` call for the given volume.
+    // the subsequent `NodePublishDevice` and `NodePublishVolume` calls
+    // for the given volume.
     // This information is opaque to the CO. This field is OPTIONAL.
     PublishVolumeInfo publish_volume_info = 1;
   }
@@ -530,6 +537,74 @@ message ControllerServiceCapability {
 }
 ////////
 ////////
+message NodePublishDeviceRequest {
+  // The API version assumed by the CO. This is a REQUIRED field.
+  Version version = 1;
+
+  // The ID of the volume to publish. This field is REQUIRED.
+  string volume_id = 2;
+
+  // The CO SHALL set this field to the value returned by
+  // `ControllerPublishVolume` if the corresponding Controller Plugin
+  // 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.
+  PublishVolumeInfo publish_volume_info = 3;
+
+  // The path to which the volume will be published. It MUST be an
+  // absolute path in the root filesystem of the process serving this
+  // request. The CO SHALL ensure uniqueness of mount_path per volume.
+  // This is a REQUIRED field.
+  string mount_path = 4;
+
+  // The capability of the volume the CO expects the volume to have.
+  // This is a REQUIRED field.
+  VolumeCapability volume_capability = 5;
+
+  // End user credentials used to authenticate/authorize node publish
+  // request. This field is OPTIONAL.
+  Credentials user_credentials = 6;
+}
+
+message NodePublishDeviceResponse {
+  message Result {}
+
+  // One of the following fields MUST be specified.
+  oneof reply {
+    Result result = 1;
+    Error error = 2;
+  }
+}
+////////
+////////
+message NodeUnpublishDeviceRequest {
+  // The API version assumed by the CO. This is a REQUIRED field.
+  Version version = 1;
+
+  // The ID of the volume. This field is REQUIRED.
+  string volume_id = 2;
+
+  // The path at which the volume was published. It MUST be an absolute
+  // path in the root filesystem of the process serving this request.
+  // This is a REQUIRED field.
+  string mount_path = 3;
+
+  // End user credentials used to authenticate/authorize node unpublish
+  // request. This field is OPTIONAL.
+  Credentials user_credentials = 4;
+}
+
+message NodeUnpublishDeviceResponse {
+  message Result {}
+
+  // One of the following fields MUST be specified.
+  oneof reply {
+    Result result = 1;
+    Error error = 2;
+  }
+}
+////////
+////////
 message NodePublishVolumeRequest {
   // The API version assumed by the CO. This is a REQUIRED field.
   Version version = 1;
@@ -664,6 +739,7 @@ message NodeServiceCapability {
   message RPC {
     enum Type {
       UNKNOWN = 0;
+      PUBLISH_UNPUBLISH_DEVICE = 1;
     }
 
     Type type = 1;
@@ -1110,6 +1186,111 @@ message Error {
     string error_description = 2;
   }
 
+  // `NodePublishDevice` specific error.
+  message NodePublishDeviceError {
+    enum NodePublishDeviceErrorCode {
+      // Default value for backwards compatibility. SHOULD NOT be
+      // returned by Plugins. However, if a Plugin returns a
+      // `NodePublishDeviceErrorCode` code that an older CSI
+      // client is not aware of, the client will see this code (the
+      // default fallback).
+      //
+      // Recovery behavior: Caller SHOULD consider updating CSI client
+      // to match Plugin CSI version.
+      UNKNOWN = 0;
+
+      // Indicates that there is a already an operation pending for the
+      // specified volume. In general the Cluster Orchestrator (CO) is
+      // responsible for ensuring that there is no more than one call
+      // “in-flight” per volume at a given time. However, in some
+      // circumstances, the CO MAY lose state (for example when the CO
+      // crashes and restarts), and MAY issue multiple calls
+      // simultaneously for the same volume. The Plugin, SHOULD handle
+      // this as gracefully as possible, and MAY return this error code
+      // to reject secondary calls.
+      //
+      // Recovery behavior: Caller SHOULD ensure that there are no other
+      // calls pending for the specified volume, and then retry with
+      // exponential back off.
+      OPERATION_PENDING_FOR_VOLUME = 1;
+
+      // Indicates that a volume corresponding to the specified
+      // volume ID does not exist.
+      //
+      // Recovery behavior: Caller SHOULD verify that the volume ID
+      // is correct and that the volume is accessible and has not been
+      // deleted before retrying with exponential back off.
+      VOLUME_DOES_NOT_EXIST = 2;
+
+      UNSUPPORTED_MOUNT_FLAGS = 3;
+      UNSUPPORTED_VOLUME_TYPE = 4;
+      UNSUPPORTED_FS_TYPE = 5;
+      MOUNT_ERROR = 6;
+
+      // Indicates that the specified volume ID is not allowed or
+      // understood by the Plugin. More human-readable information MAY
+      // be provided in the `error_description` field.
+      //
+      // Recovery behavior: Caller MUST fix the volume ID before
+      // retrying.
+      INVALID_VOLUME_ID = 7;
+    }
+
+    NodePublishDeviceErrorCode error_code = 1;
+    string error_description = 2;
+  }
+
+  // `NodeUnpublishDevice` specific error.
+  message NodeUnpublishDeviceError {
+    enum NodeUnpublishDeviceErrorCode {
+      // Default value for backwards compatibility. SHOULD NOT be
+      // returned by Plugins. However, if a Plugin returns a
+      // `NodeUnpublishDeviceErrorCode` code that an older CSI
+      // client is not aware of, the client will see this code (the
+      // default fallback).
+      //
+      // Recovery behavior: Caller SHOULD consider updating CSI client
+      // to match Plugin CSI version.
+      UNKNOWN = 0;
+
+      // Indicates that there is a already an operation pending for the
+      // specified volume. In general the Cluster Orchestrator (CO) is
+      // responsible for ensuring that there is no more than one call
+      // “in-flight” per volume at a given time. However, in some
+      // circumstances, the CO MAY lose state (for example when the CO
+      // crashes and restarts), and MAY issue multiple calls
+      // simultaneously for the same volume. The Plugin, SHOULD handle
+      // this as gracefully as possible, and MAY return this error code
+      // to reject secondary calls.
+      //
+      // Recovery behavior: Caller SHOULD ensure that there are no other
+      // calls pending for the specified volume, and then retry with
+      // exponential back off.
+      OPERATION_PENDING_FOR_VOLUME = 1;
+
+      // Indicates that a volume corresponding to the specified
+      // volume ID does not exist.
+      //
+      // Recovery behavior: Caller SHOULD verify that the volume ID
+      // is correct and that the volume is accessible and has not been
+      // deleted before retrying with exponential back off.
+      VOLUME_DOES_NOT_EXIST = 2;
+
+      UNMOUNT_ERROR = 3;
+
+      // Indicates that the specified volume ID is not allowed or
+      // understood by the Plugin. More human-readable information MAY
+      // be provided in the `error_description` field.
+      //
+      // Recovery behavior: Caller MUST fix the volume ID before
+      // retrying.
+      INVALID_VOLUME_ID = 4;
+    }
+
+    NodeUnpublishDeviceErrorCode error_code = 1;
+    string error_description = 2;
+  }
+
   // `NodePublishVolume` specific error.
   message NodePublishVolumeError {
     enum NodePublishVolumeErrorCode {