"Fossies" - the Fresh Open Source Software Archive

Member "manila-11.0.1/doc/source/admin/shared-file-systems-share-server-migration.rst" (1 Feb 2021, 19795 Bytes) of package /linux/misc/openstack/manila-11.0.1.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "shared-file-systems-share-server-migration.rst": 11.0.1_vs_12.0.0.

Share server migration

Share server migration is a functionality that lets administrators migrate a share server, and all its shares and snapshots, to a new destination.

As with share migration, a 2-phase approach was implemented for share server migration, which allows to control the right time to complete the operation, that usually ends on clients disruption.

The process of migrating a share server involves different operations over the share server, but can be achieved by invoking two main operations: "start" and "complete". You'll need to begin with the "start" operation and wait until the service has completed the first phase of the migration to call the "complete" operation. When a share server is undergoing the first phase, it's possible to choose to "cancel" it, or get a report of the progress.

A new operation called "migration check" is available to assist on a pre-migration phase, by validating within the destination host if the migration can or not be completed, providing an output with the compatible capabilities supported by the driver.

Share server migration is driven by share drivers, which means that both source and destination backends must support this functionality, and the driver must provide such operation in an efficient way.

Server migration workflows

Before actually starting the migration, you can use the operation migration_check <share_server_migration_check_cli> to verify if the destination host and the requested capabilities are supported by the driver. If the answer is compatible equal to True, you can proceed with the migration process, otherwise you'll need to identify the conflicting parameters or, in more complex scenarios, search for messages directly in the manila logs. The available capabilities are: writable, nondisruptive, preserve_snapshots and new_share_network_id, which are detailed in shared_file_systems_share_server_migration_parameters.

The migration process starts by invoking the migration_start <share_server_migration_start_cli> operation for a given share server. This operation will start the first phase of the migration that copies all data, from source to destination, including all shares, their access rules and even snapshots if supported by the driver controlling the destination host.

For all ongoing migrations, you can optionally request the current status of a share server migration using migration_get_progress <share_server_migration_get_progress_cli> operation to retrieve the total progress of the data copy and its current task state. If supported by the driver, you can also cancel this operation by issuing migration_cancel <share_server_migration_cancel_cli> and wait until all status become active and available again.

After completing the data copy, the first phase is completed and the next operation, migration_complete <share_server_migration_complete_cli>, can be initiated to finish the migration. The migration_complete <share_server_migration_complete_cli> operation usually disrupts clients access, since the export locations of the shares will change. The new export locations will be derived from the new share server that is provisioned at the destination, which is instantiated with distinct network allocations.

A new field task_state is available in the share server model to help track which operation is being executed during this process. The following tables show, for each phase, the expected task_state, along with their order of execution and a brief description of the actions that are being executed in the back end.

Share server migration states - 1st phase
Sequence task_state Description



All initial validations passed, all shares and snapshots can't be modified until the end of the migration.



The destination host started the process of migration. If the driver doesn't support remain writable, all access rules are modified to read only.



The driver was called to initiate the process of migrating the share server. Manila will wait for driver's answer.



The driver accepted the request and started copying the data to the new share server. It will remain in this state until the end of the data copy.



Driver finished copying the data and it's ready to complete the migration.

Along with the share server migration progress (in percentage) and the the current task state, the API also provides the destination share server ID. Alternatively, you may check the destination share server ID by querying the share server for a source_share_server_id set to the ID of the share server being migrated. During the entire migration process, the source source share server will remain with server_migrating status while the destination share server will remain with server_migrating_to status.

If an error occurs during the 1st phase of the migration, the source share server has its status reverted to active again, while the destination server has its status set to error. Both share servers will have their task_state updated to migration_error. All shares and snapshots are updated to available and any read-only rules are reset to allow writing into the shares.

Share server migration states - 2nd phase
Sequence task_state Description



The destination host started processing the operation and the driver is called to complete the share server migration.



The migration was completed with success. All shares and snapshots are available again.

After finishing the share server migration, all shares and snapshots have their status updated to available. The source share server status is set to inactive and the destination share server to active.

If an error occurs during the 2nd phase of the migration, both source and destination share servers will have their status updated to error, along with their shares and snapshots, since it's not possible to infer if they are working properly and the current status of the migration. In this scenario, you will need to manually verify the health of all share server's resources and manually fix their statuses. Both share servers will have their task_state set to migration_error.

Share server migration states - migration cancel
Sequence task_state Description



The destination host started the cancel process. It will remain in this state until the driver finishes all tasks that are in progress.



The migration was successfully cancelled.

If an error occurs during the migration cancel operation, the source share server has its status reverted to active again, while the destination server has its status updated to error. Both share servers will have their task_state set to migration_error. All shares and snapshots have their statuses updated to available.

Using share server migration CLI

The available commands to interact with the share server migration API are the following:

Migration check and migration start parameters

Share server migration_check <share_server_migration_check_cli> and migration_start <share_server_migration_start_cli> operations have specific parameters that have the semantic detailed below. From these, only new_share_network stands as an optional parameter.

In order to appropriately move a share server to a different host, it may be required to change the destination share network to be used by the new share server. In this case, a new share network can be provided using the following optional parameter:


For share server migration to work it is necessary to have compatible back end stanzas present in the manila configuration of all manila-share nodes.

Some drivers may provide some driver-specific configuration options that can be changed to adapt to specific workload. Check share_drivers documentation for more details.

Important notes