/** * 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 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 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 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 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 xn, 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 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 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 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 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 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 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 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 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 secrets = 5 [(csi_secret) = true]; } message ValidateVolumeCapabilitiesResponse { message Confirmed { // Volume context validated by the plugin. // This field is OPTIONAL. map 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 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 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 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 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 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 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 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 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 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 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 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 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; }