Spec ModifyVolume for QoS kep-3751

Author: sunnylovestiramisu

spec.md

@@ -381,6 +381,11 @@ service Controller {
     returns (ControllerGetVolumeResponse) {
         option (alpha_method) = true;
     }
+
+  rpc ControllerModifyVolume (ControllerModifyVolumeRequest)
+    returns (ControllerModifyVolumeResponse) {
+        option (alpha_method) = true;
+    }
 }
 
 service GroupController {
@@ -843,6 +848,22 @@ message CreateVolumeRequest {
   // VOLUME_ACCESSIBILITY_CONSTRAINTS plugin capability, the SP MAY
   // choose where the provisioned volume is accessible from.
   TopologyRequirement accessibility_requirements = 7;
+
+  // This field is OPTIONAL. This allows the CO to specify the iops
+  // requirement of the volume to be provisioned. If not specified, the
+  // Plugin MAY choose an implementation-defined iops 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.
+  int64 iops = 8;
+
+  // This field is OPTIONAL. This allows the CO to specify the throughput
+  // requirement of the volume to be provisioned. If not specified, the
+  // Plugin MAY choose an implementation-defined throughput 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.
+  int64 throughput = 9;
 }
 
 // Specifies what source the volume will be created from. One of the
@@ -1223,6 +1244,8 @@ The CO MUST implement the specified error recovery behavior when it encounters t
 | Volume already exists but is incompatible | 6 ALREADY_EXISTS | Indicates that a volume corresponding to the specified volume `name` already exists but is incompatible with the specified `capacity_range`, `volume_capabilities`, `parameters`, `accessibility_requirements` or `volume_content_source`. | Caller MUST fix the arguments or use a different `name` before retrying. |
 | Unable to provision in `accessible_topology` | 8 RESOURCE_EXHAUSTED | Indicates that although the `accessible_topology` field is valid, a new volume can not be provisioned with the specified topology constraints. More human-readable information MAY be provided in the gRPC `status.message` field. | Caller MUST ensure that whatever is preventing volumes from being provisioned in the specified location (e.g. quota issues) is addressed before retrying with exponential backoff. |
 | Unsupported `capacity_range` | 11 OUT_OF_RANGE | Indicates that the capacity range is not allowed by the Plugin, for example when trying to create a volume smaller than the source snapshot or the Plugin does not support creating volumes larger than the source snapshot or source volume. More human-readable information MAY be provided in the gRPC `status.message` field. | Caller MUST fix the capacity range before retrying. |
+| Unsupported `iops_range` | 11 OUT_OF_RANGE | Indicates that the iops range is not allowed by the Plugin. More human-readable information MAY be provided in the gRPC `status.message` field. | Caller MUST fix the iops range before retrying. |
+| Unsupported `throughput_range` | 11 OUT_OF_RANGE | Indicates that the throughput range is not allowed by the Plugin. More human-readable information MAY be provided in the gRPC `status.message` field. | Caller MUST fix the throughput range before retrying. |
 
 
 #### `DeleteVolume`
@@ -1617,6 +1640,62 @@ The CO MUST implement the specified error recovery behavior when it encounters t
 |-----------|-----------|-------------|-------------------|
 | Volume does not exist | 5 NOT_FOUND | Indicates that a volume corresponding to the specified `volume_id` does not exist. | Caller MUST verify that the `volume_id` is correct and that the volume is accessible and has not been deleted before retrying with exponential back off. |
 
+
+#### `ModifyVolume`
+
+A Controller plugin SHALL implement this RPC call. This RPC allows the CO to change key QoS parameters(iops and throughput) of a volume. 
+
+This operation MUST be idempotent. The requested  iops and  throughput values can be greater than or less than the current values. 
+
+
+```protobuf
+message ModifyVolumeRequest {
+  // Contains identity information for the existing volume.
+  // This field is REQUIRED.
+  int64 volume_id = 1
+
+  // This field is OPTIONAL.This allows the CO to specify the
+  // iops of the volume to be updated to. The unit is IO per
+  // second per volume. 
+  // If specified it MUST always be honored.
+  // A value of 0 is equal to an unspecified field value.
+  int64 iops = 2
+
+  // This field is OPTIONAL.This allows the CO to specify the
+  // throughput of the volume to be updated to. The unit is Mib per
+  // second per volume. 
+  // If specified it MUST always be honored.
+  // A value of 0 is equal to an unspecified field value.
+  string throughput = 3
+}
+
+message ModifyVolumeResponse {
+  // The iops of the volume is set. This field is OPTIONAL.
+  google.protobuf.Int64Value iops = 1
+  // The throughput of the volume is set. This field is OPTIONAL.
+  google.protobuf.Int64Value throughput = 2
+}
+```
+
+##### Definition of Iops and Throughput
+
+The iops and throughput in this API is referring to read/write iops and read/write throughput. The unit is IO per second per volume for iops, and Mib per second per volume for throughput. The parameters SHOULD be independently configured from capacity.
+
+The SP MUST reserve the requested iops and throughput for the volume. This means that the workload is guaranteed to the requested resources and will not be throttled below the request. This is also the maximum iops/throughput the user can reach in their workload. 
+
+In physically-limited environments, updating performance parameters independently from capacity may result in underutilized resources. The SP MAY enforce limits on the allowed values. If the requested iops, throughput and capacity are not compatible with each other, the SP MUST return the OUT_OF_RANGE error code.
+
+
+##### ModifyVolume Errors
+
+| Condition | gRPC Code | Description | Recovery Behavior |
+|-----------|-----------|-------------|-------------------|
+| Exceeds capabilities | 3 INVALID_ARGUMENT | Indicates that the CO has specified capabilities not supported by the volume. | Caller MAY verify volume capabilities by calling ValidateVolumeCapabilities and retry with matching capabilities. |
+| Volume does not exist | 5 NOT FOUND | Indicates that a volume corresponding to the specified volume_id does not exist. | Caller MUST verify that the volume_id is correct and that the volume is accessible and has not been deleted before retrying with exponential back off. |
+| Volume in use | 9 FAILED_PRECONDITION | Indicates that the volume corresponding to the specified `volume_id` could not be updated because it is currently published on a node but the plugin does not have ONLINE modification capability. | Caller SHOULD ensure that volume is not published and retry with exponential back off. |
+| Unsupported `iops_range` | 11 OUT_OF_RANGE | Indicates that the iops range is not allowed by the Plugin. More human-readable information MAY be provided in the gRPC `status.message` field. | Caller MUST fix the iops range before retrying. |
+| Unsupported `throughput_range` | 11 OUT_OF_RANGE | Indicates that the throughput range is not allowed by the Plugin. More human-readable information MAY be provided in the gRPC `status.message` field. | Caller MUST fix the throughput range before retrying. |
+
 #### `GetCapacity`
 
 A Controller Plugin MUST implement this RPC call if it has `GET_CAPACITY` controller capability.
@@ -1773,6 +1852,10 @@ message ControllerServiceCapability {
       // SINGLE_NODE_SINGLE_WRITER and/or SINGLE_NODE_MULTI_WRITER are
       // supported, in order to permit older COs to continue working.
       SINGLE_NODE_MULTI_WRITER = 13 [(alpha_enum_value) = true];
+
+      // Indicates the SP supports modifying iops and throughput of the volume
+      // See ModifyVolume for details.
+      MODIFY_VOLUME = 14 [(alpha_enum_value) = true];
     }
 
     Type type = 1;