Documentation for Share Migration Ocata Improvements.
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:
parent
4f0a61af39
commit
295adb71bf
@ -1068,13 +1068,16 @@ force_delete_2:
|
|||||||
in: body
|
in: body
|
||||||
required: true
|
required: true
|
||||||
type: string
|
type: string
|
||||||
force_host_copy:
|
force_host_assisted_migration:
|
||||||
description: |
|
description: |
|
||||||
Enables or disables generic host-based forced
|
Forces the host-assisted mechanism to be used, thus using the
|
||||||
migrations, which bypasses driver optimizations. Default value is
|
Data Service to copy data across back ends. This parameter
|
||||||
``false``.
|
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
|
in: body
|
||||||
required: true
|
required: false
|
||||||
type: boolean
|
type: boolean
|
||||||
force_snapshot_request:
|
force_snapshot_request:
|
||||||
description: |
|
description: |
|
||||||
@ -1136,6 +1139,14 @@ has_replicas:
|
|||||||
required: true
|
required: true
|
||||||
type: boolean
|
type: boolean
|
||||||
min_version: 2.11
|
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:
|
host_1:
|
||||||
description: |
|
description: |
|
||||||
The share host name.
|
The share host name.
|
||||||
@ -1529,6 +1540,27 @@ neutron_subnet_id_request:
|
|||||||
in: body
|
in: body
|
||||||
required: false
|
required: false
|
||||||
type: string
|
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:
|
next-available:
|
||||||
description: |
|
description: |
|
||||||
The date and time stamp when next issues are available.
|
The date and time stamp when next issues are available.
|
||||||
@ -1547,18 +1579,19 @@ next-available:
|
|||||||
in: body
|
in: body
|
||||||
required: false
|
required: false
|
||||||
type: string
|
type: string
|
||||||
notify:
|
nondisruptive:
|
||||||
description: |
|
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
|
in: body
|
||||||
required: true
|
required: true
|
||||||
type: string
|
type: boolean
|
||||||
os-migrate_share:
|
|
||||||
description: |
|
|
||||||
The ``migrate_share`` object.
|
|
||||||
in: body
|
|
||||||
required: true
|
|
||||||
type: object
|
|
||||||
os-share-type-access:is_public:
|
os-share-type-access:is_public:
|
||||||
description: |
|
description: |
|
||||||
Indicates whether a share type is publicly
|
Indicates whether a share type is publicly
|
||||||
@ -1582,6 +1615,29 @@ pools:
|
|||||||
in: body
|
in: body
|
||||||
required: true
|
required: true
|
||||||
type: string
|
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:
|
progress:
|
||||||
description: |
|
description: |
|
||||||
The progress of the snapshot creation.
|
The progress of the snapshot creation.
|
||||||
@ -3014,6 +3070,12 @@ timestamp:
|
|||||||
in: body
|
in: body
|
||||||
required: true
|
required: true
|
||||||
type: string
|
type: string
|
||||||
|
total_progress:
|
||||||
|
description: |
|
||||||
|
Defines a total progress of share migration.
|
||||||
|
in: body
|
||||||
|
required: true
|
||||||
|
type: integer
|
||||||
totalReplicaGigabytesUsed:
|
totalReplicaGigabytesUsed:
|
||||||
description: |
|
description: |
|
||||||
The total number of replica gigabytes used in a
|
The total number of replica gigabytes used in a
|
||||||
@ -3209,3 +3271,18 @@ volume_type:
|
|||||||
in: body
|
in: body
|
||||||
required: false
|
required: false
|
||||||
type: string
|
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
|
||||||
|
@ -0,0 +1,7 @@
|
|||||||
|
{
|
||||||
|
"migration_cancel":
|
||||||
|
{
|
||||||
|
"share_id": "406ea93b-32e9-4907-a117-148b3945749f"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,6 @@
|
|||||||
|
{
|
||||||
|
"migration_complete":
|
||||||
|
{
|
||||||
|
"share_id": "406ea93b-32e9-4907-a117-148b3945749f"
|
||||||
|
}
|
||||||
|
}
|
@ -0,0 +1,6 @@
|
|||||||
|
{
|
||||||
|
"migration_get_process":
|
||||||
|
{
|
||||||
|
"share_id": "406ea93b-32e9-4907-a117-148b3945749f"
|
||||||
|
}
|
||||||
|
}
|
@ -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
14
api-ref/source/samples/share-migration-start-request.json
Normal 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
|
||||||
|
}
|
||||||
|
}
|
@ -1,78 +1,77 @@
|
|||||||
.. -*- rst -*-
|
.. -*- rst -*-
|
||||||
|
|
||||||
================================
|
=================================
|
||||||
Share Migration (since API v2.5)
|
Share Migration (since API v2.22)
|
||||||
================================
|
=================================
|
||||||
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.
|
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:
|
Possible use cases for data migration include:
|
||||||
|
|
||||||
- Bring down a physical storage device for maintenance without disrupting
|
- Migrating shares along with snapshots.
|
||||||
workloads.
|
- Bring down a physical storage device for maintenance
|
||||||
- Modify the properties of a share.
|
|
||||||
- Free up space in a thinly-provisioned back end.
|
- Free up space in a thinly-provisioned back end.
|
||||||
|
- Load balancing among share servers.
|
||||||
|
- Retyping a share
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
Share Migration APIs are `experimental APIs <#experimental-apis>`_ .
|
Share Migration APIs are `experimental APIs <#experimental-apis>`_ .
|
||||||
|
|
||||||
|
|
||||||
Migrate share (DEPRECATED)
|
Start Migration
|
||||||
==========================
|
===============
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
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
|
.. rest_method:: POST /v2/{project_id}/shares/{share_id}/action
|
||||||
|
|
||||||
.. versionadded:: 2.5
|
.. versionadded:: 2.22
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
Initiates share migration. This API will initiate the share data copy to the
|
Initiates share migration. This API will initiate the share data copy to the
|
||||||
new host. The copy operation is non-disruptive.
|
new host. The copy operation is non-disruptive.
|
||||||
@ -97,23 +96,33 @@ Request
|
|||||||
|
|
||||||
.. rest_parameters:: parameters.yaml
|
.. rest_parameters:: parameters.yaml
|
||||||
|
|
||||||
- project_id: project_id_path
|
- project_id: project_id
|
||||||
- share_id: share_id
|
- share_id: share_id
|
||||||
- migrate-start: migrate-start
|
- force_host_assisted_migration: force_host_assisted_migration
|
||||||
- host: host_10
|
- preserve_snapshots: preserve_snapshots
|
||||||
- notify: notify
|
- preserve_metadata: preserve_metadata
|
||||||
- force_host_copy: force_host_copy
|
- 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
|
.. 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
|
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
|
Response codes
|
||||||
--------------
|
--------------
|
||||||
@ -135,9 +144,99 @@ Request
|
|||||||
|
|
||||||
.. rest_parameters:: parameters.yaml
|
.. rest_parameters:: parameters.yaml
|
||||||
|
|
||||||
- project_id: project_id_path
|
- project_id: project_id
|
||||||
- share_id: share_id
|
- share_id: share_id
|
||||||
- migration_complete: migration_complete
|
|
||||||
- host: host_10
|
Request example
|
||||||
- notify: notify
|
---------------
|
||||||
- force_host_copy: force_host_copy
|
|
||||||
|
.. 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
|
||||||
|
Loading…
Reference in New Issue
Block a user