docs: Add os-migrate_volume_completion api-ref

This admin API is only called externally by Nova at present when
finishing the migration or retype of an attached volume. However for
future reference it would be really useful to have this listed in the
official API reference guide.

Change-Id: I5fad6eb4903784870aa26fa0996a391bbbbb9276

api-ref/source/v2/parameters.yaml

@@ -1040,6 +1040,12 @@ migrate_lock_volume:
   in: body
   required: false
   type: boolean
+migration_completion_error:
+  description: |
+    Used to indicate if an error has occured elsewhere that requires clean up.
+  in: body
+  required: false
+  type: boolean
 # NOTE(mriedem): We can update the migration_policy retype note about encrypted
 # in-use volumes not being supported once
 # https://bugzilla.redhat.com/show_bug.cgi?id=760547 is fixed.
@@ -1213,6 +1219,12 @@ new_type:
   in: body
   required: true
   type: string
+new_volume:
+  description: |
+    The UUID of the new volume.
+  in: body
+  required: true
+  type: string
 object_count:
   description: |
     The number of objects in the backup.
@@ -1267,6 +1279,12 @@ os-migrate_volume:
   in: body
   required: true
   type: object
+os-migrate_volume_completion:
+  description: |
+    The ``os-migrate_volume_completion`` action.
+  in: body
+  required: true
+  type: object
 os-reset_status:
   description: |
     The ``os-reset_status`` action.

api-ref/source/v2/samples/volume-os-migrate_volume_completion-request.json

@@ -0,0 +1,6 @@
+{
+    "os-migrate_volume_completion": {
+        "new_volume": "2b955850-f177-45f7-9f49-ecb2c256d161",
+        "error": false,
+    }
+}

api-ref/source/v2/volumes-v2-volumes-actions.inc

@@ -483,6 +483,56 @@ Request Example
    :language: javascript
 
 
+Complete migration of a volume
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v2/{project_id}/volumes/{volume_id}/action
+
+Specify the ``os-migrate_volume_completion`` action in the request body.
+
+Complete the migration of a volume, updating the new volume in the DB,
+returning the ``status`` of the new volume to that of the original volume
+and finally deleting the original volume.
+
+**Preconditions**
+
+* Both the original and new volume ``migration_status`` must be ``None`` or
+  both must be set to a non ``None`` value.
+* Additionally when set the new volume ``migration_status`` must take the
+  form of ``target:VOLUME_UUID`` where VOLUME_UUID is the original volume UUID.
+
+**Asynchronous Postconditions**
+
+On success, the volume ``status`` will return to its original status of
+``available`` or ``in-use`` and the ``migration_status`` will be ``success``.
+On failure, the ``migration_status`` will be ``error``.
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - volume_id: volume_id_path
+   - project_id: project_id_path
+   - os-migrate_volume_completion: os-migrate_volume_completion
+   - new_volume: new_volume
+   - error: migration_completion_error
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/volume-os-migrate_volume_completion-request.json
+   :language: javascript
+
+
 Force delete volume
 ~~~~~~~~~~~~~~~~~~~
 

api-ref/source/v3/parameters.yaml

@@ -1773,6 +1773,12 @@ migrate_lock_volume:
   in: body
   required: false
   type: boolean
+migration_completion_error:
+  description: |
+    Used to indicate if an error has occured elsewhere that requires clean up.
+  in: body
+  required: false
+  type: boolean
 # NOTE(mriedem): We can update the migration_policy retype note about encrypted
 # in-use volumes not being supported once
 # https://bugzilla.redhat.com/show_bug.cgi?id=760547 is fixed.
@@ -1944,6 +1950,12 @@ new_type:
   in: body
   required: true
   type: string
+new_volume:
+  description: |
+    The UUID of the new volume.
+  in: body
+  required: true
+  type: string
 no_snapshots:
   description: |
     Transfer volume without snapshots. Defaults to False if not specified.
@@ -2024,6 +2036,12 @@ os-migrate_volume:
   in: body
   required: true
   type: object
+os-migrate_volume_completion:
+  description: |
+    The ``os-migrate_volume_completion`` action.
+  in: body
+  required: true
+  type: object
 os-reserve:
   description: |
     The ``os-reserve`` action.

api-ref/source/v3/samples/volume-os-migrate_volume_completion-request.json

@@ -0,0 +1,6 @@
+{
+    "os-migrate_volume_completion": {
+        "new_volume": "2b955850-f177-45f7-9f49-ecb2c256d161",
+        "error": false,
+    }
+}

api-ref/source/v3/volumes-v3-volumes-actions.inc

@@ -546,6 +546,56 @@ Request Example
    :language: javascript
 
 
+Complete migration of a volume
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/volumes/{volume_id}/action
+
+Specify the ``os-migrate_volume_completion`` action in the request body.
+
+Complete the migration of a volume, updating the new volume in the DB,
+returning the ``status`` of the new volume to that of the original volume
+and finally deleting the original volume.
+
+**Preconditions**
+
+* Both the original and new volume ``migration_status`` must be ``None`` or
+  both must be set to a non ``None`` value.
+* Additionally when set the new volume ``migration_status`` must take the
+  form of ``target:VOLUME_UUID`` where VOLUME_UUID is the original volume UUID.
+
+**Asynchronous Postconditions**
+
+On success, the volume ``status`` will return to its original status of
+``available`` or ``in-use`` and the ``migration_status`` will be ``success``.
+On failure, the ``migration_status`` will be ``error``.
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - volume_id: volume_id_path
+   - project_id: project_id_path
+   - os-migrate_volume_completion: os-migrate_volume_completion
+   - new_volume: new_volume
+   - error: migration_completion_error
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/volume-os-migrate_volume_completion-request.json
+   :language: javascript
+
+
 Force delete a volume
 ~~~~~~~~~~~~~~~~~~~~~