From 281b7dd1cd07ba666ca865d53348907d04a46b83 Mon Sep 17 00:00:00 2001
From: silvacarloss <ces.eduardo98@gmail.com>
Date: Mon, 5 Oct 2020 12:54:40 +0000
Subject: [PATCH] Add developer reference to share server migration
Updates the developer reference with informations regarding the
share server migration feature implemented during Victoria release.
Change-Id: Ia72cf037d2b7dc9fb9d4f19ce141cc044206d6fc
Partial-bug: #1897903
---
.../contributor/driver_requirements.rst | 7 +
doc/source/contributor/index.rst | 1 +
.../contributor/share_server_migration.rst | 241 ++++++++++++++++++
3 files changed, 249 insertions(+)
create mode 100644 doc/source/contributor/share_server_migration.rst
diff --git a/doc/source/contributor/driver_requirements.rst b/doc/source/contributor/driver_requirements.rst
index c5137fa275..fb438fd4c0 100644
--- a/doc/source/contributor/driver_requirements.rst
+++ b/doc/source/contributor/driver_requirements.rst
@@ -333,3 +333,10 @@ Drivers can update, for all the shares created on a particular backend, the
consumed space in GiB. While the polling interval for drivers to update this
information is configurable, drivers can choose to submit cached information
as necessary, but specify a time at which this information was "gathered_at".
+
+Share Server Migration (Since Victoria)
+---------------------------------------
+
+Shares servers can be migrated between different backends. Driver vendors
+need to implement the share server migration functions in order to migrate
+share servers in an efficient way.
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index 2825536471..0bc2c636b3 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -97,6 +97,7 @@ Module Reference
share_replication
driver_filter_goodness_weigher
share_migration
+ share_server_migration
.. only:: html
diff --git a/doc/source/contributor/share_server_migration.rst b/doc/source/contributor/share_server_migration.rst
new file mode 100644
index 0000000000..8486e3c5aa
--- /dev/null
+++ b/doc/source/contributor/share_server_migration.rst
@@ -0,0 +1,241 @@
+======================
+Share Server Migration
+======================
+
+As of the Victoria release of OpenStack, Manila supports migration of share
+servers across different pools through an experimental API. This developer
+document reflects the latest version of the experimental Share Server Migration
+API.
+
+Feature definition
+~~~~~~~~~~~~~~~~~~
+
+The Share Server Migration API is an administrator-only API that allows the
+invoker to select a destination backend to migrate a share server to, while
+still allowing clients to access the source share server resources during the
+migration. Migration of data is expected to be disruptive for users accessing
+the source, because at some point it will cease to exist. For this reason, the
+share server migration feature is implemented in a 2-phase approach, for the
+purpose of controlling the timing of that expected disruption of migrating
+share servers.
+
+The first phase of the migration is when operations that take the longest are
+performed, such as data copying or replication. After the first phase of data
+copying is complete, it is up to the administrator to trigger the second phase,
+often referred to as switchover phase, which may perform operations such as a
+last sync and changing the source share server to inactive.
+
+During the data copy phase, users remain connected to the source, and may have
+to reconnect after the switchover phase.
+
+Share server migration only supports driver-assisted migration. This
+mechanism uses the underlying driver running in the manila-share service node
+to coordinate the migration. The migration is performed directly in the
+storage. In order to use this mechanism, the driver should implement this
+functionality. Also, the driver managing the destination back end should
+support driver-assisted migration.
+Typically, drivers would be able to assist migration of share servers within
+storage systems from the same vendor. It is likely that this will be the most
+efficient and reliable mechanism to migrate a given share server, as the
+storage back end may be able to migrate the share server while remaining
+writable, snapshots, and possibly perform this operation non-disruptively.
+
+Note that during a share server migration, access rules cannot be added or
+removed. Also, it is not possible to modify existent access rules for
+shares and share snapshots created upon the share server being migrated.
+
+API description
+~~~~~~~~~~~~~~~
+
+The migration of a share server is started by invoking the
+``migration_start`` API. The parameters are:
+
+**share_server_id**
+ The share server to be migrated. This parameter is mandatory.
+
+**destination**
+ The destination backend in ``host@backend`` representation. This parameter
+ is mandatory.
+
+**preserve_snapshots**
+ Specifies whether migration should enforce the preservation of all existing
+ snapshots at the destination. In other words, the existing snapshots must
+ be migrated along with the share server data. When this behavior is
+ expected (i.e, this parameter is set to `True`) and drivers are not capable
+ of migrating the snapshots, migration will result in an error status.
+ This parameter is mandatory.
+
+**nondisruptive**
+ Specifies whether the migration should only be performed without disrupting
+ clients during migration. For such, it is also expected that the export
+ location does not change. When this behavior is expected (i.e, this
+ parameter is set to `True`) and drivers are not capable of allowing the
+ share server shares to remain accessible through the two phases of the
+ migration, migration will result in an error status. This parameter
+ is mandatory.
+
+**writable**
+ Specifies whether migration should only be performed if the share server
+ shares can remain writable. When this behavior is expected
+ (i.e, this parameter is set to `True`) and drivers are not capable of
+ allowing the share server shares 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 server shares
+ will remain writable through the data copy phase of migration.
+ However, during the switchover phase the shares will be re-exported at the
+ destination, causing the share to be rendered inaccessible for the duration
+ of this phase. This parameter is mandatory.
+
+**new_share_network_id**
+ If willing to change the share server's share-network so it can be
+ allocated in the desired destination backend, the invoker may supply a new
+ share network to be used. This is often suited when the share server is to
+ be migrated to a backend which operates in a different availability zone or
+ managed by a driver that handles share servers. This parameter is optional.
+
+After started, a migration may be cancelled through the ``migration_cancel``
+API, have its status obtained through the ``migration_get_progress`` API, and
+completed through the ``migration_complete`` API after reaching a certain state
+(see ``Workflows`` section below).
+
+Workflows
+~~~~~~~~~
+
+Upon invoking ``migration_start``, several validations will be performed by
+the API layer, such as:
+
+* If supplied API parameters are valid.
+
+* If share server status is `active`.
+
+* If there are share groups related to the share server.
+
+* If a new share network id was provided and is compatible with the
+ destination.
+
+* If a new host and share network id were provided and they're different from
+ the source share server.
+
+* If the share server to be migrated serves as destination to another share
+ server.
+
+* If all the availability zones match with all shares' share types within the
+ share server.
+
+* If the share server's shares do not have replicas.
+
+* If the share server's shares are not member of a share group.
+
+* If the access rules of the given share server's shares are not in error
+ status.
+
+* If the snapshots of all share server shares are in `available` state.
+
+* If the destination backend chosen to migrate the share server to exists, as
+ well as it and its share service are running.
+
+If any of the above validations fail, the API will return an error. Otherwise,
+the `task_state` field value will transition to `migration_starting` and the
+share server's status will transition to `server_migrating`. Past this point,
+all validations, state transitions and errors will not produce any
+notifications to the user. Instead, the given share server's `task_state`
+field value will transition to `migration_error`.
+
+Right after the API validations, a driver call will be performed in the
+destination backend in order to validate if the destination host is compatible
+within the requested operation. The driver will then determine the
+compatibility between source and destination hosts for the share server
+migration.
+
+A new share server will be created in the database, referred to as the
+"destination share server", with a status field value `server_migrating_to`.
+
+Share server migration data copy phase
+--------------------------------------
+
+A share server will be created as needed at the destination backend. Then, the
+share server details are provided to the driver to report the set of migration
+capabilities for this destination. If the API parameters `writable`,
+`nondisruptive`, `preserve_metadata` and `preserve_snapshots` are satisfied by
+the reported migration capabilities, the `task_state` field value transitions
+to `migration_driver_starting` and the driver is invoked to start the
+migration.
+
+The driver's ``share_server_migration_start`` method should start a job in
+the storage back end and return, allowing the `task_state` field value to
+transition to `migration_driver_in_progress`. If any of the API parameters
+described previously are not satisfied, or the driver raises an exception in
+`share_server_migration_start`, the migration ends setting the `task_state`
+field value to `migration_error`, and the created share server will have its
+status set to error.
+
+Once the ``share_server_migration_start`` driver method succeeds, a periodic
+task that checks for shares with `task_state` field value
+`migration_driver_in_progress` will invoke the driver's
+``share_server_migration_continue`` method, responsible for executing the next
+steps of migration until the data copy phase is completed, transitioning the
+`task_state` field value to `migration_driver_phase1_done`. If this step fails,
+the `task_state` field value transitions to `migration_error` and all allocated
+resources will be cleaned up.
+
+Share server migration switchover phase
+---------------------------------------
+
+When invoked, the `task_state` field value transitions to
+`migration_completing`. In this phase, these operations will happen:
+* The source share instances are deleted
+* The source share server will have its status set to inactive
+* The access rules are applied to the shares of the destination share server
+* A final sync is also performed.
+
+At last, the `task_state` field value transitions to
+`migration_success`. If the `nondisruptive` capability is not
+supported, the export locations will change and clients will need to remount
+the shares.
+
+Driver interfaces
+~~~~~~~~~~~~~~~~~
+
+All drivers that implement the migration mechanism should be able to perform
+all required steps from the source share server back end within the
+implementation of the interfaces listed in the section below.
+Those steps include:
+
+* Validating compatibility and connectivity between the source and destination
+ back end;
+
+* Start the migration job in the storage back end. Return after the job request
+ has been submitted;
+
+* Subsequent invocations to the driver to monitor the job status.
+
+* Complete migration by performing a last sync if necessary and delete the
+ original shares from the source back end.
+
+.. note::
+ The implementation of the ``share_server_migration_cancel`` and
+ ``share_server_migration_get_progress`` operations is not mandatory. If the
+ driver is able to perform such operations, make sure to set
+ ``share_server_migration_cancel`` and
+ ``share_server_migration_get_progress`` equal to ``True`` in the response of
+ the ``share_server_migration_check`` operation.
+
+Additional notes
+~~~~~~~~~~~~~~~~
+
+* In case of an error in the storage back end during the execution of the
+ migration job, the driver should raise an exception within the
+ ``share_server_migration_continue`` method.
+
+* If the manila-share service is restarted during a migration, the driver's
+ ``share_server_migration_continue`` will be invoked periodically with an
+ interval configured in the share manager service
+ (``share_server_migration_driver_continue_interval``). The invocation
+ will stop when the driver finishes the data copy phase.
+
+Share Server Migration interfaces:
+----------------------------------
+
+.. autoclass:: manila.share.driver.ShareDriver
+ :noindex:
+ :members: share_server_migration_check_compatibility, share_server_migration_start, share_server_migration_continue, share_server_migration_complete, share_server_migration_cancel, share_server_migration_get_progress