Skip to content

Commit

Permalink
NodePublishDevice
Browse files Browse the repository at this point in the history 
This patch handles issue #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.
  • Loading branch information
@akutz
akutz committed Oct 23, 2017
1 parent d68da7a commit 4df353c
Show file tree
Hide file tree
Showing 3 changed files with 1,396 additions and 268 deletions.
204 changes: 197 additions & 7 deletions csi.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,12 @@ service Controller {
}

service Node {
rpc NodePublishDevice (NodePublishDeviceRequest)
returns (NodePublishDeviceResponse) {}

rpc NodeUnpublishDevice (NodeUnpublishDeviceRequest)
returns (NodeUnpublishDeviceResponse) {}

rpc NodePublishVolume (NodePublishVolumeRequest)
returns (NodePublishVolumeResponse) {}

Expand Down Expand Up @@ -344,7 +350,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;
}
Expand Down Expand Up @@ -561,6 +568,71 @@ 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 global_target_path per
// volume.
// This is a REQUIRED field.
string global_target_path = 4;

// The capability of the volume the CO expects the volume to have.
// This is a REQUIRED field.
VolumeCapability volume_capability = 5;
}

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 global_target_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;
Expand All @@ -575,23 +647,29 @@ message NodePublishVolumeRequest {
// this capability. This is an OPTIONAL field.
PublishVolumeInfo publish_volume_info = 3;

// The path to which the device was mounted by `NodePublishDevice`.
// It MUST be an absolute path in the root filesystem of the process
// serving this request.
// This is an OPTIONAL field.
string global_target_path = 4;

// 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 target_path per volume.
// This is a REQUIRED field.
string target_path = 4;
string target_path = 5;

// The capability of the volume the CO expects the volume to have.
// This is a REQUIRED field.
VolumeCapability volume_capability = 5;
VolumeCapability volume_capability = 6;

// Whether to publish the volume in readonly mode. This field is
// REQUIRED.
bool readonly = 6;
bool readonly = 7;

// End user credentials used to authenticate/authorize node publish
// request. This field is OPTIONAL.
Credentials user_credentials = 7;
Credentials user_credentials = 8;
}

message NodePublishVolumeResponse {
Expand All @@ -612,14 +690,20 @@ message NodeUnpublishVolumeRequest {
// The handle of the volume. This field is REQUIRED.
VolumeHandle volume_handle = 2;

// The path to which the device was mounted by `NodePublishDevice`.
// It MUST be an absolute path in the root filesystem of the process
// serving this request.
// This is an OPTIONAL field.
string global_target_path = 3;

// 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 target_path = 3;
string target_path = 4;

// End user credentials used to authenticate/authorize node unpublish
// request. This field is OPTIONAL.
Credentials user_credentials = 4;
Credentials user_credentials = 5;
}

message NodeUnpublishVolumeResponse {
Expand Down Expand Up @@ -695,6 +779,7 @@ message NodeServiceCapability {
message RPC {
enum Type {
UNKNOWN = 0;
PUBLISH_UNPUBLISH_DEVICE = 1;
}

Type type = 1;
Expand Down Expand Up @@ -1141,6 +1226,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 {
Expand Down
Loading

0 comments on commit 4df353c

Please sign in to comment.