csi.proto

////////
syntax = "proto3";
package csi;
////////
////////
service Identity {
  rpc GetSupportedVersions (GetSupportedVersionsRequest)
    returns (GetSupportedVersionsResponse) {}

  rpc GetPluginInfo(GetPluginInfoRequest)
    returns (GetPluginInfoResponse) {}
}

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) {}  
}

service Node {
  rpc NodePublishVolume (NodePublishVolumeRequest)
    returns (NodePublishVolumeResponse) {}

  rpc NodeUnpublishVolume (NodeUnpublishVolumeRequest)
    returns (NodeUnpublishVolumeResponse) {}

  rpc GetNodeID (GetNodeIDRequest)
    returns (GetNodeIDResponse) {}

  rpc ProbeNode (ProbeNodeRequest)
    returns (ProbeNodeResponse) {}

  rpc NodeGetCapabilities (NodeGetCapabilitiesRequest)
    returns (NodeGetCapabilitiesResponse) {}
}
////////
////////
message GetSupportedVersionsRequest {
}

message GetSupportedVersionsResponse {
  message Result {
    // All the CSI versions that the Plugin supports. This field is
    // REQUIRED.
    repeated Version supported_versions = 1;
  }

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}

// Specifies a version in Semantic Version 2.0 format.
// (http://semver.org/spec/v2.0.0.html)
message Version {
  uint32 major = 1;  // This field is REQUIRED.
  uint32 minor = 2;  // This field is REQUIRED.
  uint32 patch = 3;  // This field is REQUIRED.
}
////////
////////
message GetPluginInfoRequest {
  // The API version assumed by the CO. This is a REQUIRED field.
  Version version = 1;
}

message GetPluginInfoResponse {
  message Result {
    // 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;
  }

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}
////////
////////
message CreateVolumeRequest {
  // The API version assumed by the CO. This field is REQUIRED.
  Version version = 1;

  // The suggested name for the storage space. This field is REQUIRED.
  // It serves two purposes:
  // 1) Idempotency - This name is generated by the CO to achieve 
  //    idempotency. If `CreateVolume` fails, the volume may or may not
  //    be provisioned. In this case, the CO may call `CreateVolume`
  //    again, with the same name, to ensure the volume exists. 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.
  // 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.
  string name = 2;

  // This field is OPTIONAL. This allows the CO to specify the capacity
  // requirement of the volume to be provisioned. If not specified, the
  // Plugin MAY choose an implementation-defined capacity range.
  CapacityRange capacity_range = 3;

  // The capabilities that the provisioned volume MUST have: the Plugin
  // MUST provision a volume that could satisfy ALL of the
  // capabilities specified in this list. The Plugin MUST assume that
  // the CO MAY use the  provisioned volume later with ANY of the
  // capabilities specified in this list. This also enables the CO to do
  // early validation: if ANY of the specified volume capabilities are
  // not supported by the Plugin, the call SHALL fail. This field is
  // REQUIRED.
  repeated VolumeCapability volume_capabilities = 4;
    
  // Plugin specific parameters passed in as opaque key-value pairs.
  // This field is OPTIONAL. The Plugin is responsible for parsing and
  // validating these parameters. COs will treat these as opaque.
  map<string, string> parameters = 5;
}

message CreateVolumeResponse {
  message Result {
    // Contains all attributes of the newly created volume that are
    // relevant to the CO along with information required by the Plugin
    // to uniquely identifying the volume. This field is REQUIRED.
    VolumeInfo volume_info = 1;
  }

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}

// Specify a capability of a volume.
message VolumeCapability {
  message BlockVolume {
    // Intentionally empty, for now.
  }
  message MountVolume {
    // The filesystem type. This field is OPTIONAL.
    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.
    repeated string mount_flags = 2;    
  }

  // One of the following fields MUST be specified.
  oneof value {
    BlockVolume block = 1;
    MountVolume mount = 2;
  }
}

// The capacity of the storage space in bytes. To specify an exact size,
// `required_bytes` and `limit_bytes` can be set to the same value. At
// least one of the these fields MUST be specified.
message CapacityRange {
  // Volume must be at least this big. 
  uint64 required_bytes = 1;

  // Volume must not be bigger than this.
  uint64 limit_bytes = 2;
}

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

  // Contains information about how the volume can be accessed. This
  // field is REQUIRED.
  AccessMode access_mode = 2;

  // Contains identity information for the created volume. This field is  
  // REQUIRED. The identity information will be used by the CO in
  // subsequent calls to refer to the provisioned volume.
  VolumeID id = 4;

  // Metadata of the created volume. This field is OPTIONAL. If set, the
  // CO SHALL pass this information along with the `id` to subsequent
  // calls.
  VolumeMetadata metadata = 5;
}

// Specify how a volume can be accessed.
message AccessMode {
  enum Mode {
    UNKNOWN = 0;
    
    // Can be published as read/write at one node at a time.
    SINGLE_NODE_WRITER = 1;

    // Can be published as readonly at one node at a 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;
}

// The identity of the volume.
message VolumeID {
  // The identity of the provisioned volume specified by the Plugin in
  // the form of key-value pairs. This field is REQUIRED. Given this
  // information will be passed around by the CO, it is RECOMMENDED that
  // each Plugin keeps this information as small as possible.
  map<string, string> values = 1;
}

// The metadata information about the volume.
message VolumeMetadata {
  // The metadata information about the provisioned volume specified by
  // the Plugin in the form of key-value pairs. This field is OPTIONAL.
  // This field MAY contain sensitive information. Therefore, the CO
  // MUST NOT leak this information to untrusted entities. Given this
  // information will be passed around by the CO, it is RECOMMENDED that
  // each Plugin keeps this information as small as possible.
  map<string, string> values = 1;
}
////////
////////
message DeleteVolumeRequest {
  // The API version assumed by the CO. This field is REQUIRED.
  Version version = 1;

  // The ID of the volume to be deprovisioned. This field is REQUIRED.
  VolumeID volume_id = 2;

  // The metadata of the volume to be deprovisioned. This field is
  // OPTIONAL.
  VolumeMetadata volume_metadata = 3;
}

message DeleteVolumeResponse {
  message Result {}

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}
////////
////////
message ControllerPublishVolumeRequest {
  // The API version assumed by the CO. This field is REQUIRED.
  Version version = 1;

  // The ID of the volume to be used on a node. This field is REQUIRED.
  VolumeID volume_id = 2;
  
  // The metadata of the volume to be used on a node. This field is
  // OPTIONAL.
  VolumeMetadata volume_metadata = 3;

  // The ID of the node. This field is OPTIONAL. The CO SHALL set (or
  // clear) this field to match the `NodeID` returned by `GetNodeID`.
  // `GetNodeID` is allowed to omit `NodeID` from a successful `Result`;
  // in such cases the CO SHALL NOT specify this field.
  NodeID node_id = 4;

  // Whether to publish the volume in readonly mode. This field is
  // REQUIRED.
  bool readonly = 5;
}

message ControllerPublishVolumeResponse {
  message Result {
    // The SP specific information that will be passed to the Plugin in
    // the subsequent `NodePublishVolume` call for the given volume.
    // This information is opaque to the CO. This field is OPTIONAL.
    PublishVolumeInfo publish_volume_info = 1;
  }

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}

message NodeID {
  // Information about a node in the form of key-value pairs. This
  // information is opaque to the CO. Given this information will be
  // passed around by the CO, it is RECOMMENDED that each Plugin keeps
  // this information as small as possible. This field is REQUIRED.
  map<string, string> values = 1;
}

message PublishVolumeInfo {
  // Information returned by the Plugin in `ControllerPublishVolume`
  // call. It is in the form of key-value pairs, and is opaque to the
  // CO. Given this information will be passed around by the CO, it is
  // RECOMMENDED that each Plugin keeps this information as small as
  // possible. This field is OPTIONAL.
  map<string, string> values = 1;
}
////////
////////
message ControllerUnpublishVolumeRequest {
  // The API version assumed by the CO. This field is REQUIRED.
  Version version = 1;

  // The ID of the volume. This field is REQUIRED.
  VolumeID volume_id = 2;

  // The metadata of the volume. This field is OPTIONAL.
  VolumeMetadata volume_metadata = 3;

  // The ID of the node. This field is OPTIONAL. The CO SHALL set (or
  // clear) this field to match the `NodeID` returned by `GetNodeID`.
  // `GetNodeID` is allowed to omit `NodeID` from a successful `Result`;
  // in such cases the CO SHALL NOT specify this field.
  //
  // If `GetNodeID` does not omit `NodeID` from a successful `Result`,
  // the CO MAY omit this field as well, indicating that it does not
  // know which node the volume was previously used. The Plugin SHOULD
  // return an Error if this is not supported.
  NodeID node_id = 4;
}

message ControllerUnpublishVolumeResponse {
  message Result {}

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}
////////
////////
message ValidateVolumeCapabilitiesRequest {
  // The API version assumed by the CO. This is a REQUIRED field.
  Version version = 1;

  // The information about the volume to check. This is a REQUIRED
  // field. 
  VolumeInfo volume_info = 2;

  // The capabilities that the CO wants to check for the volume. This
  // call SHALL return “supported” only if all the volume capabilities
  // specified below are supported. This field is REQUIRED.
  repeated VolumeCapability volume_capabilities = 3;
}

message ValidateVolumeCapabilitiesResponse {
  message Result {
    // True if the Plugin supports the specified capabilities for the
    // given volume. This field is REQUIRED.
    bool supported = 1;

    // Message to the CO if `supported` above is false. This field is
    // OPTIONAL.
    string message = 2;
  }

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}
////////
////////
message ListVolumesRequest {
  // The API version assumed by the CO. This field is REQUIRED.
  Version version = 1;

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

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

message ListVolumesResponse {
  message Result {
    message Entry {
      VolumeInfo volume_info = 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.
    string next_token = 2;
  }

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}
////////
////////
message GetCapacityRequest {
  // The API version assumed by the CO. This is a REQUIRED field.
  Version version = 1;
}

message GetCapacityResponse {
  message Result {
    // The total capacity (available + used) of the storage pool from
    // which the controller provisions volumes. This is a REQUIRED
    // field.
    uint64 total_capacity = 1;
  }

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}
////////
////////
message ControllerGetCapabilitiesRequest {
  // The API version assumed by the CO. This is a REQUIRED field.
  Version version = 1;
}

message ControllerGetCapabilitiesResponse {
  message Result {
    // All the capabilities that the controller service supports. This
    // field is OPTIONAL.
    repeated ControllerServiceCapability capabilities = 2;
  }

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}

// 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; 
    }

    Type type = 1;
  }
  
  oneof type {
    // RPC that the controller supports.
    RPC rpc = 1;
    
    // Volume capability the Controller Plugin supports. An SP SHOULD
    // avoid setting different volume capability for Controller and Node
    // Plugins if possible. If this happens during the upgrade of the
    // Plugins, the behavior is UNDEFINED. 
    VolumeCapability volume_capability = 2;
  }
}
////////
////////
message NodePublishVolumeRequest {
  // The API version assumed by the CO. This is a REQUIRED field.
  Version version = 1;

  // The ID of the volume to publish. This field is REQUIRED.
  VolumeID volume_id = 2;

  // The metadata of the volume to publish. This field is OPTIONAL.
  VolumeMetadata volume_metadata = 3;

  // 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.
  PublishVolumeInfo publish_volume_info = 4;

  // The path to which the volume will be published. It MUST be an
  // absolute path in the root filesystem of the process serving this
  // request. This is a REQUIRED field.
  string target_path = 5;

  // The capability of the volume to be published. This is a REQUIRED
  // field.
  VolumeCapability volume_capability = 6;

  // Whether to publish the volume in readonly mode. This field is
  // REQUIRED.
  bool readonly = 7;
}

message NodePublishVolumeResponse {
  message Result {}

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}
////////
////////
message NodeUnpublishVolumeRequest {
  // The API version assumed by the CO. This is a REQUIRED field.
  Version version = 1;

  // The ID of the volume. This field is REQUIRED.
  VolumeID volume_id = 2;

  // The metadata of the volume. This field is OPTIONAL.
  VolumeMetadata volume_metadata = 3;

  // The path at which the volume was published. It MUST be an absolute 
  // path in the root filesystem of the process serving this request.
  // This is a REQUIRED field.
  string target_path = 4;
}

message NodeUnpublishVolumeResponse {
  message Result {}

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}
////////
////////
message GetNodeIDRequest {
  // The API version assumed by the CO. This is a REQUIRED field.
  Version version = 1;
}

message GetNodeIDResponse {
  message Result {
    // The ID of the node which SHALL be used by CO in 
    // `ControllerPublishVolume`. This is an OPTIONAL field. If unset,
    // the CO SHALL leave the `node_id` field unset in
    // `ControllerPublishVolume`. 
    NodeID node_id = 1;
  }

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}
////////
////////
message ProbeNodeRequest {
  // The API version assumed by the CO. This is a REQUIRED field.
  Version version = 1;
}

message ProbeNodeResponse {
  message Result {}

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}
////////
////////
message NodeGetCapabilitiesRequest {
  // The API version assumed by the CO. This is a REQUIRED field.
  Version version = 1;
}

message NodeGetCapabilitiesResponse {
  message Result {
    // All the capabilities that the node service supports. This field
    // is OPTIONAL.
    repeated NodeServiceCapability capabilities = 2;
  }

  // One of the following fields MUST be specified.
  oneof reply {
    Result result = 1;
    Error error = 2;
  }
}

// Specifies a capability of the node service.
message NodeServiceCapability {
  message RPC {
    enum Type {
      UNKNOWN = 0;
    }

    Type type = 1;
  }
  
  oneof type {
    // RPC that the controller supports.
    RPC rpc = 1;
    
    // Volume capability the Node Plugin supports. An SP SHOULD avoid
    // setting different volume capability for Controller and Node
    // Plugins if possible. If this happens during the upgrade of the
    // Plugins, the behavior is UNDEFINED. 
    VolumeCapability volume_capability = 2;
  }
}
////////
////////
message Error {
  // General Error that MAY be returned by any RPC.
  message GeneralError {
    enum GeneralErrorCode {
      // Default value for backwards compatibility. SHOULD NOT be
      // returned by Plugins. However, if a Plugin returns a
      // `GeneralErrorCode` code that an older CSI client is not aware
      // of, the client will see this code (the default fallback).
      //
      // Recovery behavior: Caller SHOULD consider updating CSI client
      // to match Plugin CSI version.
      UNKNOWN = 0;

      // Indicates that an undefined error occurred. More human-readable
      // information MAY be provided in the `error_description` field.
      // The `caller_must_not_retry` field MUST be set appropriately by
      // the Plugin to provide callers expected recovery behavior.
      //
      // Recovery behavior: Caller MAY retry (with exponential backoff),
      // if `caller_must_not_retry` is set to false. Otherwise, the
      // caller MUST not reissue the same request.
      UNDEFINED = 1;

      // Indicates that the version specified in the request is not
      // supported by the Plugin. The `caller_must_not_retry` field MUST
      // be set to true.
      //
      // Recovery behavior: Caller MUST NOT retry; caller SHOULD call
      // `GetSupportedVersions` to discover which CSI versions the Plugin
      // supports.
      UNSUPPORTED_REQUEST_VERSION = 2;

      // Indicates that a required field is missing from the request.
      // More human-readable information MAY be provided in the
      // `error_description` field. The `caller_must_not_retry` field
      // MUST be set to true.
      //
      // Recovery behavior: Caller MUST fix the request by adding the
      // missing required field before retrying.
      MISSING_REQUIRED_FIELD = 3;
    }

    // Machine parsable error code.
    GeneralErrorCode error_code = 1;

    // When set to true, `caller_must_not_retry` indicates that the
    // caller MUST not retry the same call again. This MAY be because
    // the call is deemed invalid by the Plugin and no amount of retries
    // will cause it to succeed. If this value is false, the caller MAY
    // reissue the same call, but SHOULD implement exponential backoff
    // on retires.
    bool caller_must_not_retry = 2;

    // Human readable description of error, possibly with additional
    // information. This string MAY be surfaced by CO to end users.
    string error_description = 3;
  }

  // `CreateVolume` specific error.
  message CreateVolumeError {
    enum CreateVolumeErrorCode {
      // Default value for backwards compatibility. SHOULD NOT be
      // returned by Plugins. However, if a Plugin returns a
      // `CreateVolumeErrorCode` code that an older CSI client is not
      // aware of, the client will see this code (the default fallback).
      //
      // Recovery behavior: Caller SHOULD consider updating CSI client
      // to match Plugin CSI version.
      UNKNOWN = 0;

      // Indicates that the call is either not implemented by the Plugin
      // or disabled in the Plugin’s current mode of operation.
      //
      // Recovery behavior: Caller MUST not retry; caller MAY call
      // `ControllerGetCapabilities` or `NodeGetCapabilities` to discover
      // Plugin capabilities.
      CALL_NOT_IMPLEMENTED = 1;

      // Indicates that there is a already an operation pending for the
      // specified volume. In general the Cluster Orchestrator (CO) is
      // responsible for ensuring that there is no more than one call
      // “in-flight” per volume at a given time. However, in some
      // circumstances, the CO MAY lose state (for example when the CO
      // crashes and restarts), and MAY issue multiple calls
      // simultaneously for the same volume. The Plugin, SHOULD handle
      // this as gracefully as possible, and MAY return this error code
      // to reject secondary calls.
      //
      // Recovery behavior: Caller SHOULD ensure that there are no other
      // calls pending for the specified volume, and then retry with
      // exponential back off.
      OPERATION_PENDING_FOR_VOLUME = 2;

      // Indicates that the specified volume name is not allowed by the
      // Plugin. More human-readable information MAY be provided in the
      // `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the name before retrying.
      INVALID_VOLUME_NAME = 3;

      // Indicates that the capacity range is not allowed by the Plugin.
      // More human-readable information MAY be provided in the
      // `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the capacity range before //
      // retrying.
      UNSUPPORTED_CAPACITY_RANGE = 4;

      // Indicates that a volume corresponding to the specified volume
      // name already exists.
      //
      // Recovery behavior: Caller MAY assume the `CreateVolume`
      // call succeeded.
      VOLUME_ALREADY_EXISTS = 5;

      // Indicates that a key in the opaque key/value parameters field
      // is not supported by the Plugin. More human-readable information
      // MAY be provided in the `error_description` field. This MAY
      // occur, for example, due to caller error, Plugin version skew, etc.
      //
      // Recovery behavior: Caller MUST remove the unsupported key/value
      // pair from the list of parameters before retrying.
      UNSUPPORTED_PARAMETER_KEY = 6;

      // Indicates that a value in one of the opaque key/value pairs
      // parameter contains invalid data. More human-readable
      // information (such as the corresponding key) MAY be provided in
      // the `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the invalid value before
      // retrying.
      INVALID_PARAMETER_VALUE = 7;
    }
    
    // Machine parsable error code.
    CreateVolumeErrorCode error_code = 1;

    // Human readable description of error, possibly with additional
    // information. This string maybe surfaced by CO to end users.
    string error_description = 2;
  }

  // `DeleteVolume` specific error.
  message DeleteVolumeError {
    enum DeleteVolumeErrorCode {
      // Default value for backwards compatibility. SHOULD NOT be
      // returned by Plugins. However, if a Plugin returns a
      // `DeleteVolumeErrorCode` code that an older CSI client is not
      // aware of, the client will see this code (the default fallback).
      //
      // Recovery behavior: Caller SHOULD consider updating CSI client
      // to match Plugin CSI version.
      UNKNOWN = 0;

      // Indicates that the call is either not implemented by the Plugin
      // or disabled in the Plugin’s current mode of operation.
      //
      // Recovery behavior: Caller MUST not retry; caller MAY call
      // `ControllerGetCapabilities` or `NodeGetCapabilities` to
      // discover Plugin capabilities.
      CALL_NOT_IMPLEMENTED = 1;

      // Indicates that there is a already an operation pending for the
      // specified volume. In general the Cluster Orchestrator (CO) is
      // responsible for ensuring that there is no more than one call
      // “in-flight” per volume at a given time. However, in some
      // circumstances, the CO MAY lose state (for example when the CO
      // crashes and restarts), and MAY issue multiple calls
      // simultaneously for the same volume. The Plugin, SHOULD handle
      // this as gracefully as possible, and MAY return this error code
      // to reject secondary calls.
      //
      // Recovery behavior: Caller SHOULD ensure that there are no other
      // calls pending for the specified volume, and then retry with
      // exponential back off.
      OPERATION_PENDING_FOR_VOLUME = 2;

      // Indicates that the specified `VolumeID` is not allowed or
      // understood by the Plugin. More human-readable information MAY
      // be provided in the `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the `VolumeID` before
      // retrying.
      INVALID_VOLUME_ID = 3;

      // Indicates that the specified `VolumeMetadata` is not allowed or
      // understood by the Plugin. More human-readable information MAY
      // be provided in the `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the `VolumeMetadata` before
      // retrying.
      INVALID_VOLUME_METADATA = 4;

      // Indicates that a volume corresponding to the specified
      // `VolumeID` does not exist.
      //
      // Recovery behavior: Caller SHOULD assume the `DeleteVolume` call
      // succeeded.
      VOLUME_DOES_NOT_EXIST = 5;
    }
    
    // Machine parsable error code.
    DeleteVolumeErrorCode error_code = 1;

    // Human readable description of error, possibly with additional
    // information. This string maybe surfaced by CO to end users.
    string error_description = 2;
  }

  // `ControllerPublishVolume` specific error.
  message ControllerPublishVolumeError {
    enum ControllerPublishVolumeErrorCode {
      // Default value for backwards compatibility. SHOULD NOT be
      // returned by Plugins. However, if a Plugin returns a
      // `ControllerPublishVolumeErrorCode` code that an older CSI
      // client is not aware of, the client will see this code (the
      // default fallback).
      //
      // Recovery behavior: Caller SHOULD consider updating CSI client
      // to match Plugin CSI version.
      UNKNOWN = 0;

      // Indicates that the call is either not implemented by the Plugin
      // or disabled in the Plugin’s current mode of operation.
      //
      // Recovery behavior: Caller MUST not retry; caller MAY call
      // `ControllerGetCapabilities` or `NodeGetCapabilities` to discover
      // Plugin capabilities.
      CALL_NOT_IMPLEMENTED = 1;

      // Indicates that there is a already an operation pending for the
      // specified volume. In general the Cluster Orchestrator (CO) is
      // responsible for ensuring that there is no more than one call
      // “in-flight” per volume at a given time. However, in some
      // circumstances, the CO MAY lose state (for example when the CO
      // crashes and restarts), and MAY issue multiple calls
      // simultaneously for the same volume. The Plugin, SHOULD handle
      // this as gracefully as possible, and MAY return this error code
      // to reject secondary calls.
      //
      // Recovery behavior: Caller SHOULD ensure that there are no other
      // calls pending for the specified volume, and then retry with
      // exponential back off.
      OPERATION_PENDING_FOR_VOLUME = 2;

      // Indicates that the specified `VolumeID` is not allowed or
      // understood by the Plugin. More human-readable information MAY
      // be provided in the `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the `VolumeID` before
      // retrying.
      INVALID_VOLUME_ID = 3;

      // Indicates that the specified `VolumeMetadata` is not allowed or
      // understood by the Plugin. More human-readable information MAY
      // be provided in the `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the `VolumeMetadata` before
      // retrying.
      INVALID_VOLUME_METADATA = 4;

      // Indicates that a volume corresponding to the specified
      // `VolumeID` does not exist.
      //
      // Recovery behavior: Caller SHOULD verify that the `VolumeID` is
      // correct and that the volume is accessible and has not been
      // deleted before retrying with exponential back off.
      VOLUME_DOES_NOT_EXIST = 5;

      // Indicates that a volume corresponding to the specified
      // `VolumeID` is already attached to another node and does not
      // support multi-node attach. If this error code is returned, the
      // Plugin MUST also specify the `node_id` of the node the volume
      // is already attached to.
      //
      // Recovery behavior: Caller MAY use the provided `node_ids`
      // information to detach the volume from the other node. Caller
      // SHOULD ensure the specified volume is not attached to any other
      // node before retrying with exponential back off.
      VOLUME_ALREADY_PUBLISHED = 6;

      // Indicates that a node corresponding to the specified `NodeID`
      // does not exist.
      //
      // Recovery behavior: Caller SHOULD verify that the `NodeID` is
      // correct and that the node is available and has not been
      // terminated or deleted before retrying with exponential backoff.
      NODE_DOES_NOT_EXIST = 7;

      // Indicates that a volume corresponding to the specified
      // `VolumeID` is already attached to the maximum supported number
      // of nodes and therefore this operation can not be completed
      // until the volume is detached from at least one of the existing
      // nodes. When this error code is returned, the Plugin MUST also
      // specify the `NodeId` of all the nodes the volume is attached
      // to.
      //
      // Recovery behavior: Caller MAY use the provided `node_ids`
      // information to detach the volume from one other node before
      // retrying with exponential backoff.
      MAX_ATTACHED_NODES = 8;

      // Indicates that the specified `NodeID` is not allowed or
      // understood by the Plugin, or the Plugin does not support the
      // operation without a `NodeID`. More human-readable information
      // MAY be provided in the `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the `NodeID` before
      // retrying.
      INVALID_NODE_ID = 9;
    }
    
    // Machine parsable error code.
    ControllerPublishVolumeErrorCode error_code = 1;

    // Human readable description of error, possibly with additional
    // information. This string maybe surfaced by CO to end users.
    string error_description = 2;

    // On `VOLUME_ALREADY_ATTACHED` and `MAX_ATTACHED_NODES` errors,
    // this field contains the node(s) that the specified volume is
    // already attached to.
    repeated NodeID node_ids = 3;
  }

  // `ControllerUnpublishVolume` specific error.
  message ControllerUnpublishVolumeError {
    enum ControllerUnpublishVolumeErrorCode {
      // Default value for backwards compatibility. SHOULD NOT be
      // returned by Plugins. However, if a Plugin returns a
      // `ControllerUnpublishVolumeErrorCode` code that an older CSI
      // client is not aware of, the client will see this code (the
      // default fallback).
      //
      // Recovery behavior: Caller SHOULD consider updating CSI client
      // to match Plugin CSI version.
      UNKNOWN = 0;

      // Indicates that the call is either not implemented by the Plugin
      // or disabled in the Plugin’s current mode of operation.
      //
      // Recovery behavior: Caller MUST not retry; caller MAY call
      // `ControllerGetCapabilities` or `NodeGetCapabilities` to
      // discover Plugin capabilities.
      CALL_NOT_IMPLEMENTED = 1;

      // Indicates that there is a already an operation pending for the
      // specified volume. In general the Cluster Orchestrator (CO) is
      // responsible for ensuring that there is no more than one call
      // “in-flight” per volume at a given time. However, in some
      // circumstances, the CO MAY lose state (for example when the CO
      // crashes and restarts), and MAY issue multiple calls
      // simultaneously for the same volume. The Plugin, SHOULD handle
      // this as gracefully as possible, and MAY return this error code
      // to reject secondary calls.
      //
      // Recovery behavior: Caller SHOULD ensure that there are no other
      // calls pending for the specified volume, and then retry with
      // exponential back off.
      OPERATION_PENDING_FOR_VOLUME = 2;

      // Indicates that the specified `VolumeID` is not allowed or
      // understood by the Plugin. More human-readable information MAY
      // be provided in the `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the `VolumeID` before
      // retrying.
      INVALID_VOLUME_ID = 3;

      // Indicates that the specified `VolumeMetadata` is not allowed or
      // understood by the Plugin. More human-readable information MAY
      // be provided in the `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the `VolumeMetadata` before
      // retrying.
      INVALID_VOLUME_METADATA = 4;

      // Indicates that a volume corresponding to the specified
      // `VolumeID` does not exist.
      //
      // Recovery behavior: Caller SHOULD verify that the `VolumeID` is
      // correct and that the volume is accessible and has not been
      // deleted before retrying with exponential back off.
      VOLUME_DOES_NOT_EXIST = 5;

      // Indicates that a node corresponding to the specified `NodeID`
      // does not exist.
      //
      // Recovery behavior: Caller SHOULD verify that the `NodeID` is
      // correct and that the node is available and has not been
      // terminated or deleted before retrying.
      NODE_DOES_NOT_EXIST = 6;

      // Indicates that the specified `NodeID` is not allowed or
      // understood by the Plugin. More human-readable information MAY
      // be provided in the `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the `NodeID` before
      // retrying.
      INVALID_NODE_ID = 7;

      VOLUME_NOT_ATTACHED_TO_SPECIFIED_NODE = 8;

      // Indicates that the Plugin does not support the operation
      // without a `NodeID`.
      //
      // Recovery behavior: Caller MUST specify the `NodeID` before
      // retrying.
      NODE_ID_REQUIRED = 9;
    }
    
    ControllerUnpublishVolumeErrorCode error_code = 1;
    string error_description = 2;
  }

  // `ValidateVolumeCapabilities` specific error.
  message ValidateVolumeCapabilitiesError {
    enum ValidateVolumeCapabilitiesErrorCode {
      // Default value for backwards compatibility. SHOULD NOT be
      // returned by Plugins. However, if a Plugin returns a
      // `ValidateVolumeCapabilitiesErrorCode` code that an older CSI
      // client is not aware of, the client will see this code (the
      // default fallback).
      //
      // Recovery behavior: Caller SHOULD consider updating CSI client
      // to match Plugin CSI version.
      UNKNOWN = 0;

      // Indicates that a volume corresponding to the specified
      // `VolumeInfo` does not exist.
      //
      // Recovery behavior: Caller SHOULD verify that the `VolumeInfo`
      // is correct and that the volume is accessable and has not been
      // deleted before retrying.
      VOLUME_DOES_NOT_EXIST = 1;

      UNSUPPORTED_MOUNT_FLAGS = 2;
      UNSUPPORTED_VOLUME_TYPE = 3;
      UNSUPPORTED_FS_TYPE = 4;

      // Indicates that the specified `VolumeInfo` is not allowed or
      // understood by the Plugin. More human-readable information MAY
      // be provided in the `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the `VolumeInfo` before
      // retrying.
      INVALID_VOLUME_INFO = 5;
    }
    
    ValidateVolumeCapabilitiesErrorCode error_code = 1;
    string error_description = 2;
  }

  // `NodePublishVolume` specific error.
  message NodePublishVolumeError {
    enum NodePublishVolumeErrorCode {
      // Default value for backwards compatibility. SHOULD NOT be
      // returned by Plugins. However, if a Plugin returns a
      // `NodePublishVolumeErrorCode` code that an older CSI
      // client is not aware of, the client will see this code (the
      // default fallback).
      //
      // Recovery behavior: Caller SHOULD consider updating CSI client
      // to match Plugin CSI version.
      UNKNOWN = 0;

      // Indicates that there is a already an operation pending for the
      // specified volume. In general the Cluster Orchestrator (CO) is
      // responsible for ensuring that there is no more than one call
      // “in-flight” per volume at a given time. However, in some
      // circumstances, the CO MAY lose state (for example when the CO
      // crashes and restarts), and MAY issue multiple calls
      // simultaneously for the same volume. The Plugin, SHOULD handle
      // this as gracefully as possible, and MAY return this error code
      // to reject secondary calls.
      //
      // Recovery behavior: Caller SHOULD ensure that there are no other
      // calls pending for the specified volume, and then retry with
      // exponential back off.
      OPERATION_PENDING_FOR_VOLUME = 1;

      // Indicates that a volume corresponding to the specified
      // `VolumeID` does not exist.
      //
      // Recovery behavior: Caller SHOULD verify that the `VolumeID` is
      // correct and that the volume is accessible and has not been
      // deleted before retrying with exponential back off.
      VOLUME_DOES_NOT_EXIST = 2;

      UNSUPPORTED_MOUNT_FLAGS = 3;
      UNSUPPORTED_VOLUME_TYPE = 4;
      UNSUPPORTED_FS_TYPE = 5;
      MOUNT_ERROR = 6;

      // Indicates that the specified `VolumeID` is not allowed or
      // understood by the Plugin. More human-readable information MAY
      // be provided in the `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the `VolumeID` before
      // retrying.
      INVALID_VOLUME_ID = 7;
    }
    
    NodePublishVolumeErrorCode error_code = 1;
    string error_description = 2;
  }

  // `NodeUnpublishVolume` specific error.
  message NodeUnpublishVolumeError {
    enum NodeUnpublishVolumeErrorCode {
      // Default value for backwards compatibility. SHOULD NOT be
      // returned by Plugins. However, if a Plugin returns a
      // `NodeUnpublishVolumeErrorCode` code that an older CSI
      // client is not aware of, the client will see this code (the
      // default fallback).
      //
      // Recovery behavior: Caller SHOULD consider updating CSI client
      // to match Plugin CSI version.
      UNKNOWN = 0;

      // Indicates that there is a already an operation pending for the
      // specified volume. In general the Cluster Orchestrator (CO) is
      // responsible for ensuring that there is no more than one call
      // “in-flight” per volume at a given time. However, in some
      // circumstances, the CO MAY lose state (for example when the CO
      // crashes and restarts), and MAY issue multiple calls
      // simultaneously for the same volume. The Plugin, SHOULD handle
      // this as gracefully as possible, and MAY return this error code
      // to reject secondary calls.
      //
      // Recovery behavior: Caller SHOULD ensure that there are no other
      // calls pending for the specified volume, and then retry with
      // exponential back off.
      OPERATION_PENDING_FOR_VOLUME = 1;

      // Indicates that a volume corresponding to the specified
      // `VolumeID` does not exist.
      //
      // Recovery behavior: Caller SHOULD verify that the `VolumeID` is
      // correct and that the volume is accessible and has not been
      // deleted before retrying with exponential back off.
      VOLUME_DOES_NOT_EXIST = 2;

      UNMOUNT_ERROR = 3;

      // Indicates that the specified `VolumeID` is not allowed or
      // understood by the Plugin. More human-readable information MAY
      // be provided in the `error_description` field.
      //
      // Recovery behavior: Caller MUST fix the `VolumeID` before
      // retrying.
      INVALID_VOLUME_ID = 4;
    }
    
    NodeUnpublishVolumeErrorCode error_code = 1;
    string error_description = 2;
  }

  // `ProbeNode` specific error.
  message ProbeNodeError {
    enum ProbeNodeErrorCode {
      // Default value for backwards compatibility. SHOULD NOT be
      // returned by Plugins. However, if a Plugin returns a
      // `ProbeNodeErrorCode` code that an older CSI
      // client is not aware of, the client will see this code (the
      // default fallback).
      //
      // Recovery behavior: Caller SHOULD consider updating CSI client
      // to match Plugin CSI version.
      UNKNOWN = 0;

      BAD_PLUGIN_CONFIG = 1;
      MISSING_REQUIRED_HOST_DEPENDENCY = 2;
    }
    
    ProbeNodeErrorCode error_code = 1;
    string error_description = 2;
  }

  // `GetNodeID` specific error.
  message GetNodeIDError {
    enum GetNodeIDErrorCode {
      // Default value for backwards compatibility. SHOULD NOT be
      // returned by Plugins. However, if a Plugin returns a
      // `GetNodeIDErrorCode` code that an older CSI client is not aware
      // of, the client will see this code (the default fallback).
      //
      // Recovery behavior: Caller SHOULD consider updating CSI client
      // to match Plugin CSI version.
      UNKNOWN = 0;

      BAD_PLUGIN_CONFIG = 1;
      MISSING_REQUIRED_HOST_DEPENDENCY = 2;
    }
    
    GetNodeIDErrorCode error_code = 1;
    string error_description = 2;
  }

  // One of the following fields MUST be specified.
  oneof value {
    GeneralError general_error = 1;

    CreateVolumeError create_volume_error = 2;
    DeleteVolumeError delete_volume_error = 3;
    ControllerPublishVolumeError controller_publish_volume_error = 4;
    ControllerUnpublishVolumeError controller_unpublish_volume_error = 5;
    ValidateVolumeCapabilitiesError validate_volume_capabilities_error = 6;

    NodePublishVolumeError node_publish_volume_error = 7;
    NodeUnpublishVolumeError node_unpublish_volume_error = 8;
    ProbeNodeError probe_node_error = 9;
    GetNodeIDError get_node_id_error = 10;
  }
}
////////