Skip to content

spec: default field sizes; clarify OPTIONAL fields #132

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
Nov 9, 2017
Merged

spec: default field sizes; clarify OPTIONAL fields #132

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
6837c76
spec: default field sizes; clarify OPTIONAL fields
Oct 31, 2017
70bd4a5
address review feedback
Nov 2, 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
34 changes: 20 additions & 14 deletions csi.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,12 +181,14 @@ message VolumeCapability {
// Indicate that the volume will be accessed via the filesystem API.
message MountVolume {
// The filesystem type. This field is OPTIONAL.
// An empty string is equal to an unspecified field value.
string fs_type = 1;

// The mount options that can be used for the volume. This field is
// OPTIONAL. `mount_flags` MAY contain sensitive information.
// Therefore, the CO and the Plugin MUST NOT leak this information
// to untrusted entities.
// to untrusted entities. The total size of this repeated field
// SHALL NOT exceed 4 KiB.
repeated string mount_flags = 2;
}

Expand Down Expand Up @@ -232,24 +234,25 @@ message VolumeCapability {
// `required_bytes` and `limit_bytes` can be set to the same value. At
// least one of the these fields MUST be specified.
message CapacityRange {
// Volume must be at least this big.
// Volume must be at least this big. This field is OPTIONAL.
// A value of 0 is equal to an unspecified field value.
uint64 required_bytes = 1;

// Volume must not be bigger than this.
// Volume must not be bigger than this. This field is OPTIONAL.
// A value of 0 is equal to an unspecified field value.
uint64 limit_bytes = 2;
}

// The information about a provisioned volume.
message VolumeInfo {
// The capacity of the volume in bytes. This field is OPTIONAL. If not
// set, it indicates that the capacity of the volume is unknown (e.g.,
// NFS share). If set, it MUST be non-zero.
// set (value of 0), it indicates that the capacity of the volume is
// unknown (e.g., NFS share).
uint64 capacity_bytes = 1;

// 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. This field
// should not exceed 1MiB.
// subsequent calls to refer to the provisioned volume.
string id = 2;

// Attributes reflect static properties of a volume and MUST be passed
Expand Down Expand Up @@ -421,6 +424,7 @@ message ValidateVolumeCapabilitiesResponse {

// Message to the CO if `supported` above is false. This field is
// OPTIONAL.
// An empty string is equal to an unspecified field value.
string message = 2;
}

Expand All @@ -436,18 +440,19 @@ message ListVolumesRequest {
// The API version assumed by the CO. This field is REQUIRED.
Version version = 1;

// If specified, the Plugin MUST NOT return more entries than this
// number in the response. If the actual number of entries is more
// than this number, the Plugin MUST set `next_token` in the response
// which can be used to get the next page of entries in the subsequent
// `ListVolumes` call. This field is OPTIONAL. If not specified, it
// means there is no restriction on the number of entries that can be
// returned.
// If specified (non-zero value), the Plugin MUST NOT return more
// entries than this number in the response. If the actual number of
// entries is more than this number, the Plugin MUST set `next_token`
// in the response which can be used to get the next page of entries
// in the subsequent `ListVolumes` call. This field is OPTIONAL. If
// not specified (zero value), it means there is no restriction on the
// number of entries that can be returned.
uint32 max_entries = 2;

// A token to specify where to start paginating. Set this field to
// `next_token` returned by a previous `ListVolumes` call to get the
// next page of entries. This field is OPTIONAL.
// An empty string is equal to an unspecified field value.
string starting_token = 3;
}

Expand All @@ -464,6 +469,7 @@ message ListVolumesResponse {
// `max_entries`, use the `next_token` as a value for the
// `starting_token` field in the next `ListVolumes` request. This
// field is OPTIONAL.
// An empty string is equal to an unspecified field value.
string next_token = 2;
}

Expand Down
34 changes: 20 additions & 14 deletions lib/go/csi/csi.pb.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

46 changes: 32 additions & 14 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -295,6 +295,18 @@ However, in some circumstances, the CO may lose state (for example when the CO c
The plugin should handle this as gracefully as possible.
The error code `OPERATION_PENDING_FOR_VOLUME` may be returned by the plugin in this case (see general error code section for details).

#### Field Size Limits

CSI defines general size limits for fields of various types (see table below).
The general size limit for a particular field may be overridden by specifying a different size limit in said field's description.
Unless otherwise specified, fields SHALL NOT exceed the limits documented here.
These limits apply for messages generated by both COs and plugins.

| Size | Field Type |
|------------|---------------------|
| 128 bytes | string |
| 4 KiB | map<string, string> |

### Identity Service RPC

Identity service RPCs allow a CO to negotiate an API protocol version that MAY be used for subsequent RPCs across all CSI services with respect to a particular CSI plugin.
Expand Down Expand Up @@ -476,12 +488,14 @@ message VolumeCapability {
// Indicate that the volume will be accessed via the filesystem API.
message MountVolume {
// The filesystem type. This field is OPTIONAL.
// An empty string is equal to an unspecified field value.
string fs_type = 1;

// The mount options that can be used for the volume. This field is
// OPTIONAL. `mount_flags` MAY contain sensitive information.
// Therefore, the CO and the Plugin MUST NOT leak this information
// to untrusted entities.
// to untrusted entities. The total size of this repeated field
// SHALL NOT exceed 4 KiB.
repeated string mount_flags = 2;
}

Expand Down Expand Up @@ -527,24 +541,25 @@ message VolumeCapability {
// `required_bytes` and `limit_bytes` can be set to the same value. At
// least one of the these fields MUST be specified.
message CapacityRange {
// Volume must be at least this big.
// Volume must be at least this big. This field is OPTIONAL.
// A value of 0 is equal to an unspecified field value.
uint64 required_bytes = 1;

// Volume must not be bigger than this.
// Volume must not be bigger than this. This field is OPTIONAL.
// A value of 0 is equal to an unspecified field value.
uint64 limit_bytes = 2;
}

// The information about a provisioned volume.
message VolumeInfo {
// The capacity of the volume in bytes. This field is OPTIONAL. If not
// set, it indicates that the capacity of the volume is unknown (e.g.,
// NFS share). If set, it MUST be non-zero.
// set (value of 0), it indicates that the capacity of the volume is
// unknown (e.g., NFS share).
uint64 capacity_bytes = 1;

// 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. This field
// should not exceed 1MiB.
Copy link
Contributor

Choose a reason for hiding this comment

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

Hi @jdef,

I just want to be clear that the ID string previously would be allowed a field size of 1MiB, but according to the spec today the volume ID is now limited to 128 bytes. Is that correct?

// subsequent calls to refer to the provisioned volume.
string id = 2;

// Attributes reflect static properties of a volume and MUST be passed
Expand Down Expand Up @@ -761,6 +776,7 @@ message ValidateVolumeCapabilitiesResponse {

// Message to the CO if `supported` above is false. This field is
// OPTIONAL.
// An empty string is equal to an unspecified field value.
string message = 2;
}

Expand All @@ -782,18 +798,19 @@ message ListVolumesRequest {
// The API version assumed by the CO. This field is REQUIRED.
Version version = 1;

// If specified, the Plugin MUST NOT return more entries than this
// number in the response. If the actual number of entries is more
// than this number, the Plugin MUST set `next_token` in the response
// which can be used to get the next page of entries in the subsequent
// `ListVolumes` call. This field is OPTIONAL. If not specified, it
// means there is no restriction on the number of entries that can be
// returned.
// If specified (non-zero value), the Plugin MUST NOT return more
// entries than this number in the response. If the actual number of
// entries is more than this number, the Plugin MUST set `next_token`
// in the response which can be used to get the next page of entries
// in the subsequent `ListVolumes` call. This field is OPTIONAL. If
// not specified (zero value), it means there is no restriction on the
// number of entries that can be returned.
uint32 max_entries = 2;

// A token to specify where to start paginating. Set this field to
// `next_token` returned by a previous `ListVolumes` call to get the
// next page of entries. This field is OPTIONAL.
// An empty string is equal to an unspecified field value.
string starting_token = 3;
}

Expand All @@ -810,6 +827,7 @@ message ListVolumesResponse {
// `max_entries`, use the `next_token` as a value for the
// `starting_token` field in the next `ListVolumes` request. This
// field is OPTIONAL.
// An empty string is equal to an unspecified field value.
string next_token = 2;
}

Expand Down