manila/api-ref/source/share-server-migration.inc
silvacarloss 256c18d6c2 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
2021-01-06 09:04:23 -03:00

290 lines
6.7 KiB
ReStructuredText

.. -*- 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