api-ref: add docs for os-migrate_volume API

Adds the v2 and v3 API reference documentation for the
admin-only (by default) os-migrate_volume volume action
API. The only major difference with the v3 API is the
cluster parameter introduced in the 3.16 microversion.

Change-Id: I70f6b2cc4d25ea155ce09ddeec26b995890a2db3
Partial-Bug: #1607539

api-ref/source/v2/parameters.yaml

@@ -980,6 +980,29 @@ metadata_items:
   in: body
   required: true
   type: integer
+migrate_force_host_copy:
+  description: |
+    If false (the default), rely on the volume backend driver to perform
+    the migration, which might be optimized. If true, or the volume driver
+    fails to migrate the volume itself, a generic host-based migration is
+    performed.
+  in: body
+  required: false
+  type: boolean
+migrate_host:
+  description: |
+    The target host for the volume migration. Host format is ``host@backend``.
+  in: body
+  required: true
+  type: string
+migrate_lock_volume:
+  description: |
+    If true, migrating an ``available`` volume will change its status to
+    ``maintenance`` preventing other operations from being performed on the
+    volume such as attach, detach, retype, etc.
+  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.
@@ -1201,6 +1224,12 @@ os-force_detach:
   in: body
   required: true
   type: object
+os-migrate_volume:
+  description: |
+    The ``os-migrate_volume`` 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-request.json

@@ -0,0 +1,5 @@
+{
+    "os-migrate_volume": {
+        "host": "node1@lvm"
+    }
+}

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

@@ -405,6 +405,69 @@ Request Example
    :language: javascript
 
 
+Migrate volume
+~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v2/{project_id}/volumes/{volume_id}/action
+
+Specify the ``os-migrate_volume`` action in the request body.
+
+Migrates a volume to the specified host.
+
+It is generally not recommended to migrate an *in-use* multiattach volume if
+that volume has more than one active read/write attachment.
+
+Policy defaults enable only users with the administrative role to perform this
+operation. Cloud providers can change these permissions through the
+policy.json file.
+
+**Preconditions**
+
+* The volume ``status`` must be ``available`` or ``in-use``.
+* The volume ``migration_status`` must be ``None``, ``deleting``, ``error``,
+  or ``success``.
+* The volume ``replication_status`` must be ``None``, ``disabled`` or
+  ``not-capable``.
+* The migration must happen to another host from which the
+  volume currently resides.
+* The volume must not be a member of a group.
+* The volume must not have snapshots.
+
+**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``. In the case of failure,
+if ``lock_volume`` was true and the volume was originally ``available`` when
+it was migrated, the ``status`` will go back to ``available``.
+
+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: os-migrate_volume
+   - host: migrate_host
+   - force_host_copy: migrate_force_host_copy
+   - lock_volume: migrate_lock_volume
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/volume-os-migrate_volume-request.json
+   :language: javascript
+
+
 Force delete volume
 ~~~~~~~~~~~~~~~~~~~
 

api-ref/source/v3/parameters.yaml

@@ -1724,6 +1724,40 @@ metadata_9:
   required: false
   type: object
   min_version: 3.43
+migrate_cluster:
+  description: |
+    The target cluster for the volume migration. Cluster format is
+    ``cluster@backend``. Starting with microversion 3.16, either ``cluster``
+    or ``host`` must be specified. If ``host`` is specified and is part of a
+    cluster, the cluster is used as the target for the migration.
+  in: body
+  required: false
+  type: string
+  min_version: 3.16
+migrate_force_host_copy:
+  description: |
+    If false (the default), rely on the volume backend driver to perform
+    the migration, which might be optimized. If true, or the volume driver
+    fails to migrate the volume itself, a generic host-based migration is
+    performed.
+  in: body
+  required: false
+  type: boolean
+migrate_host:
+  description: |
+    The target host for the volume migration. Host format is ``host@backend``.
+    Required before microversion 3.16.
+  in: body
+  required: false
+  type: string
+migrate_lock_volume:
+  description: |
+    If true, migrating an ``available`` volume will change its status to
+    ``maintenance`` preventing other operations from being performed on the
+    volume such as attach, detach, retype, etc.
+  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.
@@ -2010,6 +2044,12 @@ os-initialize_connection:
   in: body
   required: true
   type: object
+os-migrate_volume:
+  description: |
+    The ``os-migrate_volume`` action.
+  in: body
+  required: true
+  type: object
 os-reserve:
   description: |
     The ``os-reserve`` action.

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

@@ -0,0 +1,5 @@
+{
+    "os-migrate_volume": {
+        "host": "node1@lvm"
+    }
+}

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

@@ -464,6 +464,73 @@ Request Example
    :language: javascript
 
 
+Migrate a volume
+~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/volumes/{volume_id}/action
+
+Specify the ``os-migrate_volume`` action in the request body.
+
+Migrates a volume to the specified host. Starting with the
+`3.16 microversion`_ a cluster can be specified instead of a host.
+
+It is generally not recommended to migrate an *in-use* multiattach volume if
+that volume has more than one active read/write attachment.
+
+Policy defaults enable only users with the administrative role to perform this
+operation. Cloud providers can change these permissions through the
+policy.json file.
+
+.. _3.16 microversion: https://docs.openstack.org/cinder/latest/contributor/api_microversion_history.html#id15
+
+**Preconditions**
+
+* The volume ``status`` must be ``available`` or ``in-use``.
+* The volume ``migration_status`` must be ``None``, ``deleting``, ``error``,
+  or ``success``.
+* The volume ``replication_status`` must be ``None``, ``disabled`` or
+  ``not-capable``.
+* The migration must happen to another host (or cluster) from which the
+  volume currently resides.
+* The volume must not be a member of a group.
+* The volume must not have snapshots.
+
+**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``. In the case of failure,
+if ``lock_volume`` was true and the volume was originally ``available`` when
+it was migrated, the ``status`` will go back to ``available``.
+
+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: os-migrate_volume
+   - host: migrate_host
+   - force_host_copy: migrate_force_host_copy
+   - lock_volume: migrate_lock_volume
+   - cluster: migrate_cluster
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/volume-os-migrate_volume-request.json
+   :language: javascript
+
+
 Force delete a volume
 ~~~~~~~~~~~~~~~~~~~~~