d5b539be36
This cleans up the cases where we had D001 violations so we can stop skipping that check in doc8 runs. Change-Id: Ie52f6ecac1a645fcbcc643b9ca63e033b622d830 Signed-off-by: Sean McGinnis <sean.mcginnis@gmail.com>
304 lines
12 KiB
ReStructuredText
304 lines
12 KiB
ReStructuredText
..
|
|
Copyright (c) 2015 OpenStack Foundation
|
|
All Rights Reserved.
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
Migration
|
|
=========
|
|
|
|
Introduction to volume migration
|
|
--------------------------------
|
|
Cinder provides the volume migration support within the same deployment,
|
|
which means the node of cinder volume service, c-vol node where the
|
|
source volume is located, is able to access the c-vol node where
|
|
the destination volume is located, and both of them share the same
|
|
Cinder API service, scheduler service, message queue service, etc.
|
|
|
|
As a general rule migration is possible for volumes in 'available' or
|
|
'in-use' status, for the driver which has implemented volume migration.
|
|
So far, we are confident that migration will succeed for 'available'
|
|
volumes, whose drivers implement the migration routines. However,
|
|
the migration of 'in-use' volumes is driver dependent. It depends on
|
|
different drivers involved in the operation. It may fail depending on
|
|
the source or destination driver of the volume.
|
|
|
|
For example, from RBD to LVM, the migration of 'in-use' volume will
|
|
succeed, but from LVM to RBD, it will fail.
|
|
|
|
There are two major scenarios, which volume migration supports
|
|
in Cinder:
|
|
|
|
Scenario 1: Migration between two back-ends with the same volume type,
|
|
regardless if they are located on the same c-vol node or not.
|
|
|
|
Scenario 2: Migration between two back-ends with different volume types,
|
|
regardless if the back-ends are located on the same c-vol node or not.
|
|
|
|
|
|
How to do volume migration via CLI
|
|
----------------------------------
|
|
Scenario 1 of volume migration is done via the following command from
|
|
the CLI::
|
|
|
|
cinder migrate [--force-host-copy [<True|False>]]
|
|
[--lock-volume [<True|False>]]
|
|
<volume> <host>
|
|
|
|
Mandatory arguments:
|
|
<volume> ID of volume to migrate.
|
|
<host> Destination host. The format of host is
|
|
host@backend#POOL, while 'host' is the host
|
|
name of the volume node, 'backend' is the back-end
|
|
name and 'POOL' is a logical concept to describe
|
|
a set of storage resource, residing in the
|
|
back-end. If the back-end does not have specified
|
|
pools, 'POOL' needs to be set with the same name
|
|
as 'backend'.
|
|
|
|
Optional arguments:
|
|
--force-host-copy [<True|False>]
|
|
Enables or disables generic host-based force-
|
|
migration, which bypasses the driver optimization.
|
|
Default=False.
|
|
--lock-volume [<True|False>]
|
|
Enables or disables the termination of volume
|
|
migration caused by other commands. This option
|
|
applies to the available volume. True means it locks
|
|
the volume state and does not allow the migration to
|
|
be aborted. The volume status will be in maintenance
|
|
during the migration. False means it allows the volume
|
|
migration to be aborted. The volume status is still in
|
|
the original status. Default=False.
|
|
|
|
Important note: Currently, error handling for failed migration operations is
|
|
under development in Cinder. If we would like the volume migration to finish
|
|
without any interruption, please set --lock-volume to True. If it is set
|
|
to False, we cannot predict what will happen, if other actions like attach,
|
|
detach, extend, etc, are issued on the volume during the migration.
|
|
It all depends on which stage the volume migration has reached and when the
|
|
request of another action comes.
|
|
|
|
|
|
Scenario 2 of volume migration can be done via the following command
|
|
from the CLI::
|
|
|
|
cinder retype --migration-policy on-demand
|
|
<volume> <volume-type>
|
|
Mandatory arguments:
|
|
<volume> Name or ID of volume for which to modify type.
|
|
<volume-type> New volume type.
|
|
|
|
Source volume type and destination volume type must be different and
|
|
they must refer to different back-ends.
|
|
|
|
|
|
Configurations
|
|
--------------
|
|
To set up an environment to try the volume migration, we need to
|
|
configure at least two different back-ends on the same node of cinder
|
|
volume service, c-vol node or two back-ends on two different volume
|
|
nodes of cinder volume service, c-vol nodes. Which command to use,
|
|
'cinder migrate' or 'cinder retype', depends on which type of volume
|
|
we would like to test.
|
|
|
|
**Scenario 1 for migration**
|
|
|
|
To configure the environment for Scenario 1 migration, e.g. a
|
|
volume is migrated from back-end <driver-backend> on Node 1 to back-end
|
|
<driver-backend> on Node 2, cinder.conf needs to contains the following
|
|
entries for the same back-end on both of source and the destination
|
|
nodes:
|
|
|
|
For Node 1:
|
|
...
|
|
[<driver-backend>]
|
|
volume_driver=xxxx
|
|
volume_backend_name=<driver-backend>
|
|
...
|
|
|
|
For Node 2:
|
|
...
|
|
[<driver-backend>]
|
|
volume_driver=xxxx
|
|
volume_backend_name=<driver-backend>
|
|
...
|
|
|
|
If a volume with a predefined volume type is going to migrate,
|
|
the back-end drivers from Node 1 and Node 2 should have the same
|
|
value for volume_backend_name, which means <driver-backend> should be
|
|
the same for Node 1 and Node 2. The volume type can be created
|
|
with the extra specs {volume_backend_name: driver-biz}.
|
|
|
|
If we are going to migrate a volume with a volume type of none, it
|
|
is not necessary to set the same value to volume_backend_name for
|
|
both Node 1 and Node 2.
|
|
|
|
**Scenario 2 for migration**
|
|
|
|
To configure the environment for Scenario 2 migration:
|
|
For example, a volume is migrated from driver-biz back-end on Node 1
|
|
to driver-net back-end on Node 2, cinder.conf needs to contains
|
|
the following entries:
|
|
|
|
For Node 1:
|
|
...
|
|
[driver-biz]
|
|
volume_driver=xxxx
|
|
volume_backend_name=driver-biz
|
|
...
|
|
|
|
For Node 2:
|
|
...
|
|
[driver-net]
|
|
volume_driver=xxxx
|
|
volume_backend_name=driver-net
|
|
...
|
|
|
|
For example, a volume is migrated from driver-biz back-end on Node 1
|
|
to driver-biz back-net on the same node, cinder.conf needs to
|
|
contains the following entries:
|
|
|
|
...
|
|
[driver-biz]
|
|
volume_driver=xxxx
|
|
volume_backend_name=driver-biz
|
|
...
|
|
|
|
...
|
|
[driver-net]
|
|
volume_driver=xxxx
|
|
volume_backend_name=driver-net
|
|
...
|
|
|
|
Two volume types need to be created. One is with the extra specs:
|
|
{volume_backend_name: driver-biz}. The other is with the extra specs:
|
|
{volume_backend_name: driver-net}.
|
|
|
|
|
|
What can be tracked during volume migration
|
|
-------------------------------------------
|
|
The volume migration is an administrator only action and it may take
|
|
a relatively long time to finish. The property 'migration status' will
|
|
indicate the stage of the migration process for the volume. The
|
|
administrator can check the 'migration status' via the 'cinder list'
|
|
or 'cinder show <volume-id>' command. The 'cinder list' command presents
|
|
a list of all the volumes with some properties displayed, including the
|
|
migration status, only to the administrator. However, the migration status
|
|
is not included if 'cinder list' is issued by an ordinary user. The
|
|
'cinder show <volume-id>' will present all the detailed information of a
|
|
specific volume, including the migration status, only to the administrator.
|
|
|
|
If the migration status of a volume shows 'starting', 'migrating' or
|
|
'completing', it means the volume is in the process of a migration.
|
|
If the migration status is 'success', it means the migration has finished
|
|
and the previous migration of this volume succeeded. If the
|
|
migration status is 'error', it means the migration has finished and
|
|
the previous migration of this volume failed.
|
|
|
|
|
|
How to implement volume migration for a back-end driver
|
|
-------------------------------------------------------
|
|
There are two kinds of implementations for the volume migration currently
|
|
in Cinder.
|
|
|
|
The first is the generic host-assisted migration, which consists of two
|
|
different transfer modes, block-based and file-based. This implementation
|
|
is based on the volume attachment to the node of cinder volume service,
|
|
c-vol node. Any back-end driver supporting iSCSI will be able to support
|
|
the generic host-assisted migration for sure. The back-end driver without
|
|
iSCSI supported needs to be tested to decide if it supports this kind of
|
|
migration. The block-based transfer mode is done by 'dd' command,
|
|
applying to drivers like LVM, Storwize, etc, and the file-based transfer
|
|
mode is done by file copy, typically applying to the RBD driver.
|
|
|
|
The second is the driver specific migration.
|
|
Since some storage back-ends have their special commands to copy the volume,
|
|
Cinder also provides a way for them to implement in terms of their own
|
|
internal commands to migrate.
|
|
|
|
If the volume is migrated between two nodes configured with the same
|
|
storage back-end, the migration will be optimized by calling the method
|
|
migrate_volume in the driver, if the driver provides an implementation for
|
|
it to migrate the volume within the same back-end, and will fallback to
|
|
the generic host-assisted migration provided in the manager, if no such
|
|
implementation is found or this implementation is not applicable for
|
|
this migration.
|
|
|
|
If your storage driver in Cinder provides iSCSI support, it should
|
|
naturally work under the generic host-assisted migration, when
|
|
--force-host-copy is set to True from the API request. Normally you
|
|
do not need to change any code, unless you need to transfer the volume
|
|
from your driver via a different way from the block-based transfer
|
|
or the file-based transfer.
|
|
|
|
If your driver uses a network connection to communicate the block data
|
|
itself, you can use file I/O to participate in migration. Please take
|
|
the RBD driver as a reference for this implementation.
|
|
|
|
If you would like to implement a driver specific volume migration for
|
|
your driver, the API method associated with the driver specific migration
|
|
is the following admin only method::
|
|
|
|
migrate_volume(self, ctxt, volume, host)
|
|
|
|
If your driver is taken as the destination back-end for a generic host-assisted
|
|
migration and your driver needs to update the volume model after a successful
|
|
migration, you need to implement the following method for your driver::
|
|
|
|
update_migrated_volume(self, ctxt, volume, new_volume, original_volume_status)
|
|
|
|
|
|
Required methods
|
|
----------------
|
|
There is one mandatory method that needs to be implemented for
|
|
the driver to implement the driver specific volume migration.
|
|
|
|
**migrate_volume**
|
|
|
|
Used to migrate the volume directly if source and destination are
|
|
managed by same storage.
|
|
|
|
There is one optional method that could be implemented for
|
|
the driver to implement the generic host-assisted migration.
|
|
|
|
**update_migrated_volume**
|
|
|
|
Used to return the key-value pairs to update the volume model after
|
|
a successful migration. The key-value pairs returned are supposed to
|
|
be the final values your driver would like to be in the volume model,
|
|
if a migration is completed.
|
|
|
|
This method can be used in a generally wide range, but the most common
|
|
use case covered in this method is to rename the back-end name to the
|
|
original volume id in your driver to make sure that the back-end still
|
|
keeps the same id or name as it is before the volume migration. For
|
|
this use case, there are two important fields: _name_id and
|
|
provider_location.
|
|
|
|
The field _name_id is used to map the cinder volume id and the back-end
|
|
id or name. The default value is None, which means the cinder
|
|
volume id is the same to the back-end id or name. If they are different,
|
|
_name_id is used to saved the back-end id or name.
|
|
|
|
The field provider_location is used to save the export information,
|
|
created by the volume attach. This field is optional, since some drivers
|
|
support the export creation and some do not. It is the driver
|
|
maintainer's responsibility to decide what this field needs to be.
|
|
|
|
If the back-end id or name is renamed successfully, this method can
|
|
return {'_name_id': None, 'provider_location': None}. It is the choice
|
|
for your driver to implement this method and decide what use cases should
|
|
be covered.
|
|
|