openstack/manila
Code Issues Proposed changes

Documentation for Share Migration Ocata Improvements.

Browse Source 
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
This commit is contained in:
vrushti 2020-03-26 23:43:03 +05:30 committed by Victoria Martinez de la Cruz
parent 4f0a61af39
commit 295adb71bf
7 changed files with 302 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
api-ref/source/parameters.yaml
View File

@ -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
migrations, which bypasses driver optimizations. Default value is
``false``.
Forces the host-assisted mechanism to be used, thus using the
Data Service to copy data across back ends. This parameter
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
os-migrate_share:
description: |
The ``migrate_share`` object.
in: body
required: true
type: object
type: boolean
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

7
api-ref/source/samples/share-migration-cancel-request.json Normal file
View File

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

6
api-ref/source/samples/share-migration-complete-request.json Normal file
View File

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

6
api-ref/source/samples/share-migration-get-process-request.json Normal file
View File

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

4
api-ref/source/samples/share-migration-get-process-response.json Normal file
View File

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

14
api-ref/source/samples/share-migration-start-request.json Normal file
View File

@ -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
}
}

249
api-ref/source/share-migration.inc
View File

@ -1,78 +1,77 @@
.. -*- rst -*-
================================
Share Migration (since API v2.5)
================================
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.
=================================
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:
- Bring down a physical storage device for maintenance without disrupting
workloads.
- Modify the properties of a share.
- 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>`_ .
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
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
.. versionadded:: 2.22
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
- host: host_10
- notify: notify
- force_host_copy: force_host_copy
- 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 (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
- notify: notify
- force_host_copy: force_host_copy
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