|
|
@@ -0,0 +1,1323 @@
|
|
|
+/**
|
|
|
+ * Licensed to the Apache Software Foundation (ASF) under one
|
|
|
+ * or more contributor license agreements. See the NOTICE file
|
|
|
+ * distributed with this work for additional information
|
|
|
+ * regarding copyright ownership. The ASF licenses this file
|
|
|
+ * to you under the Apache License, Version 2.0 (the
|
|
|
+ * "License"); you may not use this file except in compliance
|
|
|
+ * with the License. You may obtain a copy of the License at
|
|
|
+ *
|
|
|
+ * http://www.apache.org/licenses/LICENSE-2.0
|
|
|
+ *
|
|
|
+ * Unless required by applicable law or agreed to in writing, software
|
|
|
+ * distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
+ * See the License for the specific language governing permissions and
|
|
|
+ * limitations under the License.
|
|
|
+ */
|
|
|
+
|
|
|
+// 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.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;
|
|
|
+}
|
|
|
+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) {}
|
|
|
+}
|
|
|
+
|
|
|
+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;
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ 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;
|
|
|
+ }
|
|
|
+
|
|
|
+ // 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;
|
|
|
+ }
|
|
|
+
|
|
|
+ // 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 CO in CreateVolumeRequest. 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 CO in CreateVolumeRequest. 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 Entry {
|
|
|
+ Volume volume = 1;
|
|
|
+ }
|
|
|
+
|
|
|
+ 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 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;
|
|
|
+}
|
|
|
+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;
|
|
|
+ }
|
|
|
+
|
|
|
+ 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;
|
|
|
+}
|
|
|
+
|
|
|
+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];
|
|
|
+}
|
|
|
+
|
|
|
+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.
|
|
|
+ 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 CO in CreateVolumeRequest. 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.
|
|
|
+ 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.
|
|
|
+ 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.
|
|
|
+ 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 CO in CreateVolumeRequest. 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.
|
|
|
+ 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.
|
|
|
+ string volume_path = 2;
|
|
|
+}
|
|
|
+
|
|
|
+message NodeGetVolumeStatsResponse {
|
|
|
+ // This field is OPTIONAL.
|
|
|
+ repeated VolumeUsage usage = 1;
|
|
|
+}
|
|
|
+
|
|
|
+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;
|
|
|
+}
|
|
|
+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;
|
|
|
+ }
|
|
|
+
|
|
|
+ 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.
|
|
|
+ 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": "R2"}
|
|
|
+ // 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.
|
|
|
+ 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;
|
|
|
+}
|
|
|
+
|
|
|
+message NodeExpandVolumeResponse {
|
|
|
+ // The capacity of the volume in bytes. This field is OPTIONAL.
|
|
|
+ int64 capacity_bytes = 1;
|
|
|
+}
|
Márton Elek