====================== 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