256c18d6c2
Add documentation to the share server migration APIs introduced during Victoria release. Partial-bug: #1897903 Change-Id: I13d13c38a3869929bbfdf8083529a597d7982a16
290 lines
6.7 KiB
ReStructuredText
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
|