295adb71bf
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
243 lines
5.9 KiB
ReStructuredText
243 lines
5.9 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
=================================
|
|
Share Migration (since API v2.22)
|
|
=================================
|
|
|
|
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:
|
|
|
|
- Migrating shares along with snapshots.
|
|
- Bring down a physical storage device for maintenance
|
|
- 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>`_ .
|
|
|
|
|
|
Start Migration
|
|
===============
|
|
|
|
.. rest_method:: POST /v2/{project_id}/shares/{share_id}/action
|
|
|
|
.. versionadded:: 2.22
|
|
|
|
Initiates share migration. This API will initiate the share data copy to the
|
|
new host. The copy operation is non-disruptive.
|
|
|
|
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_id: share_id
|
|
- force_host_assisted_migration: force_host_assisted_migration
|
|
- preserve_snapshots: preserve_snapshots
|
|
- preserve_metadata: preserve_metadata
|
|
- 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
|
|
==================
|
|
|
|
.. rest_method:: POST /v2/{project_id}/shares/{share_id}/action
|
|
|
|
.. versionadded:: 2.22
|
|
|
|
Completes share migration. This API will initiate the switch-over from the
|
|
source to destination share. This operation can be disruptive.
|
|
|
|
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_id: share_id
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. 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
|