Skip to content

spec: Update VolumeHandle & NodeID to simple string values #117

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

spec: Update VolumeHandle & NodeID to simple string values #117

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9b226d5
VolumeHandle to string
akutz Oct 4, 2017
f8340d3
NodeID to string
akutz Oct 5, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 62 additions & 93 deletions csi.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -245,31 +245,9 @@ message VolumeInfo {

// 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.
VolumeHandle handle = 2;
}

// VolumeHandle objects are generated by Plugin implementations to
// serve two purposes: first, to efficiently identify a volume known
// to the Plugin implementation; second, to capture additional, opaque,
// possibly sensitive information associated with a volume. It SHALL
// NOT change over the lifetime of the volume and MAY be safely cached
// by the CO.
// Since this object will be passed around by the CO, it is RECOMMENDED
// that each Plugin keeps the information herein as small as possible.
// The total bytes of a serialized VolumeHandle must be less than 1 MiB.
message VolumeHandle {
// ID is the identity of the provisioned volume specified by the
// Plugin. This field is REQUIRED.
// This information SHALL NOT be considered sensitive such that, for
// example, the CO MAY generate log messages that include this data.
string id = 1;

// Metadata captures additional, possibly sensitive, information about
// a volume in the form of key-value pairs. This field is OPTIONAL.
// Since this field MAY contain sensitive information, the CO MUST NOT
// leak this information to untrusted entities.
map<string, string> metadata = 2;
// subsequent calls to refer to the provisioned volume. This field
// should not exceed 1MiB.
string id = 2;
}

// A standard way to encode credential data. The total bytes of the
Expand All @@ -292,9 +270,9 @@ message DeleteVolumeRequest {
// The API version assumed by the CO. This field is REQUIRED.
Version version = 1;

// The handle of the volume to be deprovisioned.
// The ID of the volume to be deprovisioned.
// This field is REQUIRED.
VolumeHandle volume_handle = 2;
string volume_id = 2;

// End user credentials used to authenticate/authorize volume deletion
// request.
Expand All @@ -317,15 +295,15 @@ message ControllerPublishVolumeRequest {
// The API version assumed by the CO. This field is REQUIRED.
Version version = 1;

// The handle of the volume to be used on a node.
// The ID of the volume to be used on a node.
// This field is REQUIRED.
VolumeHandle volume_handle = 2;
string volume_id = 2;

// The ID of the node. This field is OPTIONAL. The CO SHALL set (or
// clear) this field to match the `NodeID` returned by `GetNodeID`.
// `GetNodeID` is allowed to omit `NodeID` from a successful `Result`;
// clear) this field to match the node ID returned by `GetNodeID`.
// `GetNodeID` is allowed to omit node ID from a successful `Result`;
// in such cases the CO SHALL NOT specify this field.
NodeID node_id = 3;
string node_id = 3;

// The capability of the volume the CO expects the volume to have.
// This is a REQUIRED field.
Expand Down Expand Up @@ -356,14 +334,6 @@ message ControllerPublishVolumeResponse {
}
}

message NodeID {
// Information about a node in the form of key-value pairs. This
// information is opaque to the CO. Given this information will be
// passed around by the CO, it is RECOMMENDED that each Plugin keeps
// this information as small as possible. This field is REQUIRED.
map<string, string> values = 1;
}

message PublishVolumeInfo {
// Information returned by the Plugin in `ControllerPublishVolume`
// call. It is in the form of key-value pairs, and is opaque to the
Expand All @@ -378,19 +348,19 @@ message ControllerUnpublishVolumeRequest {
// The API version assumed by the CO. This field is REQUIRED.
Version version = 1;

// The handle of the volume. This field is REQUIRED.
VolumeHandle volume_handle = 2;
// The ID of the volume. This field is REQUIRED.
string volume_id = 2;

// The ID of the node. This field is OPTIONAL. The CO SHALL set (or
// clear) this field to match the `NodeID` returned by `GetNodeID`.
// `GetNodeID` is allowed to omit `NodeID` from a successful `Result`;
// clear) this field to match the node ID returned by `GetNodeID`.
// `GetNodeID` is allowed to omit node ID from a successful `Result`;
// in such cases the CO SHALL NOT specify this field.
//
// If `GetNodeID` does not omit `NodeID` from a successful `Result`,
// If `GetNodeID` does not omit node ID from a successful `Result`,
// the CO MAY omit this field as well, indicating that it does not
// know which node the volume was previously used. The Plugin SHOULD
// return an Error if this is not supported.
NodeID node_id = 3;
string node_id = 3;

// End user credentials used to authenticate/authorize controller
// unpublish request.
Expand All @@ -413,9 +383,8 @@ message ValidateVolumeCapabilitiesRequest {
// The API version assumed by the CO. This is a REQUIRED field.
Version version = 1;

// The information about the volume to check. This is a REQUIRED
// field.
VolumeInfo volume_info = 2;
// The ID of the volume to check. This field is REQUIRED.
string volume_id = 2;

// The capabilities that the CO wants to check for the volume. This
// call SHALL return "supported" only if all the volume capabilities
Expand Down Expand Up @@ -565,8 +534,8 @@ message NodePublishVolumeRequest {
// The API version assumed by the CO. This is a REQUIRED field.
Version version = 1;

// The handle of the volume to publish. This field is REQUIRED.
VolumeHandle volume_handle = 2;
// 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
Expand Down Expand Up @@ -609,8 +578,8 @@ message NodeUnpublishVolumeRequest {
// The API version assumed by the CO. This is a REQUIRED field.
Version version = 1;

// The handle of the volume. This field is REQUIRED.
VolumeHandle volume_handle = 2;
// 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.
Expand Down Expand Up @@ -644,7 +613,7 @@ message GetNodeIDResponse {
// `ControllerPublishVolume`. This is an OPTIONAL field. If unset,
// the CO SHALL leave the `node_id` field unset in
// `ControllerPublishVolume`.
NodeID node_id = 1;
string node_id = 1;
}

// One of the following fields MUST be specified.
Expand Down Expand Up @@ -885,16 +854,16 @@ message Error {
// exponential back off.
OPERATION_PENDING_FOR_VOLUME = 2;

// Indicates that the specified `VolumeHandle` is not allowed or
// 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 `VolumeHandle` before
// Recovery behavior: Caller MUST fix the volume ID before
// retrying.
INVALID_VOLUME_HANDLE = 3;
INVALID_VOLUME_ID = 3;

// Indicates that a volume corresponding to the specified
// `VolumeHandle` does not exist.
// volume ID does not exist.
//
// Recovery behavior: Caller SHOULD assume the `DeleteVolume` call
// succeeded.
Expand Down Expand Up @@ -945,24 +914,24 @@ message Error {
// exponential back off.
OPERATION_PENDING_FOR_VOLUME = 2;

// Indicates that the specified `VolumeHandle` is not allowed or
// 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 `VolumeHandle` before
// Recovery behavior: Caller MUST fix the volume ID before
// retrying.
INVALID_VOLUME_HANDLE = 3;
INVALID_VOLUME_ID = 3;

// Indicates that a volume corresponding to the specified
// `VolumeHandle` does not exist.
// volume ID does not exist.
//
// Recovery behavior: Caller SHOULD verify that the `VolumeHandle`
// 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 = 4;

// Indicates that a volume corresponding to the specified
// `VolumeHandle` is already attached to another node and does not
// volume ID is already attached to another node and does not
// support multi-node attach. If this error code is returned, the
// Plugin MUST also specify the `node_id` of the node the volume
// is already attached to.
Expand All @@ -973,20 +942,20 @@ message Error {
// node before retrying with exponential back off.
VOLUME_ALREADY_PUBLISHED = 5;

// Indicates that a node corresponding to the specified `NodeID`
// Indicates that a node corresponding to the specified node ID
// does not exist.
//
// Recovery behavior: Caller SHOULD verify that the `NodeID` is
// Recovery behavior: Caller SHOULD verify that the node ID is
// correct and that the node is available and has not been
// terminated or deleted before retrying with exponential backoff.
NODE_DOES_NOT_EXIST = 6;

// Indicates that a volume corresponding to the specified
// `VolumeHandle` is already attached to the maximum supported
// volume ID is already attached to the maximum supported
// number of nodes and therefore this operation can not be
// completed until the volume is detached from at least one of the
// existing nodes. When this error code is returned, the Plugin
// MUST also specify the `NodeId` of all the nodes the volume is
// MUST also specify the node ID of all the nodes the volume is
// attached to.
//
// Recovery behavior: Caller MAY use the provided `node_ids`
Expand All @@ -998,12 +967,12 @@ message Error {
UNSUPPORTED_VOLUME_TYPE = 10;
UNSUPPORTED_FS_TYPE = 11;

// Indicates that the specified `NodeID` is not allowed or
// Indicates that the specified node ID is not allowed or
// understood by the Plugin, or the Plugin does not support the
// operation without a `NodeID`. More human-readable information
// operation without a node ID. More human-readable information
// MAY be provided in the `error_description` field.
//
// Recovery behavior: Caller MUST fix the `NodeID` before
// Recovery behavior: Caller MUST fix the node ID before
// retrying.
INVALID_NODE_ID = 8;
}
Expand All @@ -1018,7 +987,7 @@ message Error {
// On `VOLUME_ALREADY_ATTACHED` and `MAX_ATTACHED_NODES` errors,
// this field contains the node(s) that the specified volume is
// already attached to.
repeated NodeID node_ids = 3;
repeated string node_ids = 3;
}

// `ControllerUnpublishVolume` specific error.
Expand Down Expand Up @@ -1057,44 +1026,44 @@ message Error {
// exponential back off.
OPERATION_PENDING_FOR_VOLUME = 2;

// Indicates that the specified `VolumeHandle` is not allowed or
// 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 `VolumeHandle` before
// Recovery behavior: Caller MUST fix the volume ID before
// retrying.
INVALID_VOLUME_HANDLE = 3;
INVALID_VOLUME_ID = 3;

// Indicates that a volume corresponding to the specified
// `VolumeHandle` does not exist.
// volume ID does not exist.
//
// Recovery behavior: Caller SHOULD verify that the `VolumeHandle`
// 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 = 4;

// Indicates that a node corresponding to the specified `NodeID`
// Indicates that a node corresponding to the specified node ID
// does not exist.
//
// Recovery behavior: Caller SHOULD verify that the `NodeID` is
// Recovery behavior: Caller SHOULD verify that the node ID is
// correct and that the node is available and has not been
// terminated or deleted before retrying.
NODE_DOES_NOT_EXIST = 5;

// Indicates that the specified `NodeID` is not allowed or
// Indicates that the specified node 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 `NodeID` before
// Recovery behavior: Caller MUST fix the node ID before
// retrying.
INVALID_NODE_ID = 6;

VOLUME_NOT_ATTACHED_TO_SPECIFIED_NODE = 7;

// Indicates that the Plugin does not support the operation
// without a `NodeID`.
// without a node ID.
//
// Recovery behavior: Caller MUST specify the `NodeID` before
// Recovery behavior: Caller MUST specify the node ID before
// retrying.
NODE_ID_REQUIRED = 8;
}
Expand Down Expand Up @@ -1170,9 +1139,9 @@ message Error {
OPERATION_PENDING_FOR_VOLUME = 1;

// Indicates that a volume corresponding to the specified
// `VolumeHandle` does not exist.
// volume ID does not exist.
//
// Recovery behavior: Caller SHOULD verify that the `VolumeHandle`
// 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;
Expand All @@ -1182,13 +1151,13 @@ message Error {
UNSUPPORTED_FS_TYPE = 5;
MOUNT_ERROR = 6;

// Indicates that the specified `VolumeHandle` is not allowed or
// 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 `VolumeHandle` before
// Recovery behavior: Caller MUST fix the volume ID before
// retrying.
INVALID_VOLUME_HANDLE = 7;
INVALID_VOLUME_ID = 7;
}

NodePublishVolumeErrorCode error_code = 1;
Expand Down Expand Up @@ -1224,22 +1193,22 @@ message Error {
OPERATION_PENDING_FOR_VOLUME = 1;

// Indicates that a volume corresponding to the specified
// `VolumeHandle` does not exist.
// volume ID does not exist.
//
// Recovery behavior: Caller SHOULD verify that the `VolumeHandle`
// 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 `VolumeHandle` is not allowed or
// 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 `VolumeHandle` before
// Recovery behavior: Caller MUST fix the volume ID before
// retrying.
INVALID_VOLUME_HANDLE = 4;
INVALID_VOLUME_ID = 4;
}

NodeUnpublishVolumeErrorCode error_code = 1;
Expand Down
Loading