Spec ModifyVolume for QoS kep-3751

Author: sunnylovestiramisu

spec.md

@@ -381,6 +381,11 @@ service Controller {
     returns (ControllerGetVolumeResponse) {
         option (alpha_method) = true;
     }
+
+  rpc ControllerModifyVolume (ModifyVolumeRequest)
+    returns (ModifyVolumeResponse) {
+        option (alpha_method) = true;
+    }
 }
 
 service GroupController {
@@ -843,6 +848,10 @@ 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
+  // volume performance class parameters to apply. 
+  map<string, string> volume_performance_class_parameters = 8;
 }
 
 // Specifies what source the volume will be created from. One of the
@@ -1617,6 +1626,57 @@ 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. If the MODIFY_VOLUME capability is present, a Controller plugin MUST implement this RPC call. This RPC allows the CO to change key Performance parameters(iops and throughput) of a volume. 
+
+This operation MUST be idempotent. The preset parameters in the VolumePerformanceClass can be greater than or less than the current values. 
+
+
+```protobuf
+message VolumePerformanceClass {
+  // The name for the volume Performance class. 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 = 1;
+  // Volume Performance specific parameters passed in as opaque key-value pairs.
+  // This field is OPTIONAL. The driver is responsible for parsing and
+  // validating these parameters. COs will treat these as opaque.
+  // Example of valid parameters:
+  // Iops of the volume to be updated to. The unit is IO per
+  // second per volume. If specified it MUST always be honored.
+  // Throughput of the volume to be updated to. The unit is Mib per
+  // second per volume. 
+  // If specified it MUST always be honored.
+  map<string, string> parameters = 2;
+}
+
+message ModifyVolumeRequest {
+  // Contains identity information for the existing volume.
+  // This field is REQUIRED.
+  string volume_id = 1
+  // This field is OPTIONAL.This allows the CO to specify the
+  // volume performance class parameters to apply. 
+  map<string, string> volume_performance_class_parameters = 2;
+}
+message ModifyVolumeResponse {
+  VolumePerformanceClass volume_Performance_class = 1
+}
+
+```
+
+##### ModifyVolume Errors
+
+| Condition | gRPC Code | Description | Recovery Behavior |
+|-----------|-----------|-------------|-------------------|
+| Parameters not supported | 3 INVALID_ARGUMENT | Indicates that the CO has specified volume performance parameters not supported by the volume. | Caller MAY verify volume performance parameters. |
+| 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. |
+
 #### `GetCapacity`
 
 A Controller Plugin MUST implement this RPC call if it has `GET_CAPACITY` controller capability.
@@ -1773,6 +1833,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 volume with performance specific 
+      // See ModifyVolume for details.
+      MODIFY_VOLUME = 14 [(alpha_enum_value) = true];
     }
 
     Type type = 1;