doc/design-disk-conversion.rst - ganeti - Git at Google

 =================================
 Conversion between disk templates
 =================================

 .. contents:: :depth: 4

 This design document describes the support for generic disk template
 conversion in Ganeti. The logic used is disk template agnostic and
 targets to cover the majority of conversions among the supported disk
 templates.


 Current state and shortcomings
 ==============================

 Currently, Ganeti supports choosing among different disk templates when
 creating an instance. However, converting the disk template of an
 existing instance is possible only between the ``plain`` and ``drbd``
 templates. This feature was added in Ganeti since its early versions
 when the number of supported disk templates was limited. Now that Ganeti
 supports plenty of choices, this feature should be extended to provide
 more flexibility to the user.

 The procedure for converting from the plain to the drbd disk template
 works as follows. Firstly, a completely new disk template is generated
 matching the size, mode, and the count of the current instance's disks.
 The missing volumes are created manually both in the primary (meta disk)
 and the secondary node. The original LVs running on the primary node are
 renamed to match the new names. The last step is to manually associate
 the DRBD devices with their mirror block device pairs. The conversion
 from the drbd to the plain disk template is much simpler than the
 opposite. Firstly, the DRBD mirroring is manually disabled. Then the
 unnecessary volumes including the meta disk(s) of the primary node, and
 the meta and data disk(s) from the previously secondary node are
 removed.


 Proposed changes
 ================

 This design proposes the creation of a unified interface for handling
 the disk template conversions in Ganeti. Currently, there is no such
 interface and each one of the supported conversions uses a separate code
 path.

 This proposal introduces a single, disk-agnostic interface for handling
 the disk template conversions in Ganeti, keeping in mind that we want it
 to be as generic as possible. An exception case will be the currently
 supported conversions between the LVM-based disk templates. Their basic
 functionality will not be affected and will diverge from the rest disk
 template conversions. The target is to provide support for conversions
 among the majority of the available disk templates, and also creating
 a mechanism that will easily support any new templates that may be
 probably added in Ganeti, at a future point.


 Design decisions
 ================

 Currently, the supported conversions for the LVM-based templates are
 handled by the ``LUInstanceSetParams`` LU. Our implementation will
 follow the same approach. From a high-level point-of-view this design
 can be split in two parts:

 * The extension of the LU's checks to cover all the supported template
   conversions

 * The new functionality which will be introduced to provide the new
   feature

 The instance must be stopped before starting the disk template
 conversion, as it currently is, otherwise the operation will fail. The
 new mechanism will need to copy the disk's data for the conversion to be
 possible. We propose using the Unix ``dd`` command to copy the
 instance's data. It can be used to copy data from source to destination,
 block-by-block, regardless of their filesystem types, making it a
 convenient tool for the case. Since the conversion will be done via data
 copy it will take a long time for bigger disks to copy their data and
 consequently for the instance to switch to the new template.

 Some template conversions can be done faster without copying explicitly
 their disks' data. A use case is the conversions between the LVM-based
 templates, i.e., ``drbd`` and ``plain`` which will be done as happens
 now and not using the ``dd`` command. Also, this implementation will
 provide partial support for the ``blockdev`` disk template which will
 act only as a source template. Since those volumes are adopted
 pre-existent block devices we will not support conversions targeting
 this template. Another exception case will be the ``diskless`` template.
 Since it is a testing template that creates instances with no disks we
 will not provide support for conversions that include this template
 type.


 We divide the design into the following parts:

 * Block device changes, that include the new methods which will be
   introduced and will be responsible for building the commands for the
   data copy from/to the requested devices

 * Backend changes, that include a new RPC call which will concatenate
   the output of the above two methods and will execute the data copy
   command

 * Core changes, that include the modifications in the Logical Unit

 * User interface changes, i.e., command line changes


 Block device changes
 --------------------

 The block device abstract class will be extended with two new methods,
 named ``Import`` and ``Export``. Those methods will be responsible for
 building the commands that will be used for the data copy between the
 corresponding devices. The ``Export`` method will build the command
 which will export the data from the source device, while the ``Import``
 method will do the opposite. It will import the data to the newly
 created target device. Those two methods will not perform the actual
 data copy; they will simply return the requested commands for
 transferring the data from/to the individual devices. The output of the
 two methods will be combined using a pipe ("|") by the caller method in
 the backend level.

 By default the data import and export will be done using the ``dd``
 command. All the inherited classes will use the base functionality
 unless there is a faster way to convert to. In that case the underlying
 block device will overwrite those methods with its specific
 functionality. A use case will be the Ceph/RADOS block devices which
 will make use of the ``rbd import`` and ``rbd export`` commands to copy
 their data instead of using the default ``dd`` command.

 Keeping the data copy functionality in the block device layer, provides
 us with a generic mechanism that works between almost all conversions
 and furthermore can be easily extended for new disk templates. It also
 covers the devices that support the ``access=userspace`` parameter and
 solves this problem in a generic way, by implementing the logic in the
 right level where we know what is the best to do for each device.


 Backend changes
 ---------------

 Introduce a new RPC call:

 * blockdev_convert(src_disk, dest_disk)

 where ``src_disk`` and ``dest_disk`` are the original and the new disk
 objects respectively. First, the actual device instances will be
 computed and then they will be used to build the export and import
 commands for the data copy. The output of those methods will be
 concatenated using a pipe, following a similar approach with the impexp
 daemon. Finally, the unified data copy command will be executed, at this
 level, by the ``nodeD``.


 Core changes
 ------------

 The main modifications will be made in the ``LUInstanceSetParams`` LU.
 The implementation of the conversion mechanism will be split into the
 following parts:

 * The generation of the new disk template for the instance. The new
   disks will match the size, mode, and name of the original volumes.
   Those parameters and any other needed, .i.e., the provider's name for
   the ExtStorage conversions, will be computed by a new method which we
   will introduce, named ``ComputeDisksInfo``. The output of that
   function will be used as the ``disk_info`` argument of the
   ``GenerateDiskTemplate`` method.

 * The creation of the new block devices. We will make use of the
   ``CreateDisks`` method which creates and attaches the new block
   devices.

 * The data copy for each disk of the instance from the original to the
   newly created volume. The data copy will be made by the ``nodeD`` with
   the rpc call we have introduced earlier in this design. In case some
   disks fail to copy their data the operation will fail and the newly
   created disks will be removed. The instance will remain intact.

 * The detachment of the original disks of the instance when the data
   copy operation successfully completes by calling the
   ``RemoveInstanceDisk`` method for each instance's disk.

 * The attachment of the new disks to the instance by calling the
   ``AddInstanceDisk`` method for each disk we have created.

 * The update of the configuration file with the new values.

 * The removal of the original block devices from the node using the
   ``BlockdevRemove`` method for each one of the old disks.


 User interface changes
 ----------------------

 The ``-t`` (``--disk-template``) option from the gnt-instance modify
 command will specify the disk template to convert *to*, as it happens
 now. The rest disk options such as its size, its mode, and its name will
 be computed from the original volumes by the conversion mechanism, and
 the user will not explicitly provide them.


 ExtStorage conversions
 ~~~~~~~~~~~~~~~~~~~~~~

 When converting to an ExtStorage disk template the
 ``provider=*PROVIDER*`` option which specifies the ExtStorage provider
 will be mandatory. Also, arbitrary parameters can be passed to the
 ExtStorage provider. Those parameters will be optional and could be
 passed as additional comma separated options. Since it is not allowed to
 convert the disk template of an instance and make use of the ``--disk``
 option at the same time, we propose to introduce a new option named
 ``--ext-params`` to handle the ``ext`` template conversions.

 ::

   gnt-instance modify -t ext --ext-params provider=pvdr1 test_vm
   gnt-instance modify -t ext --ext-params provider=pvdr1,param1=val1,param2=val2 test_vm


 File-based conversions
 ~~~~~~~~~~~~~~~~~~~~~~

 For conversions *to* a file-based template the ``--file-storage-dir``
 and the ``--file-driver`` options could be used, similarly to the
 **add** command, to manually configure the storage directory and the
 preferred driver for the file-based disks.

 ::

   gnt-instance modify -t file --file-storage-dir=mysubdir test_vm


 Supported template conversions
 ==============================

 This is a summary of the disk template conversions that the conversion
 mechanism will support:

 +--------------+-----------------------------------------------------------------------------------+
 | Source       |                                 Target Disk Template                              |
 | Disk         +---------+-------+------+------------+---------+------+------+----------+----------+
 | Template     |  Plain  |  DRBD | File | Sharedfile | Gluster | RBD  | Ext  | BlockDev | Diskless |
 +==============+=========+=======+======+============+=========+======+======+==========+==========+
 | Plain        |    -    |  Yes. | Yes. |    Yes.    |   Yes.  | Yes. | Yes. |    No.   |   No.    |
 +--------------+---------+-------+------+------------+---------+------+------+----------+----------+
 | DRBD         |   Yes.  |   -   | Yes. |    Yes.    |   Yes.  | Yes. | Yes. |    No.   |   No.    |
 +--------------+---------+-------+------+------------+---------+------+------+----------+----------+
 | File         |   Yes.  |  Yes. |   -  |    Yes.    |   Yes.  | Yes. | Yes. |    No.   |   No.    |
 +--------------+---------+-------+------+------------+---------+------+------+----------+----------+
 | Sharedfile   |   Yes.  |  Yes. | Yes. |     -      |   Yes.  | Yes. | Yes. |    No.   |   No.    |
 +--------------+---------+-------+------+------------+---------+------+------+----------+----------+
 | Gluster      |   Yes.  |  Yes. | Yes. |    Yes.    |    -    | Yes. | Yes. |    No.   |   No.    |
 +--------------+---------+-------+------+------------+---------+------+------+----------+----------+
 | RBD          |   Yes.  |  Yes. | Yes. |    Yes.    |   Yes.  |  -   | Yes. |    No.   |   No.    |
 +--------------+---------+-------+------+------------+---------+------+------+----------+----------+
 | Ext          |   Yes.  |  Yes. | Yes. |    Yes.    |   Yes.  | Yes. |  -   |    No.   |   No.    |
 +--------------+---------+-------+------+------------+---------+------+------+----------+----------+
 | BlockDev     |   Yes.  |  Yes. | Yes. |    Yes.    |   Yes.  | Yes. | Yes. |     -    |   No.    |
 +--------------+---------+-------+------+------------+---------+------+------+----------+----------+
 | Diskless     |   No.   |  No.  | No.  |    No.     |   No.   | No.  | No.  |    No.   |    -     |
 +--------------+---------+-------+------+------------+---------+------+------+----------+----------+


 Future Work
 ===========

 Expand the conversion mechanism to provide a visual indication of the
 data copy operation. We could monitor the progress of the data sent via
 a pipe, and provide to the user information such as the time elapsed,
 percentage completed (probably with a progress bar), total data
 transferred, and so on, similar to the progress tracking that is
 currently done by the impexp daemon.


 .. vim: set textwidth=72 :
 .. Local Variables:
 .. mode: rst
 .. fill-column: 72
 .. End:
	=================================
	Conversion between disk templates
	=================================

	.. contents:: :depth: 4

	This design document describes the support for generic disk template
	conversion in Ganeti. The logic used is disk template agnostic and
	targets to cover the majority of conversions among the supported disk
	templates.


	Current state and shortcomings
	==============================

	Currently, Ganeti supports choosing among different disk templates when
	creating an instance. However, converting the disk template of an
	existing instance is possible only between the ``plain`` and ``drbd``
	templates. This feature was added in Ganeti since its early versions
	when the number of supported disk templates was limited. Now that Ganeti
	supports plenty of choices, this feature should be extended to provide
	more flexibility to the user.

	The procedure for converting from the plain to the drbd disk template
	works as follows. Firstly, a completely new disk template is generated
	matching the size, mode, and the count of the current instance's disks.
	The missing volumes are created manually both in the primary (meta disk)
	and the secondary node. The original LVs running on the primary node are
	renamed to match the new names. The last step is to manually associate
	the DRBD devices with their mirror block device pairs. The conversion
	from the drbd to the plain disk template is much simpler than the
	opposite. Firstly, the DRBD mirroring is manually disabled. Then the
	unnecessary volumes including the meta disk(s) of the primary node, and
	the meta and data disk(s) from the previously secondary node are
	removed.


	Proposed changes
	================

	This design proposes the creation of a unified interface for handling
	the disk template conversions in Ganeti. Currently, there is no such
	interface and each one of the supported conversions uses a separate code
	path.

	This proposal introduces a single, disk-agnostic interface for handling
	the disk template conversions in Ganeti, keeping in mind that we want it
	to be as generic as possible. An exception case will be the currently
	supported conversions between the LVM-based disk templates. Their basic
	functionality will not be affected and will diverge from the rest disk
	template conversions. The target is to provide support for conversions
	among the majority of the available disk templates, and also creating
	a mechanism that will easily support any new templates that may be
	probably added in Ganeti, at a future point.


	Design decisions
	================

	Currently, the supported conversions for the LVM-based templates are
	handled by the ``LUInstanceSetParams`` LU. Our implementation will
	follow the same approach. From a high-level point-of-view this design
	can be split in two parts:

	* The extension of the LU's checks to cover all the supported template
	conversions

	* The new functionality which will be introduced to provide the new
	feature

	The instance must be stopped before starting the disk template
	conversion, as it currently is, otherwise the operation will fail. The
	new mechanism will need to copy the disk's data for the conversion to be
	possible. We propose using the Unix ``dd`` command to copy the
	instance's data. It can be used to copy data from source to destination,
	block-by-block, regardless of their filesystem types, making it a
	convenient tool for the case. Since the conversion will be done via data
	copy it will take a long time for bigger disks to copy their data and
	consequently for the instance to switch to the new template.

	Some template conversions can be done faster without copying explicitly
	their disks' data. A use case is the conversions between the LVM-based
	templates, i.e., ``drbd`` and ``plain`` which will be done as happens
	now and not using the ``dd`` command. Also, this implementation will
	provide partial support for the ``blockdev`` disk template which will
	act only as a source template. Since those volumes are adopted
	pre-existent block devices we will not support conversions targeting
	this template. Another exception case will be the ``diskless`` template.
	Since it is a testing template that creates instances with no disks we
	will not provide support for conversions that include this template
	type.


	We divide the design into the following parts:

	* Block device changes, that include the new methods which will be
	introduced and will be responsible for building the commands for the
	data copy from/to the requested devices

	* Backend changes, that include a new RPC call which will concatenate
	the output of the above two methods and will execute the data copy
	command

	* Core changes, that include the modifications in the Logical Unit

	* User interface changes, i.e., command line changes


	Block device changes
	--------------------

	The block device abstract class will be extended with two new methods,
	named ``Import`` and ``Export``. Those methods will be responsible for
	building the commands that will be used for the data copy between the
	corresponding devices. The ``Export`` method will build the command
	which will export the data from the source device, while the ``Import``
	method will do the opposite. It will import the data to the newly
	created target device. Those two methods will not perform the actual
	data copy; they will simply return the requested commands for
	transferring the data from/to the individual devices. The output of the
	two methods will be combined using a pipe ("\|") by the caller method in
	the backend level.

	By default the data import and export will be done using the ``dd``
	command. All the inherited classes will use the base functionality
	unless there is a faster way to convert to. In that case the underlying
	block device will overwrite those methods with its specific
	functionality. A use case will be the Ceph/RADOS block devices which
	will make use of the ``rbd import`` and ``rbd export`` commands to copy
	their data instead of using the default ``dd`` command.

	Keeping the data copy functionality in the block device layer, provides
	us with a generic mechanism that works between almost all conversions
	and furthermore can be easily extended for new disk templates. It also
	covers the devices that support the ``access=userspace`` parameter and
	solves this problem in a generic way, by implementing the logic in the
	right level where we know what is the best to do for each device.


	Backend changes
	---------------

	Introduce a new RPC call:

	* blockdev_convert(src_disk, dest_disk)

	where ``src_disk`` and ``dest_disk`` are the original and the new disk
	objects respectively. First, the actual device instances will be
	computed and then they will be used to build the export and import
	commands for the data copy. The output of those methods will be
	concatenated using a pipe, following a similar approach with the impexp
	daemon. Finally, the unified data copy command will be executed, at this
	level, by the ``nodeD``.


	Core changes
	------------

	The main modifications will be made in the ``LUInstanceSetParams`` LU.
	The implementation of the conversion mechanism will be split into the
	following parts:

	* The generation of the new disk template for the instance. The new
	disks will match the size, mode, and name of the original volumes.
	Those parameters and any other needed, .i.e., the provider's name for
	the ExtStorage conversions, will be computed by a new method which we
	will introduce, named ``ComputeDisksInfo``. The output of that
	function will be used as the ``disk_info`` argument of the
	``GenerateDiskTemplate`` method.

	* The creation of the new block devices. We will make use of the
	``CreateDisks`` method which creates and attaches the new block
	devices.

	* The data copy for each disk of the instance from the original to the
	newly created volume. The data copy will be made by the ``nodeD`` with
	the rpc call we have introduced earlier in this design. In case some
	disks fail to copy their data the operation will fail and the newly
	created disks will be removed. The instance will remain intact.

	* The detachment of the original disks of the instance when the data
	copy operation successfully completes by calling the
	``RemoveInstanceDisk`` method for each instance's disk.

	* The attachment of the new disks to the instance by calling the
	``AddInstanceDisk`` method for each disk we have created.

	* The update of the configuration file with the new values.

	* The removal of the original block devices from the node using the
	``BlockdevRemove`` method for each one of the old disks.


	User interface changes
	----------------------

	The ``-t`` (``--disk-template``) option from the gnt-instance modify
	command will specify the disk template to convert to, as it happens
	now. The rest disk options such as its size, its mode, and its name will
	be computed from the original volumes by the conversion mechanism, and
	the user will not explicitly provide them.


	ExtStorage conversions
	~~~~~~~~~~~~~~~~~~~~~~

	When converting to an ExtStorage disk template the
	``provider=PROVIDER`` option which specifies the ExtStorage provider
	will be mandatory. Also, arbitrary parameters can be passed to the
	ExtStorage provider. Those parameters will be optional and could be
	passed as additional comma separated options. Since it is not allowed to
	convert the disk template of an instance and make use of the ``--disk``
	option at the same time, we propose to introduce a new option named
	``--ext-params`` to handle the ``ext`` template conversions.

	::

	gnt-instance modify -t ext --ext-params provider=pvdr1 test_vm
	gnt-instance modify -t ext --ext-params provider=pvdr1,param1=val1,param2=val2 test_vm


	File-based conversions
	~~~~~~~~~~~~~~~~~~~~~~

	For conversions to a file-based template the ``--file-storage-dir``
	and the ``--file-driver`` options could be used, similarly to the
	add command, to manually configure the storage directory and the
	preferred driver for the file-based disks.

	::

	gnt-instance modify -t file --file-storage-dir=mysubdir test_vm


	Supported template conversions
	==============================

	This is a summary of the disk template conversions that the conversion
	mechanism will support:

	+--------------+-----------------------------------------------------------------------------------+
	\| Source \| Target Disk Template \|
	\| Disk +---------+-------+------+------------+---------+------+------+----------+----------+
	\| Template \| Plain \| DRBD \| File \| Sharedfile \| Gluster \| RBD \| Ext \| BlockDev \| Diskless \|
	+==============+=========+=======+======+============+=========+======+======+==========+==========+
	\| Plain \| - \| Yes. \| Yes. \| Yes. \| Yes. \| Yes. \| Yes. \| No. \| No. \|
	+--------------+---------+-------+------+------------+---------+------+------+----------+----------+
	\| DRBD \| Yes. \| - \| Yes. \| Yes. \| Yes. \| Yes. \| Yes. \| No. \| No. \|
	+--------------+---------+-------+------+------------+---------+------+------+----------+----------+
	\| File \| Yes. \| Yes. \| - \| Yes. \| Yes. \| Yes. \| Yes. \| No. \| No. \|
	+--------------+---------+-------+------+------------+---------+------+------+----------+----------+
	\| Sharedfile \| Yes. \| Yes. \| Yes. \| - \| Yes. \| Yes. \| Yes. \| No. \| No. \|
	+--------------+---------+-------+------+------------+---------+------+------+----------+----------+
	\| Gluster \| Yes. \| Yes. \| Yes. \| Yes. \| - \| Yes. \| Yes. \| No. \| No. \|
	+--------------+---------+-------+------+------------+---------+------+------+----------+----------+
	\| RBD \| Yes. \| Yes. \| Yes. \| Yes. \| Yes. \| - \| Yes. \| No. \| No. \|
	+--------------+---------+-------+------+------------+---------+------+------+----------+----------+
	\| Ext \| Yes. \| Yes. \| Yes. \| Yes. \| Yes. \| Yes. \| - \| No. \| No. \|
	+--------------+---------+-------+------+------------+---------+------+------+----------+----------+
	\| BlockDev \| Yes. \| Yes. \| Yes. \| Yes. \| Yes. \| Yes. \| Yes. \| - \| No. \|
	+--------------+---------+-------+------+------------+---------+------+------+----------+----------+
	\| Diskless \| No. \| No. \| No. \| No. \| No. \| No. \| No. \| No. \| - \|
	+--------------+---------+-------+------+------------+---------+------+------+----------+----------+


	Future Work
	===========

	Expand the conversion mechanism to provide a visual indication of the
	data copy operation. We could monitor the progress of the data sent via
	a pipe, and provide to the user information such as the time elapsed,
	percentage completed (probably with a progress bar), total data
	transferred, and so on, similar to the progress tracking that is
	currently done by the impexp daemon.


	.. vim: set textwidth=72 :
	.. Local Variables:
	.. mode: rst
	.. fill-column: 72
	.. End: