From 295adb71bf261bfcbc8ee41ac284901b8b9268d7 Mon Sep 17 00:00:00 2001 From: vrushti Date: Thu, 26 Mar 2020 23:43:03 +0530 Subject: [PATCH] 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 --- api-ref/source/parameters.yaml | 105 +++++++- .../share-migration-cancel-request.json | 7 + .../share-migration-complete-request.json | 6 + .../share-migration-get-process-request.json | 6 + .../share-migration-get-process-response.json | 4 + .../share-migration-start-request.json | 14 + api-ref/source/share-migration.inc | 249 ++++++++++++------ 7 files changed, 302 insertions(+), 89 deletions(-) create mode 100644 api-ref/source/samples/share-migration-cancel-request.json create mode 100644 api-ref/source/samples/share-migration-complete-request.json create mode 100644 api-ref/source/samples/share-migration-get-process-request.json create mode 100644 api-ref/source/samples/share-migration-get-process-response.json create mode 100644 api-ref/source/samples/share-migration-start-request.json diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 9d0e0f937e..653cbcd7f1 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -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 diff --git a/api-ref/source/samples/share-migration-cancel-request.json b/api-ref/source/samples/share-migration-cancel-request.json new file mode 100644 index 0000000000..d1bbf42ae1 --- /dev/null +++ b/api-ref/source/samples/share-migration-cancel-request.json @@ -0,0 +1,7 @@ +{ + "migration_cancel": + { + "share_id": "406ea93b-32e9-4907-a117-148b3945749f" + } +} + diff --git a/api-ref/source/samples/share-migration-complete-request.json b/api-ref/source/samples/share-migration-complete-request.json new file mode 100644 index 0000000000..f5b6ffcb3a --- /dev/null +++ b/api-ref/source/samples/share-migration-complete-request.json @@ -0,0 +1,6 @@ +{ + "migration_complete": + { + "share_id": "406ea93b-32e9-4907-a117-148b3945749f" + } +} diff --git a/api-ref/source/samples/share-migration-get-process-request.json b/api-ref/source/samples/share-migration-get-process-request.json new file mode 100644 index 0000000000..c5a266f541 --- /dev/null +++ b/api-ref/source/samples/share-migration-get-process-request.json @@ -0,0 +1,6 @@ +{ + "migration_get_process": + { + "share_id": "406ea93b-32e9-4907-a117-148b3945749f" + } +} diff --git a/api-ref/source/samples/share-migration-get-process-response.json b/api-ref/source/samples/share-migration-get-process-response.json new file mode 100644 index 0000000000..473911e3aa --- /dev/null +++ b/api-ref/source/samples/share-migration-get-process-response.json @@ -0,0 +1,4 @@ +{ + "total_progress": 100, + "task_state": "migration_driver_phase1_done" +} diff --git a/api-ref/source/samples/share-migration-start-request.json b/api-ref/source/samples/share-migration-start-request.json new file mode 100644 index 0000000000..eaf7f36ae9 --- /dev/null +++ b/api-ref/source/samples/share-migration-start-request.json @@ -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 + } +} diff --git a/api-ref/source/share-migration.inc b/api-ref/source/share-migration.inc index 13115f75c9..6c3e2efdde 100644 --- a/api-ref/source/share-migration.inc +++ b/api-ref/source/share-migration.inc @@ -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