Documentation for Share Migration Ocata Improvements.

Implemented several improvements to share migration in documentation
according to https://review.opendev.org/#/c/406305/

Summary of changes:

 - Add driver-assisted mandatory parameters.
 - Removed previous API documentation because support for them isn't
   there anymore after the backwards incompatible changes were
   made via https://review.opendev.org/#/c/406305/.
 - Add force-host-assisted migration.

Change-Id: I6d446b4037a3a9991e375f0a8bfb1f6edce09c1f
Closes-Bug: #1658230

api-ref/source/parameters.yaml

@@ -1068,13 +1068,16 @@ force_delete_2:
   in: body
   required: true
   type: string
-force_host_copy:
+force_host_assisted_migration:
   description: |
-    Enables or disables generic host-based forced
+    Forces the host-assisted mechanism to be used, thus using the
-    migrations, which bypasses driver optimizations. Default value is
+    Data Service to copy data across back ends. This parameter
-    ``false``.
+    value defaults to ``False``. When set to ``True``,
+    it skips the driver-assisted approach which would
+    otherwise be attempted first. If this option is set to
+    ``True``, all driver-assisted options must be set to ``False``.
   in: body
-  required: true
+  required: false
   type: boolean
 force_snapshot_request:
   description: |
@@ -1136,6 +1139,14 @@ has_replicas:
   required: true
   type: boolean
   min_version: 2.11
+host:
+  description: |
+    The target pool to which the share should be migrated to,
+    in format ``host@backend#pool``. E.g.
+    ``ubuntu@generic1#GENERIC1``.
+  in: body
+  required: true
+  type: string
 host_1:
   description: |
     The share host name.
@@ -1529,6 +1540,27 @@ neutron_subnet_id_request:
   in: body
   required: false
   type: string
+new_share_network_id:
+  description:  |
+    If willing to change the share’s share-network so it can be
+    allocated in the desired destination pool, the invoker may
+    supply a new share network to be used. This is often suited
+    when the share is to be migrated to a pool which operates
+    in a different availability zone or managed by a driver
+    that handles share servers.
+  in: body
+  required: false
+  type: string
+new_share_type_id:
+  description: |
+     If willing to retype the share so it can be allocated in the
+     desired destination pool, the invoker may supply a new share
+     type to be used. This is often suited when the share is to
+     be migrated to a pool which operates in the opposite
+     driver mode.
+  in: body
+  required: false
+  type: string
 next-available:
   description: |
     The date and time stamp when next issues are available.
@@ -1547,18 +1579,19 @@ next-available:
   in: body
   required: false
   type: string
-notify:
+nondisruptive:
   description: |
-    Enables or disables notification of data copying completed
+    Specifies whether migration should only be performed
+    without disrupting clients during migration. For such,
+    it is also expected that the export location does not change.
+    When set to ``True`` and drivers are not capable of allowing
+    the share to remain accessible through the two phases of the
+    migration, migration will result in an error status.
+    As of Ocata release, host-assisted migration cannot provide
+    this capability.
   in: body
   required: true
-  type: string
+  type: boolean
-os-migrate_share:
-  description: |
-    The ``migrate_share`` object.
-  in: body
-  required: true
-  type: object
 os-share-type-access:is_public:
   description: |
     Indicates whether a share type is publicly
@@ -1582,6 +1615,29 @@ pools:
   in: body
   required: true
   type: string
+preserve_metadata:
+  description: |
+    Specifies whether migration should enforce the preservation
+    of all file system metadata. When set to ``True``
+    and drivers are not capable of ensuring preservation
+    of file system metadata, migration will result in an
+    error status. As of Ocata release, host-assisted
+    migration cannot provide any guarantees of preserving
+    file system metadata.
+  in: body
+  required: true
+  type: boolean
+preserve_snapshots:
+  description: |
+    Specifies whether migration should enforce the preservation
+    of all existing snapshots at the destination. When set to
+    ``True`` and drivers are not capable of migrating the
+    snapshots, migration will result in an error status.
+    As of Ocata release, host-assisted migration cannot
+    provide this capability.
+  in: body
+  required: true
+  type: boolean
 progress:
   description: |
     The progress of the snapshot creation.
@@ -3014,6 +3070,12 @@ timestamp:
   in: body
   required: true
   type: string
+total_progress:
+  description: |
+    Defines a total progress of share migration.
+  in: body
+  required: true
+  type: integer
 totalReplicaGigabytesUsed:
   description: |
     The total number of replica gigabytes used in a
@@ -3209,3 +3271,18 @@ volume_type:
   in: body
   required: false
   type: string
+writable:
+  description: |
+     Specifies whether migration should only be performed
+     if the share can remain writable. When this behavior is set to ``True``
+     and drivers are not capable of allowing the share to remain writable,
+     migration will result in an error status. If drivers are not capable
+     of performing a nondisruptive migration, manila will ensure that the
+     share will remain writable through the data copy phase of migration.
+     However, during the switchover phase the share will be re-exported
+     at the destination, causing the share to be rendered inaccessible for
+     the duration of this phase. As of Ocata release, host-assisted
+     migration cannot provide this capability.
+  in: body
+  required: true
+  type: boolean

api-ref/source/samples/share-migration-cancel-request.json

@@ -0,0 +1,7 @@
+{
+    "migration_cancel":
+        {
+            "share_id": "406ea93b-32e9-4907-a117-148b3945749f"
+        }
+}
+

api-ref/source/samples/share-migration-complete-request.json

@@ -0,0 +1,6 @@
+{
+    "migration_complete":
+        {
+            "share_id": "406ea93b-32e9-4907-a117-148b3945749f"
+        }
+}

api-ref/source/samples/share-migration-get-process-request.json

@@ -0,0 +1,6 @@
+{
+    "migration_get_process":
+        {
+            "share_id": "406ea93b-32e9-4907-a117-148b3945749f"
+        }
+}

api-ref/source/samples/share-migration-get-process-response.json

@@ -0,0 +1,4 @@
+{
+    "total_progress": 100,
+    "task_state": "migration_driver_phase1_done"
+}

api-ref/source/samples/share-migration-start-request.json

@@ -0,0 +1,14 @@
+{
+    "migration_start":
+        {
+            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
+            "writable": true,
+            "preserve_snapshots": true,
+            "preserve_metadata": true,
+            "nondisruptive": true,
+            "host": "ubuntu@generic2#GENERIC2",
+            "new_share_type_id": "foo_share_type_id",
+            "new_share_network_id": "bar_share_network_id",
+            "force_host_assisted_migration": false
+        }
+}

api-ref/source/share-migration.inc

@@ -1,78 +1,77 @@
 .. -*- rst -*-
 
-================================
+=================================
-Share Migration (since API v2.5)
+Share Migration (since API v2.22)
-================================
+=================================
-As an administrator, you can migrate a share with its data from one
+
-location to another in a manner that is transparent to users and workloads.
+The Share Migration API is an administrator-only experimental API that allows
+the invoker to select a destination pool to migrate a share to,
+while still allowing clients to access the source
+"share instance" during migration.
+
+Share migration is implemented in a 2-phase approach. The first phase of
+migration is when operations that take the longest are performed, such as
+data copying or replication. After first phase of data copying is complete,
+it is up to administrator to trigger the second phase,
+often referred to as switchover phase, which may perform operations
+such as final sync and deleting the source share instance.
+
+During the data copy phase, user can remain connected to the source, and may have
+to reconnect after the switchover phase. In order to migrate a share, manila
+may employ one of two mechanisms which are driver-assisted migration and
+host-assisted migration.
+
+- ``Driver-assisted migration``: This mechanism is intended to make use of driver
+    optimizations to migrate shares between pools of the same storage vendor.
+    This mechanism allows migrating shares nondisruptively while the source
+    remains writable, preserving all filesystem metadata and snapshots.
+    The migration workload is performed in the storage back end.
+
+- ``Host-assisted migration``: This mechanism is intended to migrate
+    shares in an agnostic manner between two different pools, regardless
+    of storage vendor. The implementation for this mechanism does not
+    offer the same properties found in driver-assisted migration.
+    In host-assisted migration, the source remains readable,
+    snapshots must be deleted prior to starting the migration,
+    filesystem metadata may be lost, and the clients will get
+    disconnected by the end of migration. The migration workload
+    is performed by the Data Service, which is a dedicated
+    manila service for intensive data operations.
+
+These methods provide different capabilities
+and affect how efficiently the data copy and switchover
+are achieved. Generally speaking, driver-assisted migration is
+limited to homogenous storage backends and when available,
+is expected to be faster and more efficient than host-assisted migration.
+Driver-assisted migration occurs on the storage backend,
+while host-assisted migration occurs on the OpenStack nodes
+running the manila data service.
+
+When starting a migration, ``driver-assisted migration`` is
+attempted first. If the shared file system service detects
+it is not possible to perform the ``driver-assisted
+migration``, it proceeds to attempt
+``host-assisted migration``.
 
 Possible use cases for data migration include:
 
- - Bring down a physical storage device for maintenance without disrupting
+ - Migrating shares along with snapshots.
-   workloads.
+ - Bring down a physical storage device for maintenance
- - Modify the properties of a share.
  - Free up space in a thinly-provisioned back end.
+ - Load balancing among share servers.
+ - Retyping a share
 
 .. note::
 
     Share Migration APIs are `experimental APIs <#experimental-apis>`_ .
 
 
-Migrate share (DEPRECATED)
+Start Migration
-==========================
+===============
 
-.. warning::
+.. rest_method:: POST /v2/{project_id}/shares/{share_id}/action
 
-   This API is deprecated starting with microversion 2.15 and requests to
+.. versionadded:: 2.22
-   this API will fail with a 404 starting from microversion 2.15. Please see
-   the new experimental API below.
-
-.. rest_method::  POST /v2/{project_id}/shares/{share_id}/action
-
-.. versionadded:: 2.5
-
-Migrates a share from one back end to another.
-
-You can migrate a share from one back end to another but both back
-ends must set the ``driver_handles_share_servers`` parameter to
-``False``. If a share driver handles one of the back ends, this
-action is not supported. You can configure a back end in the
-``manila.conf`` file.
-
-Response codes
---------------
-
-.. rest_status_code:: success status.yaml
-
-   - 202
-
-.. rest_status_code:: error status.yaml
-
-   - 400
-   - 401
-   - 403
-   - 404
-   - 409
-
-Request
--------
-
-.. rest_parameters:: parameters.yaml
-
-   - project_id: project_id_path
-   - share_id: share_id
-   - os-migrate_share: os-migrate_share
-   - migrate_share: migrate_share
-   - host: host_10
-   - force_host_copy: force_host_copy
-
-
-Start Migration (since API v2.15)
-=================================
-
-.. rest_method::  POST /v2/{project_id}/shares/{share_id}/action
-
-.. versionadded:: 2.15
 
 Initiates share migration. This API will initiate the share data copy to the
 new host. The copy operation is non-disruptive.
@@ -97,23 +96,33 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - project_id: project_id_path
+   - project_id: project_id
    - share_id: share_id
-   - migrate-start: migrate-start
+   - force_host_assisted_migration: force_host_assisted_migration
-   - host: host_10
+   - preserve_snapshots: preserve_snapshots
-   - notify: notify
+   - preserve_metadata: preserve_metadata
-   - force_host_copy: force_host_copy
+   - nondisruptive: nondisruptive
+   - writable: writable
+   - new_share_type_id: new_share_type_id
+   - new_share_network_id: new_share_network_id
+   - host: host
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-migration-start-request.json
+   :language: javascript
 
 
-Complete Migration (since API v2.15)
+Complete Migration
-=======================================
+==================
 
 .. rest_method::  POST /v2/{project_id}/shares/{share_id}/action
 
-.. versionadded:: 2.15
+.. versionadded:: 2.22
 
 Completes share migration. This API will initiate the switch-over from the
-source to destination share. This operation is disruptive.
+source to destination share. This operation can be disruptive.
 
 Response codes
 --------------
@@ -135,9 +144,99 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - project_id: project_id_path
+   - project_id: project_id
    - share_id: share_id
-   - migration_complete: migration_complete
+
-   - host: host_10
+Request example
-   - notify: notify
+---------------
-   - force_host_copy: force_host_copy
+
+.. literalinclude:: samples/share-migration-complete-request.json
+   :language: javascript
+
+
+Migration Get Process
+=====================
+
+.. rest_method::  POST /v2/{project_id}/shares/{share_id}/action
+
+.. versionadded:: 2.22
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 202
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - share_id: share_id
+   - project_id: project_id
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - total_progress: total_progress
+   - task_state: task_state
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-migration-get-process-request.json
+   :language: javascript
+
+Response_parameters
+-------------------
+
+.. literalinclude:: samples/share-migration-get-process-response.json
+   :language: javascript
+
+
+Cancel Migration
+================
+
+.. rest_method::  POST /v2/{project_id}/shares/{share_id}/action
+
+.. versionadded:: 2.22
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 202
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - share_id: share_id
+   - project_id: project_id
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-migration-cancel-request.json
+   :language: javascript