Skip to content

Refactor VolumeHandle into id and vol attributes #123

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

Merged
merged 2 commits into from
Oct 31, 2017
Merged

Refactor VolumeHandle into id and vol attributes #123

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
12d7beb
VolumeHandle to string
akutz Oct 4, 2017
7cb087c
spec: add Attributes to VolumeInfo, and to publish/validation requests.
Oct 19, 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
131 changes: 66 additions & 65 deletions csi.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ message CreateVolumeResponse {
message Result {
// Contains all attributes of the newly created volume that are
// relevant to the CO along with information required by the Plugin
// to uniquely identifying the volume. This field is REQUIRED.
// to uniquely identify the volume. This field is REQUIRED.
VolumeInfo volume_info = 1;
}

Expand Down Expand Up @@ -248,31 +248,19 @@ 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;

// 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;
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess we should probably have a limit for the encoded size of this field. 1MiB, or something else?

}

// A standard way to encode credential data. The total bytes of the
Expand All @@ -295,9 +283,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 @@ -320,9 +308,9 @@ 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`.
Expand All @@ -342,6 +330,11 @@ message ControllerPublishVolumeRequest {
// publish request.
// This field is OPTIONAL.
Credentials user_credentials = 6;

// Attributes of the volume to be used on a node. This field is
// OPTIONAL and MUST match the attributes of the VolumeInfo identified
// by `volume_id`.
map<string,string> volume_attributes = 7;
}

message ControllerPublishVolumeResponse {
Expand Down Expand Up @@ -372,8 +365,8 @@ 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`.
Expand Down Expand Up @@ -407,14 +400,17 @@ 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
// specified below are supported. This field is REQUIRED.
repeated VolumeCapability volume_capabilities = 3;

// Attributes of the volume to check. This field is OPTIONAL and MUST
// match the attributes of the VolumeInfo identified by `volume_id`.
map<string,string> volume_attributes = 4;
}

message ValidateVolumeCapabilitiesResponse {
Expand Down Expand Up @@ -575,8 +571,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 All @@ -602,6 +598,11 @@ message NodePublishVolumeRequest {
// End user credentials used to authenticate/authorize node publish
// request. This field is OPTIONAL.
Credentials user_credentials = 7;

// Attributes of the volume to publish. This field is OPTIONAL and
// MUST match the attributes of the VolumeInfo identified by
// `volume_id`.
map<string,string> volume_attributes = 8;
}

message NodePublishVolumeResponse {
Expand All @@ -619,8 +620,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 @@ -895,16 +896,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 @@ -955,24 +956,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 @@ -992,7 +993,7 @@ message Error {
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
Expand Down Expand Up @@ -1067,18 +1068,18 @@ 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;
Expand Down Expand Up @@ -1201,9 +1202,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 @@ -1213,13 +1214,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 @@ -1255,22 +1256,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