Share migration is the feature that migrates a share between different storage pools.
As an administrator, you may want to migrate your share from one storage pool to another for several reasons. Examples include:
Moving shares across different storage pools is generally expected to be a disruptive operation that disconnects existing clients when the source ceases to exist. For this reason, share migration is implemented in a 2-phase approach that allows the administrator to control the timing of the disruption. The first phase performs data copy while users retain access to the share. When copying is complete, the second phase may be triggered to perform a switchover that may include a last sync and deleting the source, generally requiring users to reconnect to continue accessing the share.
In order to migrate a share, one of two possible mechanisms may be employed, which provide different capabilities and affect how the disruption occurs with regards to user access during data copy phase and disconnection during switchover phase. Those two mechanisms are:
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.
The commands to interact with the share migration API are:
migration_start: starts a migration while retaining access to the share.
Migration is paused and waits for
migration_complete invocation when it
has copied all data and is ready to take down the source share.
$ manila migration-start share_1 ubuntu@generic2#GENERIC2 --writable False --preserve-snapshots False --preserve-metadata False --nondisruptive False
This command has no output.
migration_complete: completes a migration, removing the source share and
setting the destination share instance to
$ manila migration-complete share_1
This command has no output.
migration_get_progress: obtains migration progress information of a
$ manila migration-get-progress share_1 +----------------+--------------------------+ | Property | Value | +----------------+--------------------------+ | task_state | data_copying_in_progress | | total_progress | 37 | +----------------+--------------------------+
migration_cancel: cancels an in-progress migration of a share.
$ manila migration-cancel share_1
This command has no output.
To start a migration, an administrator should specify several parameters. Among those, two of them are key for the migration.
share: The share that will be migrated.
destination_pool: The destination pool to which the share should be migrated to, in format host@backend#pool.
Several other parameters, referred to here as
must be specified in the
migration_start API. They are:
preserve_metadata: whether preservation of filesystem metadata should be enforced for this migration.
preserve_snapshots: whether preservation of snapshots should be enforced for this migration.
writable: whether the source share remaining writable should be enforced for this migration.
nondisruptive: whether it should be enforced to keep clients connected throughout the migration.
Specifying any of the boolean parameters above as
True will disallow a
In order to appropriately move a share to a different storage pool, it may be required to change one or more share properties, such as the share type, share network, or availability zone. To accomplish this, use the optional parameters:
new_share_type_id: Specify the ID of the share type that should be set in the migrated share.
new_share_network_id: Specify the ID of the share network that should be set in the migrated share.
If driver-assisted migration should not be attempted, you may provide the optional parameter:
force_host_assisted_migration: whether driver-assisted migration attempt should be skipped. If this option is set to
True, all driver-assisted options must be set to
For share migration to work in the cloud, there are several configuration requirements that need to be met:
For driver-assisted migration: it is necessary that the configuration of all back end stanzas is present in the file manila.conf of all manila-share nodes. Also, network connectivity between the nodes running manila-share service and their respective storage back ends is required.
For host-assisted migration: it is necessary that the Data Service
(manila-data) is installed and configured in a node connected to the cloud’s
administrator network. The drivers pertaining to the source back end and
destination back end involved in the migration should be able to provide shares
that can be accessed from the administrator network. This can easily be
accomplished if the driver supports
admin_only export locations, else it is
up to the administrator to set up means of connectivity.
In order for the Data Service to mount the source and destination instances, it must use manila share access APIs to grant access to mount the instances. The access rule type varies according to the share protocol, so there are a few config options to set the access value for each type:
data_node_access_ip: For IP-based access type, provide the value of the IP of the Data Service node in the administrator network. For NFS shares, drivers should always add rules with the “no_root_squash” property.
data_node_access_cert: For certificate-based access type, provide the value of the certificate name that grants access to the Data Service.
data_node_access_admin_user: For user-based access type, provide the value of a username that grants access and administrator privileges to the files in the share.
data_node_mount_options: Provide the value of a mapping of protocol name to respective mount options. The Data Service makes use of mount command templates that by default have a dedicated field to inserting mount options parameter. The default value for this config option already includes the username and password parameters for CIFS shares and NFS v3 enforcing parameter for NFS shares.
mount_tmp_location: Provide the value of a string representing the path where the share instances used in migration should be temporarily mounted. The default value is
check_hash: This boolean config option value determines whether the hash of all files copied in migration should be validated. Setting this option increases the time it takes to migrate files, and is recommended for ultra-dependable systems. It defaults to disabled.
The configuration options above are respective to the Data Service only and
should be defined the
DEFAULT group of the
file. Also, the Data Service node must have all the protocol-related libraries
pre-installed to be able to run the mount commands for each protocol.
You may need to change some driver-specific configuration options from their
default value to work with specific drivers. If so, they must be set under the
driver configuration stanza in
manila.conf. See a detailed description for
each one below:
migration_ignore_files: Provide value as a list containing the names of
files or folders to be ignored during migration for a specific driver. The
default value is a list containing only
share_mount_template: Provide a string that defines the template for the
mount command for a specific driver. The template should contain the
following entries to be formatted by the code:
The default value for this config option is:
mount -vt %(proto)s %(options)s %(export)s %(path)s.
share_unmount_template: Provide the value of a string that defines the
template for the unmount command for a specific driver. The template should
contain the path of where the shares are mounted, according to the
mount_tmp_location config option, to be formatted automatically by the
Data Service. The default value for this config option is:
umount -v %(path)s
protocol_access_mapping: Provide the value of a mapping of access rule
type to protocols supported. The default value specifies IP and user based
access types mapped to NFS and CIFS respectively, which are the combinations
supported by manila. If a certain driver uses a different protocol for IP or
user access types, or is not included in the default mapping, it should be
specified in this configuration option.
migratingand it will block other share actions, such as adding or removing access rules, creating or deleting snapshots, resizing, among others.
access-listAPI. This access rule should not be tampered with, it will otherwise cause migration to fail.
task_statepresent in the Share model. If for any reason the state is not set to
migration_errorduring a failure, it will need to be reset using the
task_statefield value starts with
data_copying_). In other steps of the host-assisted migration, both the source and destination manila-share services should not be restarted.
migration_driver_in_progress, while the copy is being done in the back end. Otherwise, the source and destination manila-share services should not be restarted.