taikun.cloud

Taikun Logo
Request Demo
Sign Up
Sign In

Taikun OCP Guide

Table of Contents

Share migration

Share migration is the feature that migrates a share between
different storage pools.

Use cases

As an administrator, you may want to migrate your share from one
storage pool to another for several reasons. Examples include:

  • Maintenance or evacuation
    • Evacuate a back end for hardware or software upgrades
    • Evacuate a back end experiencing failures
    • Evacuate a back end which is tagged end-of-life
  • Optimization
    • Defragment back ends to empty and be taken offline to conserve
      power
    • Rebalance back ends to maximize available performance
    • Move data and compute closer together to reduce network utilization
      and decrease latency or increase bandwidth
  • Moving shares
    • Migrate from old hardware generation to a newer generation
    • Migrate from one vendor to another

Migration workflows

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:

  • Driver-assisted migration: This mechanism is intended to make use of
    driver optimizations to migrate shares between pools of the same storage
    vendor. This mechanism allows migrating shares nondisruptively while the
    source remains writable, preserving all filesystem metadata and
    snapshots. The migration workload is performed in the storage back
    end.
  • Host-assisted migration: This mechanism is intended to migrate
    shares in an agnostic manner between two different pools, regardless of
    storage vendor. The implementation for this mechanism does not offer the
    same properties found in driver-assisted migration. In host-assisted
    migration, the source remains readable, snapshots must be deleted prior
    to starting the migration, filesystem metadata may be lost, and the
    clients will get disconnected by the end of migration. The migration
    workload is performed by the Data Service, which is a dedicated manila
    service for intensive data operations.

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.

Using the migration APIs

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

    Note

    This command has no output.

  • migration_complete: completes a migration, removing
    the source share and setting the destination share instance to
    available.

    $ manila migration-complete share_1

    Note

    This command has no output.

  • migration_get_progress: obtains migration progress
    information of a share.

    $ 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

    Note

    This command has no output.

The parameters

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
driver-assisted parameters, 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 host-assisted migration.

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
    False.

Configuration

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_ips: For IP-based access type, provide
    one or more administrator network IP addresses of the host running the
    Data Service. 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 /tmp/.
  • 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
manila.conf configuration 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
    lost+found folder.

  • 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:

    • proto: The share protocol. Automatically formatted by the Data
      Service.
    • options: The mount options to be formatted by the Data Service
      according to the data_node_mount_options config option.
    • export: The export path of the share. Automatically formatted by the
      Data Service with the share’s admin_only export
      location.
    • path: The path to mount the share. Automatically formatted by the
      Data Service according to the mount_tmp_location config option.

    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.

Other remarks

  • There is no need to manually add any of the previously existing
    access rules after a migration is complete, they will be persisted on
    the destination after the migration.
  • Once migration of a share has started, the user will see the status
    migrating and it will block other share actions, such as
    adding or removing access rules, creating or deleting snapshots,
    resizing, among others.
  • The destination share instance export locations, although it may
    exist from the beginning of a host-assisted migration, are not visible
    nor accessible as access rules cannot be added.
  • During a host-assisted migration, an access rule granting access to
    the Data Service will be added and displayed by querying the
    access-list API. This access rule should not be tampered
    with, it will otherwise cause migration to fail.
  • Resources allocated are cleaned up automatically when a migration
    fails, except if this failure occurs during the 2nd phase of a
    driver-assisted migration. Each step in migration is saved to the field
    task_state present in the Share model. If for any reason
    the state is not set to migration_error during a failure,
    it will need to be reset using the reset-task-state
    API.
  • It is advised that the node running the Data Service is well
    secured, since it will be mounting shares with highest privileges,
    temporarily exposing user data to whoever has access to this node.
  • The two mechanisms of migration are affected differently by service
    restarts:

    • If performing a host-assisted migration, all services may be
      restarted except for the manila-data service when performing the copy
      (the task_state field 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.
    • If performing a driver-assisted migration, the migration is affected
      minimally by driver restarts if the task_state is
      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.