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
This commit is contained in:
silvacarloss
parent
52c926e32c
commit
281b7dd1cd
@ -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.
|
||||
|
||||
@ -97,6 +97,7 @@ Module Reference
|
||||
share_replication
|
||||
driver_filter_goodness_weigher
|
||||
share_migration
|
||||
share_server_migration
|
||||
|
||||
.. only:: html
|
||||
|
||||
|
||||
241
doc/source/contributor/share_server_migration.rst
Normal file
241
doc/source/contributor/share_server_migration.rst
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user