package csi.v1
Get desktop application:
View/edit binary Protocol Buffers messages
service Controller
csi.proto:63rpc CreateVolume (, )
csi.proto:64message
csi.proto:319string name = 1
The suggested name for the storage space. This field is REQUIRED. It serves two purposes: 1) Idempotency - This name is generated by the CO to achieve idempotency. The Plugin SHOULD ensure that multiple `CreateVolume` calls for the same name do not result in more than one piece of storage provisioned corresponding to that name. If a Plugin is unable to enforce idempotency, the CO's error recovery logic could result in multiple (unused) volumes being provisioned. In the case of error, the CO MUST handle the gRPC error codes per the recovery behavior defined in the "CreateVolume Errors" section below. The CO is responsible for cleaning up volumes it provisioned that it no longer needs. If the CO is uncertain whether a volume was provisioned or not when a `CreateVolume` call fails, the CO MAY call `CreateVolume` again, with the same name, to ensure the volume exists and to retrieve the volume's `volume_id` (unless otherwise prohibited by "CreateVolume Errors"). 2) Suggested name - Some storage systems allow callers to specify an identifier by which to refer to the newly provisioned storage. If a storage system supports this, it can optionally use this name as the identifier for the new volume. Any Unicode string that conforms to the length limit is allowed except those containing the following banned characters: U+0000-U+0008, U+000B, U+000C, U+000E-U+001F, U+007F-U+009F. (These are control characters other than commonly used whitespace.)
optional capacity_range = 2
This field is OPTIONAL. This allows the CO to specify the capacity requirement of the volume to be provisioned. If not specified, the Plugin MAY choose an implementation-defined capacity range. If specified it MUST always be honored, even when creating volumes from a source; which MAY force some backends to internally extend the volume after creating it.
repeated volume_capabilities = 3
The capabilities that the provisioned volume MUST have. SP MUST provision a volume that will satisfy ALL of the capabilities specified in this list. Otherwise SP MUST return the appropriate gRPC error code. The Plugin MUST assume that the CO MAY use the provisioned volume with ANY of the capabilities specified in this list. For example, a CO MAY specify two volume capabilities: one with access mode SINGLE_NODE_WRITER and another with access mode MULTI_NODE_READER_ONLY. In this case, the SP MUST verify that the provisioned volume can be used in either mode. This also enables the CO to do early validation: If ANY of the specified volume capabilities are not supported by the SP, the call MUST return the appropriate gRPC error code. This field is REQUIRED.
map<string, string> parameters = 4
Plugin specific creation-time parameters passed in as opaque key-value pairs. This field is OPTIONAL. The Plugin is responsible for parsing and validating these parameters. COs will treat these as opaque.
map<string, string> secrets = 5
Secrets required by plugin to complete volume creation request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
optional volume_content_source = 6
If specified, the new volume will be pre-populated with data from this source. This field is OPTIONAL.
optional accessibility_requirements = 7
Specifies where (regions, zones, racks, etc.) the provisioned volume MUST be accessible from. An SP SHALL advertise the requirements for topological accessibility information in documentation. COs SHALL only specify topological accessibility information supported by the SP. This field is OPTIONAL. This field SHALL NOT be specified unless the SP has the VOLUME_ACCESSIBILITY_CONSTRAINTS plugin capability. If this field is not specified and the SP has the VOLUME_ACCESSIBILITY_CONSTRAINTS plugin capability, the SP MAY choose where the provisioned volume is accessible from.
map<string, string> mutable_parameters = 8
Plugins MUST treat these as if they take precedence over the parameters field. This field SHALL NOT be specified unless the SP has the MODIFY_VOLUME plugin capability.
message
csi.proto:438optional volume = 1
Contains all attributes of the newly created volume that are relevant to the CO along with information required by the Plugin to uniquely identify the volume. This field is REQUIRED.
rpc DeleteVolume (, )
csi.proto:67message
csi.proto:777string volume_id = 1
The ID of the volume to be deprovisioned. This field is REQUIRED.
map<string, string> secrets = 2
Secrets required by plugin to complete volume deletion request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
message
csi.proto:788Intentionally empty.
(message has no fields)
rpc ControllerPublishVolume (, )
csi.proto:70message
csi.proto:791string volume_id = 1
The ID of the volume to be used on a node. This field is REQUIRED.
string node_id = 2
The ID of the node. This field is REQUIRED. The CO SHALL set this field to match the node ID returned by `NodeGetInfo`.
optional volume_capability = 3
Volume capability describing how the CO intends to use this volume. SP MUST ensure the CO can use the published volume as described. Otherwise SP MUST return the appropriate gRPC error code. This is a REQUIRED field.
bool readonly = 4
Indicates SP MUST publish the volume in readonly mode. CO MUST set this field to false if SP does not have the PUBLISH_READONLY controller capability. This is a REQUIRED field.
map<string, string> secrets = 5
Secrets required by plugin to complete controller publish volume request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
map<string, string> volume_context = 6
Volume context as returned by SP in CreateVolumeResponse.Volume.volume_context. This field is OPTIONAL and MUST match the volume_context of the volume identified by `volume_id`.
message
csi.proto:824map<string, string> publish_context = 1
Opaque static publish properties of the volume. SP MAY use this field to ensure subsequent `NodeStageVolume` or `NodePublishVolume` calls calls have contextual information. The contents of this field SHALL be opaque to a CO. The contents of this field SHALL NOT be mutable. The contents of this field SHALL be safe for the CO to cache. The contents of this field SHOULD NOT contain sensitive information. The contents of this field SHOULD NOT be used for uniquely identifying a volume. The `volume_id` alone SHOULD be sufficient to identify the volume. This field is OPTIONAL and when present MUST be passed to subsequent `NodeStageVolume` or `NodePublishVolume` calls
message
csi.proto:840string volume_id = 1
The ID of the volume. This field is REQUIRED.
string node_id = 2
The ID of the node. This field is OPTIONAL. The CO SHOULD set this field to match the node ID returned by `NodeGetInfo` or leave it unset. If the value is set, the SP MUST unpublish the volume from the specified node. If the value is unset, the SP MUST unpublish the volume from all nodes it is published to.
map<string, string> secrets = 3
Secrets required by plugin to complete controller unpublish volume request. This SHOULD be the same secrets passed to the ControllerPublishVolume call for the specified volume. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
message
csi.proto:859Intentionally empty.
(message has no fields)
message
csi.proto:862string volume_id = 1
The ID of the volume to check. This field is REQUIRED.
map<string, string> volume_context = 2
Volume context as returned by SP in CreateVolumeResponse.Volume.volume_context. This field is OPTIONAL and MUST match the volume_context of the volume identified by `volume_id`.
repeated volume_capabilities = 3
The capabilities that the CO wants to check for the volume. This call SHALL return "confirmed" only if all the volume capabilities specified below are supported. This field is REQUIRED.
map<string, string> parameters = 4
See CreateVolumeRequest.parameters. This field is OPTIONAL.
map<string, string> secrets = 5
Secrets required by plugin to complete volume validation request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
map<string, string> mutable_parameters = 6
See CreateVolumeRequest.mutable_parameters. This field is OPTIONAL.
message
csi.proto:891optional confirmed = 1
Confirmed indicates to the CO the set of capabilities that the plugin has validated. This field SHALL only be set to a non-empty value for successful validation responses. For successful validation responses, the CO SHALL compare the fields of this message to the originally requested capabilities in order to guard against an older plugin reporting "valid" for newer capability fields that it does not yet understand. This field is OPTIONAL.
string message = 2
Message to the CO if `confirmed` above is empty. This field is OPTIONAL. An empty string is equal to an unspecified field value.
rpc ListVolumes (, )
csi.proto:79message
csi.proto:925int32 max_entries = 1
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. The value of this field MUST NOT be negative.
string starting_token = 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.
message
csi.proto:943repeated entries = 1
string next_token = 2
This token allows you to get the next page of entries for `ListVolumes` request. If the number of entries is larger than `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.
rpc GetCapacity (, )
csi.proto:82message
csi.proto:1045repeated volume_capabilities = 1
If specified, the Plugin SHALL report the capacity of the storage that can be used to provision volumes that satisfy ALL of the specified `volume_capabilities`. These are the same `volume_capabilities` the CO will use in `CreateVolumeRequest`. This field is OPTIONAL.
map<string, string> parameters = 2
If specified, the Plugin SHALL report the capacity of the storage that can be used to provision volumes with the given Plugin specific `parameters`. These are the same `parameters` the CO will use in `CreateVolumeRequest`. This field is OPTIONAL.
optional accessible_topology = 3
If specified, the Plugin SHALL report the capacity of the storage that can be used to provision volumes that in the specified `accessible_topology`. This is the same as the `accessible_topology` the CO returns in a `CreateVolumeResponse`. This field is OPTIONAL. This field SHALL NOT be set unless the plugin advertises the VOLUME_ACCESSIBILITY_CONSTRAINTS capability.
message
csi.proto:1068int64 available_capacity = 1
The available capacity, in bytes, of the storage that can be used to provision volumes. If `volume_capabilities` or `parameters` is specified in the request, the Plugin SHALL take those into consideration when calculating the available capacity of the storage. This field is REQUIRED. The value of this field MUST NOT be negative.
optional maximum_volume_size = 2
The largest size that may be used in a CreateVolumeRequest.capacity_range.required_bytes field to create a volume with the same parameters as those in GetCapacityRequest. If `volume_capabilities` or `parameters` is specified in the request, the Plugin SHALL take those into consideration when calculating the minimum volume size of the storage. This field is OPTIONAL. MUST NOT be negative. The Plugin SHOULD provide a value for this field if it has a maximum size for individual volumes and leave it unset otherwise. COs MAY use it to make decision about where to create volumes.
optional minimum_volume_size = 3
The smallest size that may be used in a CreateVolumeRequest.capacity_range.limit_bytes field to create a volume with the same parameters as those in GetCapacityRequest. If `volume_capabilities` or `parameters` is specified in the request, the Plugin SHALL take those into consideration when calculating the maximum volume size of the storage. This field is OPTIONAL. MUST NOT be negative. The Plugin SHOULD provide a value for this field if it has a minimum size for individual volumes and leave it unset otherwise. COs MAY use it to make decision about where to create volumes.
message
csi.proto:1112Intentionally empty.
(message has no fields)
message
csi.proto:1116repeated capabilities = 1
All the capabilities that the controller service supports. This field is OPTIONAL.
rpc CreateSnapshot (, )
csi.proto:88message
csi.proto:1198string source_volume_id = 1
The ID of the source volume to be snapshotted. This field is REQUIRED.
string name = 2
The suggested name for the snapshot. This field is REQUIRED for idempotency. Any Unicode string that conforms to the length limit is allowed except those containing the following banned characters: U+0000-U+0008, U+000B, U+000C, U+000E-U+001F, U+007F-U+009F. (These are control characters other than commonly used whitespace.)
map<string, string> secrets = 3
Secrets required by plugin to complete snapshot creation request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
map<string, string> parameters = 4
Plugin specific parameters passed in as opaque key-value pairs. This field is OPTIONAL. The Plugin is responsible for parsing and validating these parameters. COs will treat these as opaque. Use cases for opaque parameters: - Specify a policy to automatically clean up the snapshot. - Specify an expiration date for the snapshot. - Specify whether the snapshot is readonly or read/write. - Specify if the snapshot should be replicated to some place. - Specify primary or secondary for replication systems that support snapshotting only on primary.
message
csi.proto:1229optional snapshot = 1
Contains all attributes of the newly created snapshot that are relevant to the CO along with information required by the Plugin to uniquely identify the snapshot. This field is REQUIRED.
rpc DeleteSnapshot (, )
csi.proto:91message
csi.proto:1287string snapshot_id = 1
The ID of the snapshot to be deleted. This field is REQUIRED.
map<string, string> secrets = 2
Secrets required by plugin to complete snapshot deletion request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
message
csi.proto:1298(message has no fields)
rpc ListSnapshots (, )
csi.proto:94message
csi.proto:1301List all snapshots on the storage system regardless of how they were created.
int32 max_entries = 1
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 `ListSnapshots` 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. The value of this field MUST NOT be negative.
string starting_token = 2
A token to specify where to start paginating. Set this field to `next_token` returned by a previous `ListSnapshots` call to get the next page of entries. This field is OPTIONAL. An empty string is equal to an unspecified field value.
string source_volume_id = 3
Identity information for the source volume. This field is OPTIONAL. It can be used to list snapshots by volume.
string snapshot_id = 4
Identity information for a specific snapshot. This field is OPTIONAL. It can be used to list only a specific snapshot. ListSnapshots will return with current snapshot information and will not block if the snapshot is being processed after it is cut.
map<string, string> secrets = 5
Secrets required by plugin to complete ListSnapshot request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
message
csi.proto:1335repeated entries = 1
string next_token = 2
This token allows you to get the next page of entries for `ListSnapshots` request. If the number of entries is larger than `max_entries`, use the `next_token` as a value for the `starting_token` field in the next `ListSnapshots` request. This field is OPTIONAL. An empty string is equal to an unspecified field value.
rpc ControllerExpandVolume (, )
csi.proto:97message
csi.proto:1350string volume_id = 1
The ID of the volume to expand. This field is REQUIRED.
optional capacity_range = 2
This allows CO to specify the capacity requirements of the volume after expansion. This field is REQUIRED.
map<string, string> secrets = 3
Secrets required by the plugin for expanding the volume. This field is OPTIONAL.
optional volume_capability = 4
Volume capability describing how the CO intends to use this volume. This allows SP to determine if volume is being used as a block device or mounted file system. For example - if volume is being used as a block device - the SP MAY set node_expansion_required to false in ControllerExpandVolumeResponse to skip invocation of NodeExpandVolume on the node by the CO. This is an OPTIONAL field.
message
csi.proto:1372int64 capacity_bytes = 1
Capacity of volume after expansion. This field is REQUIRED.
bool node_expansion_required = 2
Whether node expansion is required for the volume. When true the CO MUST make NodeExpandVolume RPC call on the node. This field is REQUIRED.
rpc ControllerGetVolume (, )
csi.proto:100message
csi.proto:984string volume_id = 1
The ID of the volume to fetch current volume information for. This field is REQUIRED.
message
csi.proto:992optional volume = 1
This field is REQUIRED
optional status = 2
This field is REQUIRED.
rpc ControllerModifyVolume (, )
csi.proto:105message
csi.proto:1018string volume_id = 1
Contains identity information for the existing volume. This field is REQUIRED.
map<string, string> secrets = 2
Secrets required by plugin to complete modify volume request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
map<string, string> mutable_parameters = 3
Plugin specific volume attributes to mutate, passed in as opaque key-value pairs. This field is REQUIRED. The Plugin is responsible for parsing and validating these parameters. COs will treat these as opaque. The CO SHOULD specify the intended values of all mutable parameters it intends to modify. SPs MUST NOT modify volumes based on the absence of keys, only keys that are specified should result in modifications to the volume.
message
csi.proto:1041(message has no fields)
service GroupController
csi.proto:111message
csi.proto:1757Intentionally empty.
(message has no fields)
message
csi.proto:1761repeated capabilities = 1
All the capabilities that the group controller service supports. This field is OPTIONAL.
message
csi.proto:1787string name = 1
The suggested name for the group snapshot. This field is REQUIRED for idempotency. Any Unicode string that conforms to the length limit is allowed except those containing the following banned characters: U+0000-U+0008, U+000B, U+000C, U+000E-U+001F, U+007F-U+009F. (These are control characters other than commonly used whitespace.)
repeated string source_volume_ids = 2
volume IDs of the source volumes to be snapshotted together. This field is REQUIRED.
map<string, string> secrets = 3
Secrets required by plugin to complete ControllerCreateVolumeGroupSnapshot request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field. The secrets provided in this field SHOULD be the same for all group snapshot operations on the same group snapshot.
map<string, string> parameters = 4
Plugin specific parameters passed in as opaque key-value pairs. This field is OPTIONAL. The Plugin is responsible for parsing and validating these parameters. COs will treat these as opaque.
message
csi.proto:1814optional group_snapshot = 1
Contains all attributes of the newly created group snapshot. This field is REQUIRED.
message
csi.proto:1851string group_snapshot_id = 1
The ID of the group snapshot to be deleted. This field is REQUIRED.
repeated string snapshot_ids = 2
A list of snapshot IDs that are part of this group snapshot. If SP does not need to rely on this field to delete the snapshots in the group, it SHOULD check this field and report an error if it has the ability to detect a mismatch. Some SPs require this list to delete the snapshots in the group. If SP needs to use this field to delete the snapshots in the group, it MUST report an error if it has the ability to detect a mismatch. This field is REQUIRED.
map<string, string> secrets = 3
Secrets required by plugin to complete group snapshot deletion request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field. The secrets provided in this field SHOULD be the same for all group snapshot operations on the same group snapshot.
message
csi.proto:1876Intentionally empty.
(message has no fields)
rpc GetVolumeGroupSnapshot (, )
csi.proto:124message
csi.proto:1879string group_snapshot_id = 1
The ID of the group snapshot to fetch current group snapshot information for. This field is REQUIRED.
repeated string snapshot_ids = 2
A list of snapshot IDs that are part of this group snapshot. If SP does not need to rely on this field to get the snapshots in the group, it SHOULD check this field and report an error if it has the ability to detect a mismatch. Some SPs require this list to get the snapshots in the group. If SP needs to use this field to get the snapshots in the group, it MUST report an error if it has the ability to detect a mismatch. This field is REQUIRED.
map<string, string> secrets = 3
Secrets required by plugin to complete GetVolumeGroupSnapshot request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field. The secrets provided in this field SHOULD be the same for all group snapshot operations on the same group snapshot.
message
csi.proto:1905optional group_snapshot = 1
This field is REQUIRED
service Identity
csi.proto:52rpc GetPluginInfo (, )
csi.proto:53message
csi.proto:167Intentionally empty.
(message has no fields)
message
csi.proto:171string name = 1
The name MUST follow domain name notation format (https://tools.ietf.org/html/rfc1035#section-2.3.1). It SHOULD include the plugin's host company name and the plugin name, to minimize the possibility of collisions. It MUST be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), dots (.), and alphanumerics between. This field is REQUIRED.
string vendor_version = 2
This field is REQUIRED. Value of this field is opaque to the CO.
map<string, string> manifest = 3
This field is OPTIONAL. Values are opaque to the CO.
rpc GetPluginCapabilities (, )
csi.proto:56message
csi.proto:187Intentionally empty.
(message has no fields)
message
csi.proto:191repeated capabilities = 1
All the capabilities that the controller service supports. This field is OPTIONAL.
rpc Probe (, )
csi.proto:59message
csi.proto:292Intentionally empty.
(message has no fields)
message
csi.proto:296optional ready = 1
Readiness allows a plugin to report its initialization status back to the CO. Initialization for some plugins MAY be time consuming and it is important for a CO to distinguish between the following cases: 1) The plugin is in an unhealthy state and MAY need restarting. In this case a gRPC error code SHALL be returned. 2) The plugin is still initializing, but is otherwise perfectly healthy. In this case a successful response SHALL be returned with a readiness value of `false`. Calls to the plugin's Controller and/or Node services MAY fail due to an incomplete initialization state. 3) The plugin has finished initializing and is ready to service calls to its Controller and/or Node services. A successful response is returned with a readiness value of `true`. This field is OPTIONAL. If not present, the caller SHALL assume that the plugin is in a ready state and is accepting calls to its Controller and/or Node services (according to the plugin's reported capabilities).
service Node
csi.proto:140rpc NodeStageVolume (, )
csi.proto:141message
csi.proto:1381string volume_id = 1
The ID of the volume to publish. This field is REQUIRED.
map<string, string> publish_context = 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.
string staging_target_path = 3
The path to which the volume MAY be staged. It MUST be an absolute path in the root filesystem of the process serving this request, and MUST be a directory. The CO SHALL ensure that there is only one `staging_target_path` per volume. The CO SHALL ensure that the path is directory and that the process serving the request has `read` and `write` permission to that directory. The CO SHALL be responsible for creating the directory if it does not exist. This is a REQUIRED field. This field overrides the general CSI size limit. SP SHOULD support the maximum path length allowed by the operating system/filesystem, but, at a minimum, SP MUST accept a max path length of at least 128 bytes.
optional volume_capability = 4
Volume capability describing how the CO intends to use this volume. SP MUST ensure the CO can use the staged volume as described. Otherwise SP MUST return the appropriate gRPC error code. This is a REQUIRED field.
map<string, string> secrets = 5
Secrets required by plugin to complete node stage volume request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
map<string, string> volume_context = 6
Volume context as returned by SP in CreateVolumeResponse.Volume.volume_context. This field is OPTIONAL and MUST match the volume_context of the volume identified by `volume_id`.
message
csi.proto:1425Intentionally empty.
(message has no fields)
rpc NodeUnstageVolume (, )
csi.proto:144message
csi.proto:1428string volume_id = 1
The ID of the volume. This field is REQUIRED.
string staging_target_path = 2
The path at which the volume was staged. It MUST be an absolute path in the root filesystem of the process serving this request. This is a REQUIRED field. This field overrides the general CSI size limit. SP SHOULD support the maximum path length allowed by the operating system/filesystem, but, at a minimum, SP MUST accept a max path length of at least 128 bytes.
message
csi.proto:1442Intentionally empty.
(message has no fields)
rpc NodePublishVolume (, )
csi.proto:147message
csi.proto:1445string volume_id = 1
The ID of the volume to publish. This field is REQUIRED.
map<string, string> publish_context = 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.
string staging_target_path = 3
The path to which the volume was staged by `NodeStageVolume`. It MUST be an absolute path in the root filesystem of the process serving this request. It MUST be set if the Node Plugin implements the `STAGE_UNSTAGE_VOLUME` node capability. This is an OPTIONAL field. This field overrides the general CSI size limit. SP SHOULD support the maximum path length allowed by the operating system/filesystem, but, at a minimum, SP MUST accept a max path length of at least 128 bytes.
string 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. The CO SHALL ensure that the parent directory of this path exists and that the process serving the request has `read` and `write` permissions to that parent directory. For volumes with an access type of block, the SP SHALL place the block device at target_path. For volumes with an access type of mount, the SP SHALL place the mounted directory at target_path. Creation of target_path is the responsibility of the SP. This is a REQUIRED field. This field overrides the general CSI size limit. SP SHOULD support the maximum path length allowed by the operating system/filesystem, but, at a minimum, SP MUST accept a max path length of at least 128 bytes.
optional volume_capability = 5
Volume capability describing how the CO intends to use this volume. SP MUST ensure the CO can use the published volume as described. Otherwise SP MUST return the appropriate gRPC error code. This is a REQUIRED field.
bool readonly = 6
Indicates SP MUST publish the volume in readonly mode. This field is REQUIRED.
map<string, string> secrets = 7
Secrets required by plugin to complete node publish volume request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
map<string, string> volume_context = 8
Volume context as returned by SP in CreateVolumeResponse.Volume.volume_context. This field is OPTIONAL and MUST match the volume_context of the volume identified by `volume_id`.
message
csi.proto:1508Intentionally empty.
(message has no fields)
rpc NodeUnpublishVolume (, )
csi.proto:150message
csi.proto:1511string volume_id = 1
The ID of the volume. This field is REQUIRED.
string target_path = 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. The SP MUST delete the file or directory it created at this path. This is a REQUIRED field. This field overrides the general CSI size limit. SP SHOULD support the maximum path length allowed by the operating system/filesystem, but, at a minimum, SP MUST accept a max path length of at least 128 bytes.
message
csi.proto:1526Intentionally empty.
(message has no fields)
rpc NodeGetVolumeStats (, )
csi.proto:153message
csi.proto:1529string volume_id = 1
The ID of the volume. This field is REQUIRED.
string volume_path = 2
It can be any valid path where volume was previously staged or published. It MUST be an absolute path in the root filesystem of the process serving this request. This is a REQUIRED field. This field overrides the general CSI size limit. SP SHOULD support the maximum path length allowed by the operating system/filesystem, but, at a minimum, SP MUST accept a max path length of at least 128 bytes.
string staging_target_path = 3
The path where the volume is staged, if the plugin has the STAGE_UNSTAGE_VOLUME capability, otherwise empty. If not empty, it MUST be an absolute path in the root filesystem of the process serving this request. This field is OPTIONAL. This field overrides the general CSI size limit. SP SHOULD support the maximum path length allowed by the operating system/filesystem, but, at a minimum, SP MUST accept a max path length of at least 128 bytes.
message
csi.proto:1556repeated usage = 1
This field is OPTIONAL.
optional volume_condition = 2
Information about the current condition of the volume. This field is OPTIONAL. This field MUST be specified if the VOLUME_CONDITION node capability is supported.
rpc NodeExpandVolume (, )
csi.proto:157message
csi.proto:1705string volume_id = 1
The ID of the volume. This field is REQUIRED.
string volume_path = 2
The path on which volume is available. This field is REQUIRED. This field overrides the general CSI size limit. SP SHOULD support the maximum path length allowed by the operating system/filesystem, but, at a minimum, SP MUST accept a max path length of at least 128 bytes.
optional capacity_range = 3
This allows CO to specify the capacity requirements of the volume after expansion. If capacity_range is omitted then a plugin MAY inspect the file system of the volume to determine the maximum capacity to which the volume can be expanded. In such cases a plugin MAY expand the volume to its maximum capacity. This field is OPTIONAL.
string staging_target_path = 4
The path where the volume is staged, if the plugin has the STAGE_UNSTAGE_VOLUME capability, otherwise empty. If not empty, it MUST be an absolute path in the root filesystem of the process serving this request. This field is OPTIONAL. This field overrides the general CSI size limit. SP SHOULD support the maximum path length allowed by the operating system/filesystem, but, at a minimum, SP MUST accept a max path length of at least 128 bytes.
optional volume_capability = 5
Volume capability describing how the CO intends to use this volume. This allows SP to determine if volume is being used as a block device or mounted file system. For example - if volume is being used as a block device the SP MAY choose to skip expanding the filesystem in NodeExpandVolume implementation but still perform rest of the housekeeping needed for expanding the volume. If volume_capability is omitted the SP MAY determine access_type from given volume_path for the volume and perform node expansion. This is an OPTIONAL field.
map<string, string> secrets = 6
Secrets required by plugin to complete node expand volume request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
message
csi.proto:1753int64 capacity_bytes = 1
The capacity of the volume in bytes. This field is OPTIONAL.
rpc NodeGetCapabilities (, )
csi.proto:161message
csi.proto:1601Intentionally empty.
(message has no fields)
message
csi.proto:1605repeated capabilities = 1
All the capabilities that the node service supports. This field is OPTIONAL.
rpc NodeGetInfo (, )
csi.proto:164message
csi.proto:1661(message has no fields)
message
csi.proto:1664string node_id = 1
The identifier of the node as understood by the SP. This field is REQUIRED. This field MUST contain enough information to uniquely identify this specific node vs all other nodes supported by this plugin. This field SHALL be used by the CO in subsequent calls, including `ControllerPublishVolume`, to refer to this node. The SP is NOT responsible for global uniqueness of node_id across multiple SPs. This field overrides the general CSI size limit. The size of this field SHALL NOT exceed 256 bytes. The general CSI size limit, 128 byte, is RECOMMENDED for best backwards compatibility.
int64 max_volumes_per_node = 2
Maximum number of volumes that controller can publish to the node. If value is not set or zero CO SHALL decide how many volumes of this type can be published by the controller to the node. The plugin MUST NOT set negative values here. This field is OPTIONAL.
optional accessible_topology = 3
Specifies where (regions, zones, racks, etc.) the node is accessible from. A plugin that returns this field MUST also set the VOLUME_ACCESSIBILITY_CONSTRAINTS plugin capability. COs MAY use this information along with the topology information returned in CreateVolumeResponse to ensure that a given volume is accessible from a given node when scheduling workloads. This field is OPTIONAL. If it is not specified, the CO MAY assume the node is not subject to any topological constraint, and MAY schedule workloads that reference any volume V, such that there are no topological constraints declared for V. Example 1: accessible_topology = {"region": "R1", "zone": "Z2"} Indicates the node exists within the "region" "R1" and the "zone" "Z2".
service SnapshotMetadata
csi.proto:130rpc GetMetadataAllocated (, stream )
csi.proto:133message
csi.proto:1936The GetMetadataAllocatedRequest message is used to solicit metadata on the allocated blocks of a snapshot: i.e. this identifies the data ranges that have valid data as they were the target of some previous write operation on the volume.
string snapshot_id = 1
This is the identifier of the snapshot. This field is REQUIRED.
int64 starting_offset = 2
This indicates the zero based starting byte position in the volume snapshot from which the result should be computed. It is intended to be used to continue a previously interrupted call. The CO SHOULD specify this value to be the offset of the byte position immediately after the last byte of the last data range received, if continuing an interrupted operation, or zero if not. The SP MUST ensure that the returned response stream does not contain BlockMetadata tuples that end before the requested starting_offset: i.e. if S is the requested starting_offset, and B0 is block_metadata[0] of the first message in the response stream, then (S < B0.byte_offset + B0.size_bytes) must be true. This field is REQUIRED.
int32 max_results = 3
This is an optional parameter, and if non-zero it specifies the maximum number of tuples to be returned in each GetMetadataAllocatedResponse message returned by the RPC stream. The plugin will determine an appropriate value if 0, and is always free to send less than the requested value. This field is OPTIONAL.
map<string, string> secrets = 4
Secrets required by plugin to complete the request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
message
csi.proto:1973GetMetadataAllocatedResponse messages are returned in a gRPC stream. Cumulatively, they provide information on the allocated data ranges in the snapshot.
BlockMetadataType block_metadata_type = 1
This specifies the style used in the BlockMetadata sequence. This value must be the same in all such messages returned by the stream. If block_metadata_type is FIXED_LENGTH, then the size_bytes field of each message in the block_metadata list MUST be constant. This field is REQUIRED.
int64 volume_capacity_bytes = 2
This returns the capacity of the underlying volume in bytes. This value must be the same in all such messages returned by the stream. This field is REQUIRED.
repeated block_metadata = 3
This is a list of data range tuples. If the value of max_results in the GetMetadataAllocatedRequest message is greater than zero, then the number of entries in this list MUST be less than or equal to that value. The SP MUST respect the value of starting_offset in the request. The byte_offset fields of adjacent BlockMetadata messages MUST be strictly increasing and messages MUST NOT overlap: i.e. for any two BlockMetadata messages, A and B, if A is returned before B, then (A.byte_offset + A.size_bytes <= B.byte_offset) MUST be true. This MUST also be true if A and B are from block_metadata lists in different GetMetadataAllocatedResponse messages in the gRPC stream. This field is OPTIONAL.
rpc GetMetadataDelta (, stream )
csi.proto:136message
csi.proto:2005The GetMetadataDeltaRequest message is used to solicit metadata on the data ranges that have changed between two snapshots.
string base_snapshot_id = 1
This is the identifier of the snapshot against which changes are to be computed. This field is REQUIRED.
string target_snapshot_id = 2
This is the identifier of a second snapshot in the same volume, created after the base snapshot. This field is REQUIRED.
int64 starting_offset = 3
This indicates the zero based starting byte position in the volume snapshot from which the result should be computed. It is intended to be used to continue a previously interrupted call. The CO SHOULD specify this value to be the offset of the byte position immediately after the last byte of the last data range received, if continuing an interrupted operation, or zero if not. The SP MUST ensure that the returned response stream does not contain BlockMetadata tuples that end before the requested starting_offset: i.e. if S is the requested starting_offset, and B0 is block_metadata[0] of the first message in the response stream, then (S < B0.byte_offset + B0.size_bytes) must be true. This field is REQUIRED.
int32 max_results = 4
This is an optional parameter, and if non-zero it specifies the maximum number of tuples to be returned in each GetMetadataDeltaResponse message returned by the RPC stream. The plugin will determine an appropriate value if 0, and is always free to send less than the requested value. This field is OPTIONAL.
map<string, string> secrets = 5
Secrets required by plugin to complete the request. This field is OPTIONAL. Refer to the `Secrets Requirements` section on how to use this field.
message
csi.proto:2049GetMetadataDeltaResponse messages are returned in a gRPC stream. Cumulatively, they provide information on the data ranges that have changed between the base and target snapshots specified in the GetMetadataDeltaRequest message.
BlockMetadataType block_metadata_type = 1
This specifies the style used in the BlockMetadata sequence. This value must be the same in all such messages returned by the stream. If block_metadata_type is FIXED_LENGTH, then the size_bytes field of each message in the block_metadata list MUST be constant. This field is REQUIRED.
int64 volume_capacity_bytes = 2
This returns the capacity of the underlying volume in bytes. This value must be the same in all such messages returned by the stream. This field is REQUIRED.
repeated block_metadata = 3
This is a list of data range tuples. If the value of max_results in the GetMetadataDeltaRequest message is greater than zero, then the number of entries in this list MUST be less than or equal to that value. The SP MUST respect the value of starting_offset in the request. The byte_offset fields of adjacent BlockMetadata messages MUST be strictly increasing and messages MUST NOT overlap: i.e. for any two BlockMetadata messages, A and B, if A is returned before B, then (A.byte_offset + A.size_bytes <= B.byte_offset) MUST be true. This MUST also be true if A and B are from block_metadata lists in different GetMetadataDeltaResponse messages in the gRPC stream. This field is OPTIONAL.
message
csi.proto:1910BlockMetadata specifies a data range.
Used in: ,
int64 byte_offset = 1
This is the zero based byte position in the volume or snapshot, measured from the start of the object. This field is REQUIRED.
int64 size_bytes = 2
This is the size of the data range. size_bytes MUST be greater than zero. This field is REQUIRED.
Used in: ,
UNKNOWN = 0
FIXED_LENGTH = 1
The FIXED_LENGTH value indicates that data ranges are returned in fixed size blocks.
VARIABLE_LENGTH = 2
The VARIABLE_LENGTH value indicates that data ranges are returned in potentially variable sized extents.
message
csi.proto:534The capacity of the storage space in bytes. To specify an exact size, `required_bytes` and `limit_bytes` SHALL be set to the same value. At least one of the these fields MUST be specified.
Used in: , ,
int64 required_bytes = 1
Volume MUST be at least this big. This field is OPTIONAL. A value of 0 is equal to an unspecified field value. The value of this field MUST NOT be negative.
int64 limit_bytes = 2
Volume MUST not be bigger than this. This field is OPTIONAL. A value of 0 is equal to an unspecified field value. The value of this field MUST NOT be negative.
message
csi.proto:995Used in:
repeated string published_node_ids = 1
A list of all the `node_id` of nodes that this volume is controller published on. This field is OPTIONAL. This field MUST be specified if the LIST_VOLUMES_PUBLISHED_NODES controller capability is supported. published_node_ids MAY include nodes not published to or reported by the SP. The CO MUST be resilient to that.
optional volume_condition = 2
Information about the current condition of the volume. This field is OPTIONAL. This field MUST be specified if the VOLUME_CONDITION controller capability is supported.
message
csi.proto:1123Specifies a capability of the controller service.
Used in:
oneof type
rpc = 1
RPC that the controller supports.
message
csi.proto:1124Used in:
RPC.Type type = 1
Used in:
UNKNOWN = 0
CREATE_DELETE_VOLUME = 1
PUBLISH_UNPUBLISH_VOLUME = 2
LIST_VOLUMES = 3
GET_CAPACITY = 4
CREATE_DELETE_SNAPSHOT = 5
Currently the only way to consume a snapshot is to create a volume from it. Therefore plugins supporting CREATE_DELETE_SNAPSHOT MUST support creating volume from snapshot.
LIST_SNAPSHOTS = 6
CLONE_VOLUME = 7
Plugins supporting volume cloning at the storage level MAY report this capability. The source volume MUST be managed by the same plugin. Not all volume sources and parameters combinations MAY work.
PUBLISH_READONLY = 8
Indicates the SP supports ControllerPublishVolume.readonly field.
EXPAND_VOLUME = 9
See VolumeExpansion for details.
LIST_VOLUMES_PUBLISHED_NODES = 10
Indicates the SP supports the ListVolumesResponse.entry.published_node_ids field and the ControllerGetVolumeResponse.published_node_ids field. The SP MUST also support PUBLISH_UNPUBLISH_VOLUME.
VOLUME_CONDITION = 11
Indicates that the Controller service can report volume conditions. An SP MAY implement `VolumeCondition` in only the Controller Plugin, only the Node Plugin, or both. If `VolumeCondition` is implemented in both the Controller and Node Plugins, it SHALL report from different perspectives. If for some reason Controller and Node Plugins report misaligned volume conditions, CO SHALL assume the worst case is the truth. Note that, for alpha, `VolumeCondition` is intended be informative for humans only, not for automation.
GET_VOLUME = 12
Indicates the SP supports the ControllerGetVolume RPC. This enables COs to, for example, fetch per volume condition after a volume is provisioned.
SINGLE_NODE_MULTI_WRITER = 13
Indicates the SP supports the SINGLE_NODE_SINGLE_WRITER and/or SINGLE_NODE_MULTI_WRITER access modes. These access modes are intended to replace the SINGLE_NODE_WRITER access mode to clarify the number of writers for a volume on a single node. Plugins MUST accept and allow use of the SINGLE_NODE_WRITER access mode when either SINGLE_NODE_SINGLE_WRITER and/or SINGLE_NODE_MULTI_WRITER are supported, in order to permit older COs to continue working.
MODIFY_VOLUME = 14
Indicates the SP supports modifying volume with mutable parameters. See ControllerModifyVolume for details.
message
csi.proto:1768Specifies a capability of the group controller service.
Used in:
oneof type
rpc = 1
RPC that the controller supports.
message
csi.proto:1769Used in:
RPC.Type type = 1
Used in:
UNKNOWN = 0
CREATE_DELETE_GET_VOLUME_GROUP_SNAPSHOT = 1
Indicates that the group controller plugin supports creating, deleting, and getting details of a volume group snapshot.
message
csi.proto:1336Used in:
optional snapshot = 1
message
csi.proto:964Used in:
optional volume = 1
This field is REQUIRED
optional status = 2
This field is OPTIONAL. This field MUST be specified if the LIST_VOLUMES_PUBLISHED_NODES controller capability is supported.
message
csi.proto:944Used in:
repeated string published_node_ids = 1
A list of all `node_id` of nodes that the volume in this entry is controller published on. This field is OPTIONAL. If it is not specified and the SP has the LIST_VOLUMES_PUBLISHED_NODES controller capability, the CO MAY assume the volume is not controller published to any nodes. If the field is not specified and the SP does not have the LIST_VOLUMES_PUBLISHED_NODES controller capability, the CO MUST not interpret this field. published_node_ids MAY include nodes not published to or reported by the SP. The CO MUST be resilient to that.
optional volume_condition = 2
Information about the current condition of the volume. This field is OPTIONAL. This field MUST be specified if the VOLUME_CONDITION controller capability is supported.
message
csi.proto:1612Specifies a capability of the node service.
Used in:
oneof type
rpc = 1
RPC that the controller supports.
message
csi.proto:1613Used in:
RPC.Type type = 1
Used in:
UNKNOWN = 0
STAGE_UNSTAGE_VOLUME = 1
GET_VOLUME_STATS = 2
If Plugin implements GET_VOLUME_STATS capability then it MUST implement NodeGetVolumeStats RPC call for fetching volume statistics.
EXPAND_VOLUME = 3
See VolumeExpansion for details.
VOLUME_CONDITION = 4
Indicates that the Node service can report volume conditions. An SP MAY implement `VolumeCondition` in only the Node Plugin, only the Controller Plugin, or both. If `VolumeCondition` is implemented in both the Node and Controller Plugins, it SHALL report from different perspectives. If for some reason Node and Controller Plugins report misaligned volume conditions, CO SHALL assume the worst case is the truth. Note that, for alpha, `VolumeCondition` is intended to be informative for humans only, not for automation.
SINGLE_NODE_MULTI_WRITER = 5
Indicates the SP supports the SINGLE_NODE_SINGLE_WRITER and/or SINGLE_NODE_MULTI_WRITER access modes. These access modes are intended to replace the SINGLE_NODE_WRITER access mode to clarify the number of writers for a volume on a single node. Plugins MUST accept and allow use of the SINGLE_NODE_WRITER access mode (subject to the processing rules for NodePublishVolume), when either SINGLE_NODE_SINGLE_WRITER and/or SINGLE_NODE_MULTI_WRITER are supported, in order to permit older COs to continue working.
VOLUME_MOUNT_GROUP = 6
Indicates that Node service supports mounting volumes with provided volume group identifier during node stage or node publish RPC calls.
message
csi.proto:198Specifies a capability of the plugin.
Used in:
oneof type
service = 1
Service that the plugin supports.
volume_expansion = 2
message
csi.proto:199Used in:
Service.Type type = 1
Used in:
UNKNOWN = 0
CONTROLLER_SERVICE = 1
CONTROLLER_SERVICE indicates that the Plugin provides RPCs for the ControllerService. Plugins SHOULD provide this capability. In rare cases certain plugins MAY wish to omit the ControllerService entirely from their implementation, but such SHOULD NOT be the common case. The presence of this capability determines whether the CO will attempt to invoke the REQUIRED ControllerService RPCs, as well as specific RPCs as indicated by ControllerGetCapabilities.
VOLUME_ACCESSIBILITY_CONSTRAINTS = 2
VOLUME_ACCESSIBILITY_CONSTRAINTS indicates that the volumes for this plugin MAY NOT be equally accessible by all nodes in the cluster. The CO MUST use the topology information returned by CreateVolumeRequest along with the topology information returned by NodeGetInfo to ensure that a given volume is accessible from a given node when scheduling workloads.
GROUP_CONTROLLER_SERVICE = 3
GROUP_CONTROLLER_SERVICE indicates that the Plugin provides RPCs for operating on groups of volumes. Plugins MAY provide this capability. The presence of this capability determines whether the CO will attempt to invoke the REQUIRED GroupController service RPCs, as well as specific RPCs as indicated by GroupControllerGetCapabilities.
SNAPSHOT_METADATA_SERVICE = 4
SNAPSHOT_METADATA_SERVICE indicates that the Plugin provides RPCs to retrieve metadata on the allocated blocks of a single snapshot, or the changed blocks between a pair of snapshots of the same block volume. The presence of this capability determines whether the CO will attempt to invoke the OPTIONAL SnapshotMetadata service RPCs.
message
csi.proto:240Used in:
VolumeExpansion.Type type = 1
Used in:
UNKNOWN = 0
ONLINE = 1
ONLINE indicates that volumes may be expanded when published to a node. When a Plugin implements this capability it MUST implement either the EXPAND_VOLUME controller capability or the EXPAND_VOLUME node capability or both. When a plugin supports ONLINE volume expansion and also has the EXPAND_VOLUME controller capability then the plugin MUST support expansion of volumes currently published and available on a node. When a plugin supports ONLINE volume expansion and also has the EXPAND_VOLUME node capability then the plugin MAY support expansion of node-published volume via NodeExpandVolume. Example 1: Given a shared filesystem volume (e.g. GlusterFs), the Plugin may set the ONLINE volume expansion capability and implement ControllerExpandVolume but not NodeExpandVolume. Example 2: Given a block storage volume type (e.g. EBS), the Plugin may set the ONLINE volume expansion capability and implement both ControllerExpandVolume and NodeExpandVolume. Example 3: Given a Plugin that supports volume expansion only upon a node, the Plugin may set the ONLINE volume expansion capability and implement NodeExpandVolume but not ControllerExpandVolume.
OFFLINE = 2
OFFLINE indicates that volumes currently published and available on a node SHALL NOT be expanded via ControllerExpandVolume. When a plugin supports OFFLINE volume expansion it MUST implement either the EXPAND_VOLUME controller capability or both the EXPAND_VOLUME controller capability and the EXPAND_VOLUME node capability. Example 1: Given a block storage volume type (e.g. Azure Disk) that does not support expansion of "node-attached" (i.e. controller-published) volumes, the Plugin may indicate OFFLINE volume expansion support and implement both ControllerExpandVolume and NodeExpandVolume.
message
csi.proto:1237Information about a specific snapshot.
Used in: , ,
int64 size_bytes = 1
This is the complete size of the snapshot in bytes. The purpose of this field is to give CO guidance on how much space is needed to create a volume from this snapshot. The size of the volume MUST NOT be less than the size of the source snapshot. This field is OPTIONAL. If this field is not set, it indicates that this size is unknown. The value of this field MUST NOT be negative and a size of zero means it is unspecified.
string snapshot_id = 2
The identifier for this snapshot, generated by the plugin. This field is REQUIRED. This field MUST contain enough information to uniquely identify this specific snapshot vs all other snapshots supported by this plugin. This field SHALL be used by the CO in subsequent calls to refer to this snapshot. The SP is NOT responsible for global uniqueness of snapshot_id across multiple SPs.
string source_volume_id = 3
Identity information for the source volume. Note that creating a snapshot from a snapshot is not supported here so the source has to be a volume. This field is REQUIRED.
optional creation_time = 4
Timestamp when the point-in-time snapshot is taken on the storage system. This field is REQUIRED.
bool ready_to_use = 5
Indicates if a snapshot is ready to use as a `volume_content_source` in a `CreateVolumeRequest`. The default value is false. This field is REQUIRED.
string group_snapshot_id = 6
The ID of the volume group snapshot that this snapshot is part of. It uniquely identifies the group snapshot on the storage system. This field is OPTIONAL. If this snapshot is a member of a volume group snapshot, and it MUST NOT be deleted as a stand alone snapshot, then the SP MUST provide the ID of the volume group snapshot in this field. If provided, CO MUST use this field in subsequent volume group snapshot operations to indicate that this snapshot is part of the specified group snapshot. If not provided, CO SHALL treat the snapshot as independent, and SP SHALL allow it to be deleted separately. If this message is inside a VolumeGroupSnapshot message, the value MUST be the same as the group_snapshot_id in that message.
message
csi.proto:774Topology is a map of topological domains to topological segments. A topological domain is a sub-division of a cluster, like "region", "zone", "rack", etc. A topological segment is a specific instance of a topological domain, like "zone3", "rack3", etc. For example {"com.company/zone": "Z1", "com.company/rack": "R3"} Valid keys have two segments: an OPTIONAL prefix and name, separated by a slash (/), for example: "com.company.example/zone". The key name segment is REQUIRED. The prefix is OPTIONAL. The key name MUST be 63 characters or less, begin and end with an alphanumeric character ([a-z0-9A-Z]), and contain only dashes (-), underscores (_), dots (.), or alphanumerics in between, for example "zone". The key prefix MUST be 63 characters or less, begin and end with a lower-case alphanumeric character ([a-z0-9]), contain only dashes (-), dots (.), or lower-case alphanumerics in between, and follow domain name notation format (https://tools.ietf.org/html/rfc1035#section-2.3.1). The key prefix SHOULD include the plugin's host company name and/or the plugin name, to minimize the possibility of collisions with keys from other plugins. If a key prefix is specified, it MUST be identical across all topology keys returned by the SP (across all RPCs). Keys MUST be case-insensitive. Meaning the keys "Zone" and "zone" MUST not both exist. Each value (topological segment) MUST contain 1 or more strings. Each string MUST be 63 characters or less and begin and end with an alphanumeric character with '-', '_', '.', or alphanumerics in between.
Used in: , , ,
map<string, string> segments = 1
message
csi.proto:614Used in:
repeated requisite = 1
Specifies the list of topologies the provisioned volume MUST be accessible from. This field is OPTIONAL. If TopologyRequirement is specified either requisite or preferred or both MUST be specified. If requisite is specified, the provisioned volume MUST be accessible from at least one of the requisite topologies. Given x = number of topologies provisioned volume is accessible from n = number of requisite topologies The CO MUST ensure n >= 1. The SP MUST ensure x >= 1 If x==n, then the SP MUST make the provisioned volume available to all topologies from the list of requisite topologies. If it is unable to do so, the SP MUST fail the CreateVolume call. For example, if a volume should be accessible from a single zone, and requisite = {"region": "R1", "zone": "Z2"} then the provisioned volume MUST be accessible from the "region" "R1" and the "zone" "Z2". Similarly, if a volume should be accessible from two zones, and requisite = {"region": "R1", "zone": "Z2"}, {"region": "R1", "zone": "Z3"} then the provisioned volume MUST be accessible from the "region" "R1" and both "zone" "Z2" and "zone" "Z3". If x<n, then the SP SHALL choose x unique topologies from the list of requisite topologies. If it is unable to do so, the SP MUST fail the CreateVolume call. For example, if a volume should be accessible from a single zone, and requisite = {"region": "R1", "zone": "Z2"}, {"region": "R1", "zone": "Z3"} then the SP may choose to make the provisioned volume available in either the "zone" "Z2" or the "zone" "Z3" in the "region" "R1". Similarly, if a volume should be accessible from two zones, and requisite = {"region": "R1", "zone": "Z2"}, {"region": "R1", "zone": "Z3"}, {"region": "R1", "zone": "Z4"} then the provisioned volume MUST be accessible from any combination of two unique topologies: e.g. "R1/Z2" and "R1/Z3", or "R1/Z2" and "R1/Z4", or "R1/Z3" and "R1/Z4". If x>n, then the SP MUST make the provisioned volume available from all topologies from the list of requisite topologies and MAY choose the remaining x-n unique topologies from the list of all possible topologies. If it is unable to do so, the SP MUST fail the CreateVolume call. For example, if a volume should be accessible from two zones, and requisite = {"region": "R1", "zone": "Z2"} then the provisioned volume MUST be accessible from the "region" "R1" and the "zone" "Z2" and the SP may select the second zone independently, e.g. "R1/Z4".
repeated preferred = 2
Specifies the list of topologies the CO would prefer the volume to be provisioned in. This field is OPTIONAL. If TopologyRequirement is specified either requisite or preferred or both MUST be specified. An SP MUST attempt to make the provisioned volume available using the preferred topologies in order from first to last. If requisite is specified, all topologies in preferred list MUST also be present in the list of requisite topologies. If the SP is unable to to make the provisioned volume available from any of the preferred topologies, the SP MAY choose a topology from the list of requisite topologies. If the list of requisite topologies is not specified, then the SP MAY choose from the list of all possible topologies. If the list of requisite topologies is specified and the SP is unable to to make the provisioned volume available from any of the requisite topologies it MUST fail the CreateVolume call. Example 1: Given a volume should be accessible from a single zone, and requisite = {"region": "R1", "zone": "Z2"}, {"region": "R1", "zone": "Z3"} preferred = {"region": "R1", "zone": "Z3"} then the SP SHOULD first attempt to make the provisioned volume available from "zone" "Z3" in the "region" "R1" and fall back to "zone" "Z2" in the "region" "R1" if that is not possible. Example 2: Given a volume should be accessible from a single zone, and requisite = {"region": "R1", "zone": "Z2"}, {"region": "R1", "zone": "Z3"}, {"region": "R1", "zone": "Z4"}, {"region": "R1", "zone": "Z5"} preferred = {"region": "R1", "zone": "Z4"}, {"region": "R1", "zone": "Z2"} then the SP SHOULD first attempt to make the provisioned volume accessible from "zone" "Z4" in the "region" "R1" and fall back to "zone" "Z2" in the "region" "R1" if that is not possible. If that is not possible, the SP may choose between either the "zone" "Z3" or "Z5" in the "region" "R1". Example 3: Given a volume should be accessible from TWO zones (because an opaque parameter in CreateVolumeRequest, for example, specifies the volume is accessible from two zones, aka synchronously replicated), and requisite = {"region": "R1", "zone": "Z2"}, {"region": "R1", "zone": "Z3"}, {"region": "R1", "zone": "Z4"}, {"region": "R1", "zone": "Z5"} preferred = {"region": "R1", "zone": "Z5"}, {"region": "R1", "zone": "Z3"} then the SP SHOULD first attempt to make the provisioned volume accessible from the combination of the two "zones" "Z5" and "Z3" in the "region" "R1". If that's not possible, it should fall back to a combination of "Z5" and other possibilities from the list of requisite. If that's not possible, it should fall back to a combination of "Z3" and other possibilities from the list of requisite. If that's not possible, it should fall back to a combination of other possibilities from the list of requisite.
message
csi.proto:892Used in:
map<string, string> volume_context = 1
Volume context validated by the plugin. This field is OPTIONAL.
repeated volume_capabilities = 2
Volume capabilities supported by the plugin. This field is REQUIRED.
map<string, string> parameters = 3
The volume creation parameters validated by the plugin. This field is OPTIONAL.
map<string, string> mutable_parameters = 4
The volume creation mutable_parameters validated by the plugin. This field is OPTIONAL.
message
csi.proto:547Information about a specific volume.
Used in: , ,
int64 capacity_bytes = 1
The capacity of the volume in bytes. This field is OPTIONAL. If not set (value of 0), it indicates that the capacity of the volume is unknown (e.g., NFS share). The value of this field MUST NOT be negative.
string volume_id = 2
The identifier for this volume, generated by the plugin. This field is REQUIRED. This field MUST contain enough information to uniquely identify this specific volume vs all other volumes supported by this plugin. This field SHALL be used by the CO in subsequent calls to refer to this volume. The SP is NOT responsible for global uniqueness of volume_id across multiple SPs.
map<string, string> volume_context = 3
Opaque static properties of the volume. SP MAY use this field to ensure subsequent volume validation and publishing calls have contextual information. The contents of this field SHALL be opaque to a CO. The contents of this field SHALL NOT be mutable. The contents of this field SHALL be safe for the CO to cache. The contents of this field SHOULD NOT contain sensitive information. The contents of this field SHOULD NOT be used for uniquely identifying a volume. The `volume_id` alone SHOULD be sufficient to identify the volume. A volume uniquely identified by `volume_id` SHALL always report the same volume_context. This field is OPTIONAL and when present MUST be passed to volume validation and publishing calls.
optional content_source = 4
If specified, indicates that the volume is not empty and is pre-populated with data from the specified source. This field is OPTIONAL.
repeated accessible_topology = 5
Specifies where (regions, zones, racks, etc.) the provisioned volume is accessible from. A plugin that returns this field MUST also set the VOLUME_ACCESSIBILITY_CONSTRAINTS plugin capability. An SP MAY specify multiple topologies to indicate the volume is accessible from multiple locations. COs MAY use this information along with the topology information returned by NodeGetInfo to ensure that a given volume is accessible from a given node when scheduling workloads. This field is OPTIONAL. If it is not specified, the CO MAY assume the volume is equally accessible from all nodes in the cluster and MAY schedule workloads referencing the volume on any available node. Example 1: accessible_topology = {"region": "R1", "zone": "Z2"} Indicates a volume accessible only from the "region" "R1" and the "zone" "Z2". Example 2: accessible_topology = {"region": "R1", "zone": "Z2"}, {"region": "R1", "zone": "Z3"} Indicates a volume accessible from both "zone" "Z2" and "zone" "Z3" in the "region" "R1".
message
csi.proto:446Specify a capability of a volume.
Used in: , , , , , , , ,
oneof access_type
Specifies what API the volume will be accessed using. One of the following fields MUST be specified.
block = 1
mount = 2
optional access_mode = 3
This is a REQUIRED field.
message
csi.proto:480Specify how a volume can be accessed.
Used in:
AccessMode.Mode mode = 1
This field is REQUIRED.
Used in:
UNKNOWN = 0
SINGLE_NODE_WRITER = 1
Can only be published once as read/write on a single node, at any given time.
SINGLE_NODE_READER_ONLY = 2
Can only be published once as readonly on a single node, at any given time.
MULTI_NODE_READER_ONLY = 3
Can be published as readonly at multiple nodes simultaneously.
MULTI_NODE_SINGLE_WRITER = 4
Can be published at multiple nodes simultaneously. Only one of the node can be used as read/write. The rest will be readonly.
MULTI_NODE_MULTI_WRITER = 5
Can be published as read/write at multiple nodes simultaneously.
SINGLE_NODE_SINGLE_WRITER = 6
Can only be published once as read/write at a single workload on a single node, at any given time. SHOULD be used instead of SINGLE_NODE_WRITER for COs using the experimental SINGLE_NODE_MULTI_WRITER capability.
SINGLE_NODE_MULTI_WRITER = 7
Can be published as read/write at multiple workloads on a single node simultaneously. SHOULD be used instead of SINGLE_NODE_WRITER for COs using the experimental SINGLE_NODE_MULTI_WRITER capability.
message
csi.proto:448Indicate that the volume will be accessed via the block device API.
Intentionally empty, for now.
Used in:
(message has no fields)
message
csi.proto:453Indicate that the volume will be accessed via the filesystem API.
Used in:
string fs_type = 1
The filesystem type. This field is OPTIONAL. An empty string is equal to an unspecified field value.
repeated string mount_flags = 2
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. The total size of this repeated field SHALL NOT exceed 4 KiB.
string volume_mount_group = 3
If SP has VOLUME_MOUNT_GROUP node capability and CO provides this field then SP MUST ensure that the volume_mount_group parameter is passed as the group identifier to the underlying operating system mount system call, with the understanding that the set of available mount call parameters and/or mount implementations may vary across operating systems. Additionally, new file and/or directory entries written to the underlying filesystem SHOULD be permission-labeled in such a manner, unless otherwise modified by a workload, that they are both readable and writable by said mount group identifier. This is an OPTIONAL field.
message
csi.proto:1589VolumeCondition represents the current condition of a volume.
Used in: , ,
bool abnormal = 1
Normal volumes are available for use and operating optimally. An abnormal volume does not meet these criteria. This field is REQUIRED.
string message = 2
The message describing the condition of the volume. This field is REQUIRED.
message
csi.proto:416Specifies what source the volume will be created from. One of the type fields MUST be specified.
Used in: ,
oneof type
snapshot = 1
volume = 2
message
csi.proto:417Used in:
string snapshot_id = 1
Contains identity information for the existing source snapshot. This field is REQUIRED. Plugin is REQUIRED to support creating volume from snapshot if it supports the capability CREATE_DELETE_SNAPSHOT.
message
csi.proto:425Used in:
string volume_id = 1
Contains identity information for the existing source volume. This field is REQUIRED. Plugins reporting CLONE_VOLUME capability MUST support creating a volume from another volume.
message
csi.proto:1820Used in: ,
string group_snapshot_id = 1
The identifier for this group snapshot, generated by the plugin. This field MUST contain enough information to uniquely identify this specific snapshot vs all other group snapshots supported by this plugin. This field SHALL be used by the CO in subsequent calls to refer to this group snapshot. The SP is NOT responsible for global uniqueness of group_snapshot_id across multiple SPs. This field is REQUIRED.
repeated snapshots = 2
A list of snapshots belonging to this group. This field is REQUIRED.
optional creation_time = 3
Timestamp of when the volume group snapshot was taken. This field is REQUIRED.
bool ready_to_use = 4
Indicates if all individual snapshots in the group snapshot are ready to use as a `volume_content_source` in a `CreateVolumeRequest`. The default value is false. If any snapshot in the list of snapshots in this message have ready_to_use set to false, the SP MUST set this field to false. If all of the snapshots in the list of snapshots in this message have ready_to_use set to true, the SP SHOULD set this field to true. This field is REQUIRED.
message
csi.proto:1566Used in:
int64 available = 1
The available capacity in specified Unit. This field is OPTIONAL. The value of this field MUST NOT be negative.
int64 total = 2
The total capacity in specified Unit. This field is REQUIRED. The value of this field MUST NOT be negative.
int64 used = 3
The used capacity in specified Unit. This field is OPTIONAL. The value of this field MUST NOT be negative.
VolumeUsage.Unit unit = 4
Units by which values are measured. This field is REQUIRED.
Used in:
UNKNOWN = 0
BYTES = 1
INODES = 2