rawfile-localpv/protos/csi.proto
2021-07-02 20:31:34 +04:30

1636 lines
66 KiB
Protocol Buffer

// Code generated by make; DO NOT EDIT.
syntax = "proto3";
package csi.v1;
import "google/protobuf/descriptor.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
option go_package = "csi";
extend google.protobuf.EnumOptions {
// Indicates that this enum is OPTIONAL and part of an experimental
// API that may be deprecated and eventually removed between minor
// releases.
bool alpha_enum = 1060;
}
extend google.protobuf.EnumValueOptions {
// Indicates that this enum value is OPTIONAL and part of an
// experimental API that may be deprecated and eventually removed
// between minor releases.
bool alpha_enum_value = 1060;
}
extend google.protobuf.FieldOptions {
// Indicates that a field MAY contain information that is sensitive
// and MUST be treated as such (e.g. not logged).
bool csi_secret = 1059;
// Indicates that this field is OPTIONAL and part of an experimental
// API that may be deprecated and eventually removed between minor
// releases.
bool alpha_field = 1060;
}
extend google.protobuf.MessageOptions {
// Indicates that this message is OPTIONAL and part of an experimental
// API that may be deprecated and eventually removed between minor
// releases.
bool alpha_message = 1060;
}
extend google.protobuf.MethodOptions {
// Indicates that this method is OPTIONAL and part of an experimental
// API that may be deprecated and eventually removed between minor
// releases.
bool alpha_method = 1060;
}
extend google.protobuf.ServiceOptions {
// Indicates that this service is OPTIONAL and part of an experimental
// API that may be deprecated and eventually removed between minor
// releases.
bool alpha_service = 1060;
}
service Identity {
rpc GetPluginInfo(GetPluginInfoRequest)
returns (GetPluginInfoResponse) {}
rpc GetPluginCapabilities(GetPluginCapabilitiesRequest)
returns (GetPluginCapabilitiesResponse) {}
rpc Probe (ProbeRequest)
returns (ProbeResponse) {}
}
service Controller {
rpc CreateVolume (CreateVolumeRequest)
returns (CreateVolumeResponse) {}
rpc DeleteVolume (DeleteVolumeRequest)
returns (DeleteVolumeResponse) {}
rpc ControllerPublishVolume (ControllerPublishVolumeRequest)
returns (ControllerPublishVolumeResponse) {}
rpc ControllerUnpublishVolume (ControllerUnpublishVolumeRequest)
returns (ControllerUnpublishVolumeResponse) {}
rpc ValidateVolumeCapabilities (ValidateVolumeCapabilitiesRequest)
returns (ValidateVolumeCapabilitiesResponse) {}
rpc ListVolumes (ListVolumesRequest)
returns (ListVolumesResponse) {}
rpc GetCapacity (GetCapacityRequest)
returns (GetCapacityResponse) {}
rpc ControllerGetCapabilities (ControllerGetCapabilitiesRequest)
returns (ControllerGetCapabilitiesResponse) {}
rpc CreateSnapshot (CreateSnapshotRequest)
returns (CreateSnapshotResponse) {}
rpc DeleteSnapshot (DeleteSnapshotRequest)
returns (DeleteSnapshotResponse) {}
rpc ListSnapshots (ListSnapshotsRequest)
returns (ListSnapshotsResponse) {}
rpc ControllerExpandVolume (ControllerExpandVolumeRequest)
returns (ControllerExpandVolumeResponse) {}
rpc ControllerGetVolume (ControllerGetVolumeRequest)
returns (ControllerGetVolumeResponse) {
option (alpha_method) = true;
}
}
service Node {
rpc NodeStageVolume (NodeStageVolumeRequest)
returns (NodeStageVolumeResponse) {}
rpc NodeUnstageVolume (NodeUnstageVolumeRequest)
returns (NodeUnstageVolumeResponse) {}
rpc NodePublishVolume (NodePublishVolumeRequest)
returns (NodePublishVolumeResponse) {}
rpc NodeUnpublishVolume (NodeUnpublishVolumeRequest)
returns (NodeUnpublishVolumeResponse) {}
rpc NodeGetVolumeStats (NodeGetVolumeStatsRequest)
returns (NodeGetVolumeStatsResponse) {}
rpc NodeExpandVolume(NodeExpandVolumeRequest)
returns (NodeExpandVolumeResponse) {}
rpc NodeGetCapabilities (NodeGetCapabilitiesRequest)
returns (NodeGetCapabilitiesResponse) {}
rpc NodeGetInfo (NodeGetInfoRequest)
returns (NodeGetInfoResponse) {}
}
message GetPluginInfoRequest {
// Intentionally empty.
}
message GetPluginInfoResponse {
// 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 name = 1;
// This field is REQUIRED. Value of this field is opaque to the CO.
string vendor_version = 2;
// This field is OPTIONAL. Values are opaque to the CO.
map<string, string> manifest = 3;
}
message GetPluginCapabilitiesRequest {
// Intentionally empty.
}
message GetPluginCapabilitiesResponse {
// All the capabilities that the controller service supports. This
// field is OPTIONAL.
repeated PluginCapability capabilities = 1;
}
// Specifies a capability of the plugin.
message PluginCapability {
message Service {
enum Type {
UNKNOWN = 0;
// 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.
CONTROLLER_SERVICE = 1;
// 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.
VOLUME_ACCESSIBILITY_CONSTRAINTS = 2;
}
Type type = 1;
}
message VolumeExpansion {
enum Type {
UNKNOWN = 0;
// 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.
ONLINE = 1;
// 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.
OFFLINE = 2;
}
Type type = 1;
}
oneof type {
// Service that the plugin supports.
Service service = 1;
VolumeExpansion volume_expansion = 2;
}
}
message ProbeRequest {
// Intentionally empty.
}
message ProbeResponse {
// 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).
.google.protobuf.BoolValue ready = 1;
}
message CreateVolumeRequest {
// 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.)
string name = 1;
// 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.
CapacityRange capacity_range = 2;
// 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.
repeated VolumeCapability volume_capabilities = 3;
// 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.
map<string, string> parameters = 4;
// 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.
map<string, string> secrets = 5 [(csi_secret) = true];
// If specified, the new volume will be pre-populated with data from
// this source. This field is OPTIONAL.
VolumeContentSource volume_content_source = 6;
// 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.
TopologyRequirement accessibility_requirements = 7;
}
// Specifies what source the volume will be created from. One of the
// type fields MUST be specified.
message VolumeContentSource {
message SnapshotSource {
// 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.
string snapshot_id = 1;
}
message VolumeSource {
// 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.
string volume_id = 1;
}
oneof type {
SnapshotSource snapshot = 1;
VolumeSource volume = 2;
}
}
message CreateVolumeResponse {
// 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.
Volume volume = 1;
}
// Specify a capability of a volume.
message VolumeCapability {
// Indicate that the volume will be accessed via the block device API.
message BlockVolume {
// Intentionally empty, for now.
}
// 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. The total size of this repeated field
// SHALL NOT exceed 4 KiB.
repeated string mount_flags = 2;
// 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.
string volume_mount_group = 3 [(alpha_field) = true];
}
// Specify how a volume can be accessed.
message AccessMode {
enum Mode {
UNKNOWN = 0;
// Can only be published once as read/write on a single node, at
// any given time.
SINGLE_NODE_WRITER = 1;
// Can only be published once as readonly on a single node, at
// any given time.
SINGLE_NODE_READER_ONLY = 2;
// Can be published as readonly at multiple nodes simultaneously.
MULTI_NODE_READER_ONLY = 3;
// 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_SINGLE_WRITER = 4;
// Can be published as read/write at multiple nodes
// simultaneously.
MULTI_NODE_MULTI_WRITER = 5;
// 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_SINGLE_WRITER = 6 [(alpha_enum_value) = true];
// 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.
SINGLE_NODE_MULTI_WRITER = 7 [(alpha_enum_value) = true];
}
// This field is REQUIRED.
Mode mode = 1;
}
// Specifies what API the volume will be accessed using. One of the
// following fields MUST be specified.
oneof access_type {
BlockVolume block = 1;
MountVolume mount = 2;
}
// This is a REQUIRED field.
AccessMode access_mode = 3;
}
// The 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.
message CapacityRange {
// 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 required_bytes = 1;
// 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.
int64 limit_bytes = 2;
}
// Information about a specific volume.
message Volume {
// 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.
int64 capacity_bytes = 1;
// 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.
string volume_id = 2;
// 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.
map<string, string> volume_context = 3;
// If specified, indicates that the volume is not empty and is
// pre-populated with data from the specified source.
// This field is OPTIONAL.
VolumeContentSource content_source = 4;
// 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".
repeated Topology accessible_topology = 5;
}
message TopologyRequirement {
// 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 Topology requisite = 1;
// 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 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 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 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.
repeated Topology preferred = 2;
}
// Topology 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.
message Topology {
map<string, string> segments = 1;
}
message DeleteVolumeRequest {
// The ID of the volume to be deprovisioned.
// This field is REQUIRED.
string volume_id = 1;
// 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.
map<string, string> secrets = 2 [(csi_secret) = true];
}
message DeleteVolumeResponse {
// Intentionally empty.
}
message ControllerPublishVolumeRequest {
// The ID of the volume to be used on a node.
// This field is REQUIRED.
string volume_id = 1;
// The ID of the node. This field is REQUIRED. The CO SHALL set this
// field to match the node ID returned by `NodeGetInfo`.
string node_id = 2;
// 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.
VolumeCapability volume_capability = 3;
// 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.
bool readonly = 4;
// 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> secrets = 5 [(csi_secret) = true];
// 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`.
map<string, string> volume_context = 6;
}
message ControllerPublishVolumeResponse {
// 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
map<string, string> publish_context = 1;
}
message ControllerUnpublishVolumeRequest {
// The ID of the volume. This field is REQUIRED.
string volume_id = 1;
// 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.
string node_id = 2;
// 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.
map<string, string> secrets = 3 [(csi_secret) = true];
}
message ControllerUnpublishVolumeResponse {
// Intentionally empty.
}
message ValidateVolumeCapabilitiesRequest {
// The ID of the volume to check. This field is REQUIRED.
string volume_id = 1;
// 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`.
map<string, string> volume_context = 2;
// 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.
repeated VolumeCapability volume_capabilities = 3;
// See CreateVolumeRequest.parameters.
// This field is OPTIONAL.
map<string, string> parameters = 4;
// 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> secrets = 5 [(csi_secret) = true];
}
message ValidateVolumeCapabilitiesResponse {
message Confirmed {
// Volume context validated by the plugin.
// This field is OPTIONAL.
map<string, string> volume_context = 1;
// Volume capabilities supported by the plugin.
// This field is REQUIRED.
repeated VolumeCapability volume_capabilities = 2;
// The volume creation parameters validated by the plugin.
// This field is OPTIONAL.
map<string, string> parameters = 3;
}
// 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.
Confirmed confirmed = 1;
// Message to the CO if `confirmed` above is empty. This field is
// OPTIONAL.
// An empty string is equal to an unspecified field value.
string message = 2;
}
message ListVolumesRequest {
// 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.
int32 max_entries = 1;
// 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 = 2;
}
message ListVolumesResponse {
message VolumeStatus{
// 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.
repeated string published_node_ids = 1;
// 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.
VolumeCondition volume_condition = 2 [(alpha_field) = true];
}
message Entry {
// This field is REQUIRED
Volume volume = 1;
// This field is OPTIONAL. This field MUST be specified if the
// LIST_VOLUMES_PUBLISHED_NODES controller capability is
// supported.
VolumeStatus status = 2;
}
repeated Entry entries = 1;
// 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.
string next_token = 2;
}
message ControllerGetVolumeRequest {
option (alpha_message) = true;
// The ID of the volume to fetch current volume information for.
// This field is REQUIRED.
string volume_id = 1;
}
message ControllerGetVolumeResponse {
option (alpha_message) = true;
message VolumeStatus{
// 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 PUBLISH_UNPUBLISH_VOLUME
// 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.
repeated string published_node_ids = 1;
// 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.
VolumeCondition volume_condition = 2;
}
// This field is REQUIRED
Volume volume = 1;
// This field is REQUIRED.
VolumeStatus status = 2;
}
message GetCapacityRequest {
// 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.
repeated VolumeCapability volume_capabilities = 1;
// 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.
map<string, string> parameters = 2;
// 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.
Topology accessible_topology = 3;
}
message GetCapacityResponse {
// 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.
int64 available_capacity = 1;
// 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.
google.protobuf.Int64Value maximum_volume_size = 2
[(alpha_field) = true];
// 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.
google.protobuf.Int64Value minimum_volume_size = 3
[(alpha_field) = true];
}
message ControllerGetCapabilitiesRequest {
// Intentionally empty.
}
message ControllerGetCapabilitiesResponse {
// All the capabilities that the controller service supports. This
// field is OPTIONAL.
repeated ControllerServiceCapability capabilities = 1;
}
// Specifies a capability of the controller service.
message ControllerServiceCapability {
message RPC {
enum Type {
UNKNOWN = 0;
CREATE_DELETE_VOLUME = 1;
PUBLISH_UNPUBLISH_VOLUME = 2;
LIST_VOLUMES = 3;
GET_CAPACITY = 4;
// 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.
CREATE_DELETE_SNAPSHOT = 5;
LIST_SNAPSHOTS = 6;
// 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.
CLONE_VOLUME = 7;
// Indicates the SP supports ControllerPublishVolume.readonly
// field.
PUBLISH_READONLY = 8;
// See VolumeExpansion for details.
EXPAND_VOLUME = 9;
// Indicates the SP supports the
// ListVolumesResponse.entry.published_nodes field
LIST_VOLUMES_PUBLISHED_NODES = 10;
// 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.
VOLUME_CONDITION = 11 [(alpha_enum_value) = true];
// Indicates the SP supports the ControllerGetVolume RPC.
// This enables COs to, for example, fetch per volume
// condition after a volume is provisioned.
GET_VOLUME = 12 [(alpha_enum_value) = true];
// 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.
SINGLE_NODE_MULTI_WRITER = 13 [(alpha_enum_value) = true];
}
Type type = 1;
}
oneof type {
// RPC that the controller supports.
RPC rpc = 1;
}
}
message CreateSnapshotRequest {
// The ID of the source volume to be snapshotted.
// This field is REQUIRED.
string source_volume_id = 1;
// 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.)
string name = 2;
// 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> secrets = 3 [(csi_secret) = true];
// 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.
map<string, string> parameters = 4;
}
message CreateSnapshotResponse {
// 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.
Snapshot snapshot = 1;
}
// Information about a specific snapshot.
message Snapshot {
// 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.
int64 size_bytes = 1;
// 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 snapshot_id = 2;
// 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.
string source_volume_id = 3;
// Timestamp when the point-in-time snapshot is taken on the storage
// system. This field is REQUIRED.
.google.protobuf.Timestamp creation_time = 4;
// 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.
bool ready_to_use = 5;
}
message DeleteSnapshotRequest {
// The ID of the snapshot to be deleted.
// This field is REQUIRED.
string snapshot_id = 1;
// 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.
map<string, string> secrets = 2 [(csi_secret) = true];
}
message DeleteSnapshotResponse {}
// List all snapshots on the storage system regardless of how they were
// created.
message ListSnapshotsRequest {
// 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.
int32 max_entries = 1;
// 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 starting_token = 2;
// Identity information for the source volume. This field is OPTIONAL.
// It can be used to list snapshots by volume.
string source_volume_id = 3;
// 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.
string snapshot_id = 4;
// Secrets required by plugin to complete ListSnapshot request.
// This field is OPTIONAL. Refer to the `Secrets Requirements`
// section on how to use this field.
map<string, string> secrets = 5 [(csi_secret) = true];
}
message ListSnapshotsResponse {
message Entry {
Snapshot snapshot = 1;
}
repeated Entry entries = 1;
// 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.
string next_token = 2;
}
message ControllerExpandVolumeRequest {
// The ID of the volume to expand. This field is REQUIRED.
string volume_id = 1;
// This allows CO to specify the capacity requirements of the volume
// after expansion. This field is REQUIRED.
CapacityRange capacity_range = 2;
// Secrets required by the plugin for expanding the volume.
// This field is OPTIONAL.
map<string, string> secrets = 3 [(csi_secret) = true];
// 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.
VolumeCapability volume_capability = 4;
}
message ControllerExpandVolumeResponse {
// Capacity of volume after expansion. This field is REQUIRED.
int64 capacity_bytes = 1;
// Whether node expansion is required for the volume. When true
// the CO MUST make NodeExpandVolume RPC call on the node. This field
// is REQUIRED.
bool node_expansion_required = 2;
}
message NodeStageVolumeRequest {
// The ID of the volume to publish. This field is REQUIRED.
string volume_id = 1;
// 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.
map<string, string> publish_context = 2;
// 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.
string staging_target_path = 3;
// 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.
VolumeCapability volume_capability = 4;
// 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> secrets = 5 [(csi_secret) = true];
// 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`.
map<string, string> volume_context = 6;
}
message NodeStageVolumeResponse {
// Intentionally empty.
}
message NodeUnstageVolumeRequest {
// The ID of the volume. This field is REQUIRED.
string volume_id = 1;
// 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.
string staging_target_path = 2;
}
message NodeUnstageVolumeResponse {
// Intentionally empty.
}
message NodePublishVolumeRequest {
// The ID of the volume to publish. This field is REQUIRED.
string volume_id = 1;
// 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.
map<string, string> publish_context = 2;
// 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 staging_target_path = 3;
// The path to which the volume will be published. It MUST be an
// absolute path in the root filesystem of the process serving this
// request. The CO SHALL ensure uniqueness of 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.
string target_path = 4;
// 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.
VolumeCapability volume_capability = 5;
// Indicates SP MUST publish the volume in readonly mode.
// This field is REQUIRED.
bool readonly = 6;
// 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> secrets = 7 [(csi_secret) = true];
// 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`.
map<string, string> volume_context = 8;
}
message NodePublishVolumeResponse {
// Intentionally empty.
}
message NodeUnpublishVolumeRequest {
// The ID of the volume. This field is REQUIRED.
string volume_id = 1;
// 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.
string target_path = 2;
}
message NodeUnpublishVolumeResponse {
// Intentionally empty.
}
message NodeGetVolumeStatsRequest {
// The ID of the volume. This field is REQUIRED.
string volume_id = 1;
// 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 volume_path = 2;
// 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.
string staging_target_path = 3;
}
message NodeGetVolumeStatsResponse {
// This field is OPTIONAL.
repeated VolumeUsage usage = 1;
// 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.
VolumeCondition volume_condition = 2 [(alpha_field) = true];
}
message VolumeUsage {
enum Unit {
UNKNOWN = 0;
BYTES = 1;
INODES = 2;
}
// The available capacity in specified Unit. This field is OPTIONAL.
// The value of this field MUST NOT be negative.
int64 available = 1;
// The total capacity in specified Unit. This field is REQUIRED.
// The value of this field MUST NOT be negative.
int64 total = 2;
// The used capacity in specified Unit. This field is OPTIONAL.
// The value of this field MUST NOT be negative.
int64 used = 3;
// Units by which values are measured. This field is REQUIRED.
Unit unit = 4;
}
// VolumeCondition represents the current condition of a volume.
message VolumeCondition {
option (alpha_message) = true;
// Normal volumes are available for use and operating optimally.
// An abnormal volume does not meet these criteria.
// This field is REQUIRED.
bool abnormal = 1;
// The message describing the condition of the volume.
// This field is REQUIRED.
string message = 2;
}
message NodeGetCapabilitiesRequest {
// Intentionally empty.
}
message NodeGetCapabilitiesResponse {
// All the capabilities that the node service supports. This field
// is OPTIONAL.
repeated NodeServiceCapability capabilities = 1;
}
// Specifies a capability of the node service.
message NodeServiceCapability {
message RPC {
enum Type {
UNKNOWN = 0;
STAGE_UNSTAGE_VOLUME = 1;
// If Plugin implements GET_VOLUME_STATS capability
// then it MUST implement NodeGetVolumeStats RPC
// call for fetching volume statistics.
GET_VOLUME_STATS = 2;
// See VolumeExpansion for details.
EXPAND_VOLUME = 3;
// 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.
VOLUME_CONDITION = 4 [(alpha_enum_value) = true];
// 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.
SINGLE_NODE_MULTI_WRITER = 5 [(alpha_enum_value) = true];
// Indicates that Node service supports mounting volumes
// with provided volume group identifier during node stage
// or node publish RPC calls.
VOLUME_MOUNT_GROUP = 6 [(alpha_enum_value) = true];
}
Type type = 1;
}
oneof type {
// RPC that the controller supports.
RPC rpc = 1;
}
}
message NodeGetInfoRequest {
}
message NodeGetInfoResponse {
// 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.
string node_id = 1;
// 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.
int64 max_volumes_per_node = 2;
// 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".
Topology accessible_topology = 3;
}
message NodeExpandVolumeRequest {
// The ID of the volume. This field is REQUIRED.
string volume_id = 1;
// 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.
string volume_path = 2;
// 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.
CapacityRange capacity_range = 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.
string staging_target_path = 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 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.
VolumeCapability volume_capability = 5;
// 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.
map<string, string> secrets = 6
[(csi_secret) = true, (alpha_field) = true];
}
message NodeExpandVolumeResponse {
// The capacity of the volume in bytes. This field is OPTIONAL.
int64 capacity_bytes = 1;
}