Add api reference for share server migration

Add documentation to the share server migration APIs introduced
during Victoria release.

Partial-bug: #1897903

Change-Id: I13d13c38a3869929bbfdf8083529a597d7982a16

api-ref/source/index.rst

@@ -45,3 +45,4 @@ Shared File Systems API (EXPERIMENTAL)
 
 .. include:: experimental.inc
 .. include:: share-migration.inc
+.. include:: share-server-migration.inc

api-ref/source/parameters.yaml

@@ -811,6 +811,15 @@ cidr:
   required: true
   type: string
   max_version: 2.50
+compatible:
+  description: |
+    Whether the destination backend can or can't handle the share server
+    migration considering the received entries for ``share_network_id``,
+    ``host``, ``nondisruptive``, ``writable`` and ``preserve_snapshots``
+    matched with the driver supported capabilities.
+  in: body
+  required: true
+  type: boolean
 consistent_snapshot_support:
   description: |
     The consistency snapshot support.
@@ -878,6 +887,13 @@ description_request:
   in: body
   required: false
   type: string
+destination_share_server_id:
+  description: |
+    UUID of the share server that was created in the destination backend during
+    a share server migration operation.
+  in: body
+  required: true
+  type: string
 detail_id_body:
   in: body
   required: true
@@ -1181,6 +1197,13 @@ host_share_server_body:
   in: body
   required: true
   type: string
+host_share_server_migration:
+  description: |
+    The target backend to which the share server should be migrated to,
+    in format ``host@backend``. E.g. ``ubuntu@generic1``.
+  in: body
+  required: true
+  type: string
 id_13:
   description: |
     The share instance ID.
@@ -1551,6 +1574,14 @@ new_share_network_id:
   in: body
   required: false
   type: string
+new_share_network_id_server_migration:
+  description:  |
+    If willing to change the share server’s share-network so it can be
+    allocated in the desired destination backend, the invoker may
+    supply a new share network to be used.
+  in: body
+  required: false
+  type: string
 new_share_type_id:
   description: |
      If willing to retype the share so it can be allocated in the
@@ -1592,6 +1623,17 @@ nondisruptive:
   in: body
   required: true
   type: boolean
+nondisruptive_server_migration:
+  description: |
+    Specifies whether share server 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 server to remain accessible through the two phases of the
+    migration, migration will result in an error status.
+  in: body
+  required: true
+  type: boolean
 os-share-type-access:is_public:
   description: |
     Indicates whether a share type is publicly
@@ -1638,6 +1680,15 @@ preserve_snapshots:
   in: body
   required: true
   type: boolean
+preserve_snapshots_server_migration:
+  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.
+  in: body
+  required: true
+  type: boolean
 progress:
   description: |
     The progress of the snapshot creation.
@@ -1962,6 +2013,15 @@ request_id_body:
   in: body
   required: true
   type: string
+requested_capabilities:
+  description: |
+    The parameters that were sent to the server in order to check if the
+    destination host can handle the share server migration. This object
+    contains the following attributes: ``writable``, ``nondisruptive``,
+    ``preserve_snapshots``, ``share_network_id`` and ``host``.
+  in: body
+  required: true
+  type: object
 required_extra_specs:
   description: |
     The required extra specifications for the share
@@ -3040,6 +3100,17 @@ status_share_server_body:
   in: body
   required: true
   type: string
+supported_capabilities:
+  description: |
+    The driver's supported attributes for a share server migration. It
+    will contain the following items: ``writable``, ``nondisruptive``,
+    ``preserve_snapshots`` and ``share_network_id``. Drivers will also report
+    if they can perform ``migration_cancel`` and ``migration_get_progress``
+    operations. All of the mentioned parameters will be present in this
+    object. All parameters but the ``share_network_id`` are boolean values.
+  in: body
+  required: true
+  type: object
 task_state:
   description: |
     For the share migration, the migration task state.  A valid
@@ -3052,6 +3123,16 @@ task_state:
   required: true
   type: string
   min_version: 2.5
+task_state_server_migration:
+  description: |
+    For the share server migration, the migration task state. A valid
+    value is ``null``, ``migration_in_progress``,
+    ``migration_cancel_in_progress``, ``migration_cancelled``,
+    ``migration_driver_starting``, ``migration_driver_in_progress``, or
+    ``migration_phase_1_done``.
+  in: body
+  required: true
+  type: string
 timestamp:
   description: |
     The date and time stamp when the API request was issued.
@@ -3076,6 +3157,12 @@ total_progress:
   in: body
   required: true
   type: integer
+total_progress_server_migration:
+  description: |
+    Defines a total progress of share server migration.
+  in: body
+  required: true
+  type: integer
 totalReplicaGigabytesUsed:
   description: |
     The total number of replica gigabytes used in a
@@ -3286,3 +3373,17 @@ writable:
   in: body
   required: true
   type: boolean
+writable_server_migration:
+  description: |
+     Specifies whether migration should only be performed
+     if the shares can remain writable. When this behavior is set to ``True``
+     and drivers are not capable of allowing the shares 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
+     shares will remain writable through the data copy phase of migration.
+     However, during the switchover phase all shares will be re-exported
+     at the destination, causing the shares to be rendered inaccessible for
+     the duration of this phase.
+  in: body
+  required: true
+  type: boolean

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

@@ -0,0 +1,3 @@
+{
+    "migration_cancel":null
+}

api-ref/source/samples/share-server-migration-check-compatibility-request.json

@@ -0,0 +1,9 @@
+{
+    "migration_check": {
+        "host": "foohost2@backend2",
+        "preserve_snapshots": "True",
+        "writable": "True",
+        "nondisruptive": "True",
+        "new_share_network_id": null
+    }
+}

api-ref/source/samples/share-server-migration-check-compatibility-response.json

@@ -0,0 +1,18 @@
+{
+    "compatible": false,
+    "requested_capabilities": {
+        "writable": "True",
+        "nondisruptive": "True",
+        "preserve_snapshots": "True",
+        "share_network_id": null,
+        "host": "foohost2@backend2"
+    },
+    "supported_capabilities": {
+        "writable": true,
+        "nondisruptive": false,
+        "preserve_snapshots": true,
+        "share_network_id": "1d04b755-649f-46a4-964c-be9f0395af13",
+        "migration_cancel": true,
+        "migration_get_progress": true
+    }
+}

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

@@ -0,0 +1,3 @@
+{
+    "migration_complete": null
+}

api-ref/source/samples/share-server-migration-complete-response.json

@@ -0,0 +1,3 @@
+{
+    "destination_share_server_id": "c2f71561-85e2-4ccb-a91a-e44f9ff6f7ef"
+}

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

@@ -0,0 +1,3 @@
+{
+    "migration_get_progress": null
+}

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

@@ -0,0 +1,5 @@
+{
+    "total_progress": 50,
+    "task_state": "migration_driver_in_progress",
+    "destination_share_server_id": "c2f71561-85e2-4ccb-a91a-e44f9ff6f7ef"
+}

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

@@ -0,0 +1,9 @@
+{
+    "migration_start": {
+        "host": "foohost2@backend2",
+        "preserve_snapshots": "True",
+        "writable": "True",
+        "nondisruptive": "False",
+        "new_share_network_id": null
+    }
+}

api-ref/source/share-server-migration.inc

@@ -0,0 +1,289 @@
+.. -*- rst -*-
+
+========================================
+Share Server Migration (since API v2.57)
+========================================
+
+The Share Server Migration API is an administrator-only experimental API that
+allows the invoker to select a destination backend to migrate a share server
+to.
+
+Share server migration uses a 2-phased approach. In the first phase of the
+migration, the data copying or replication operations are performed, so it's
+the longer phase. After the first phase is finished, the administrator can
+trigger the second phase, which consists in final syncs and making the new
+share server available to be used and the latter one inactive.
+
+During the data copy phase, source shares will remain available and writable
+if it was required by the administrator and supported by the share driver.
+After the second phase, users may need to reconnect to the shares affected by
+the migration.
+All shares belonging to a share server are migrated and their access rules are
+preserved through the migration.
+The share snapshots are going to be copied if specified by the administrator
+and/or supported by the driver.
+
+.. important::
+  In order to migrate a share server, the administrator must make sure that
+  none of the shares on the server are replicated or in a share group.
+
+.. note::
+
+    Share Server Migration APIs are `experimental APIs <#experimental-apis>`_ .
+
+Possible uses for share server migration include:
+
+ - Migrating a share server and all its shares and snapshots at once.
+ - Bring down a physical storage device for maintenance.
+ - Free up space in a thinly-provisioned back end.
+ - Load balancing among backends.
+
+
+Share Server Migration Check Compatibility
+==========================================
+
+.. rest_method:: POST /v2/{project_id}/share_servers/{share_server_id}/action
+
+.. versionadded:: 2.57
+
+Checks if a share driver can handle a share server migration according to
+the specified destination host and ``new_share_network_id``, as well as the
+``writable``, ``nondisruptive`` and ``preserve_snapshots`` flags.
+
+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
+   - share_server_id: share_server_id
+   - preserve_snapshots: preserve_snapshots_server_migration
+   - nondisruptive: nondisruptive_server_migration
+   - writable: writable_server_migration
+   - new_share_network_id: new_share_network_id_server_migration
+   - host: host_share_server_migration
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - compatible: compatible
+   - requested_capabilities: requested_capabilities
+   - supported_capabilities: supported_capabilities
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-server-migration-check-compatibility-request.json
+   :language: javascript
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-server-migration-check-compatibility-response.json
+   :language: javascript
+
+
+Start a Share Server Migration
+==============================
+
+.. rest_method:: POST /v2/{project_id}/share_servers/{share_server_id}/action
+
+.. versionadded:: 2.57
+
+Triggers a share server migration. This API will initiate the first phase of
+the share server migration to a new host.
+
+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
+   - share_server_id: share_server_id
+   - preserve_snapshots: preserve_snapshots_server_migration
+   - nondisruptive: nondisruptive_server_migration
+   - writable: writable_server_migration
+   - new_share_network_id: new_share_network_id_server_migration
+   - host: host_share_server_migration
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-server-migration-start-request.json
+   :language: javascript
+
+
+Complete Share Server Migration
+===============================
+
+.. rest_method:: POST /v2/{project_id}/share_servers/{share_server_id}/action
+
+.. versionadded:: 2.57
+
+Completes share server migration. This API will initiate the switch-over
+from the source to destination share server. This operation can be disruptive.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 202
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id
+   - share_server_id: share_server_id
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - total_progress: total_progress_server_migration
+   - task_state: task_state_server_migration
+   - destination_share_server_id: destination_share_server_id
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-server-migration-complete-request.json
+   :language: javascript
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-server-migration-complete-response.json
+   :language: javascript
+
+
+Share Server Migration Get Progress
+===================================
+
+.. rest_method:: POST /v2/{project_id}/share_servers/{share_server_id}/action
+
+.. versionadded:: 2.57
+
+Returns the completed percentage and the destination share server id of an
+ongoing share server migration.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 202
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - share_server_id: share_server_id
+   - project_id: project_id
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - total_progress: total_progress_server_migration
+   - task_state: task_state_server_migration
+   - destination_share_server_id: destination_share_server_id
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-server-migration-get-progress-request.json
+   :language: javascript
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-server-migration-get-progress-response.json
+   :language: javascript
+
+
+Cancel Share Server Migration
+=============================
+
+.. rest_method:: POST /v2/{project_id}/share_servers/{share_server_id}/action
+
+.. versionadded:: 2.57
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 202
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - share_server_id: share_server_id
+   - project_id: project_id
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-server-migration-cancel-request.json
+   :language: javascript