doc/ovfconverter.rst - ganeti - Git at Google

 =============
 OVF converter
 =============

 Using ``ovfconverter`` from the ``tools`` directory, one can easily
 convert previously exported Ganeti instance into OVF package, supported
 by VMWare, VirtualBox and some other virtualization software. It is
 also possible to use instance exported from such a tool and convert it
 to Ganeti config file, used by ``gnt-backup import`` command.

 For the internal design of the converter and more detailed description,
 including listing of available command line options, please refer to
 :doc:`design-ovf-support`

 As the amount of Ganeti-specific details, that need to be provided in
 order to import an external instance, is rather large, we will present
 here some examples of importing instances from different sources.
 It is also worth noting that there are some limitations regarding
 support for different hardware.

 Limitations on import
 =====================

 Network
 -------
 Available modes for the network include ``bridged`` and ``routed``.
 There is no ``NIC`` mode, which is typically used e.g. by VirtualBox.
 For most usecases this should not be of any effect, since if
 ``NetworkSection`` contains any networks which are not discovered as
 ``bridged`` or ``routed``, the network mode is assigned automatically,
 using Ganeti's cluster defaults.

 Backend
 -------
 The only values that are taken into account regarding Virtual Hardware
 (described in ``VirtualHardwareSection`` of the ``.ovf`` file) are:

 - number of virtual CPUs
 - RAM memory
 - hard disks
 - networks

 Neither USB nor CD-ROM drive are used in Ganeti. We decided to simply
 ignore unused elements of this section, so their presence won't raise
 any warnings.

 Operating System
 ----------------
 List of operating systems available on a cluster is viewable using
 ``gnt-os list`` command. When importing from external source, providing
 OS type in a command line (``--os-type=...``) is **required**. This is
 because even if the type is given in OVF description, it is not detailed
 enough for Ganeti to know which os-specific scripts to use.
 Please note, that instance containing disks may only be imported using
 OS script that supports raw disk images.

 References
 ----------
 Files listed in ``ovf:References`` section cannot be hyperlinks.


 Limitations on export
 =====================

 Disk content
 ------------
 Most Ganeti instances do not contain grub. This results in some
 problems when importing to virtualization software that does expect it.
 Examples of such software include VirtualBox and VMWare.

 To avoid trouble, please install grub inside the instance before
 exporting it.


 Import to VirtualBox
 --------------------
 ``format`` option should be set to ``vmdk`` in order for instance to be
 importable by VirtualBox.

 Tests using existing versions of VirtualBox (3.16) suggest, that
 VirtualBox does not support disk compression or OVA packaging. In future
 versions this might change.


 Import to VMWare
 ----------------
 Importing Ganeti instance to VMWare was tested using ``ovftool``.

 ``format`` option should be set to ``vmdk`` in order for instance to be
 importable by VMWare.

 Presence of Ganeti section does seem to cause some problems and
 therefore it is recommended to use ``--external`` option on export.

 Import of compressed disks generated by ovfconverter was impossible in
 current version of ``ovftool`` (2.1.0). This seems to be related to old
 ``vmdk`` version. Since the conversion to ``vmdk`` format is done using
 ``qemu-img``, it is possible and in fact expected, that future versions
 of the latter tool will resolve this problem.


 Import examples
 ===============

 Ganeti's OVF
 ------------
 If you are importing instance created using ``ovfconverter export`` --
 you most probably will not have to provide any additional information.
 In that case, the following is all you need (unless you wish to change
 some configuration options)::

 	ovfconverter import ganeti.ovf
 	[...]
 	gnt-instance import -n <node> <instance name>


 Virtualbox, VMWare and other external sources
 ---------------------------------------------
 In case of importing from external source, you will most likely have to
 provide the following details:

 - ``os-type`` can be any operating system listed on ``gnt-os list``
 - ``name`` that has to be resolvable, as it will be used as instance
   name (even if your external instance has a name, it most probably is
   not resolvable to an IP address)

 These are not the only options, but the recommended ones. For the
 complete list of available options please refer to
 `Command Line description <design-ovf-support.rst>`

 Minimalistic but complete example of importing Virtualbox's OVF
 instance may look like::

     ovfconverter virtualbox.ovf --os-type=lenny-image \
       --name=xen.test.i1 --disk-template=diskless
     [...]
     gnt-instance import -n node1.xen xen.test.i1


 Export example
 ==============

 Exporting instance into ``.ovf`` format is pretty streightforward and
 requires little - if any - explanation. The only compulsory detail is
 the required disk format, provided using the ``--format`` option.

 Export to another Ganeti instance
 ---------------------------------
 If for some reason it is convenient for you to use ``ovfconverter`` to
 move instance between clusters (e.g. because of the disk compression),
 the complete example of export may look like this::

     gnt-backup export -n node1.xen xen.test.i1
     [...]
     ovfconverter export --format=vmdk --ova \
       /srv/ganeti/export/xen.i1.node1.xen/config.ini
     [...]

 The result is then in
 ``/srv/ganeti/export/xen.i1.node1.xen/xen.test.i1.ova``

 Export to Virtualbox/VMWare/other external tool
 -----------------------------------------------
 Typically, when exporting to external tool we do not want
 Ganeti-specific configuration to be saved. In that case, simply use the
 ``--external`` option::

     gnt-backup export -n node1.xen xen.test.i1
     [...]
     ovfconverter export --external --output-dir ~/ganeti-instance/ \
       /srv/ganeti/export/xen.i1.node1.xen/config.ini


 Known issues
 ============

 Conversion errors
 -----------------
 If you are encountering trouble when converting the disk, please ensure
 that you have newest ``qemu-img`` version.

 OVA and compression
 -------------------
 The compressed disks and OVA packaging do not work correctly in either
 VirtualBox (old version) or VMWare.

 VirtualBox (3.16 OSE) does not seem to support those two, so there is
 very little we can do about this.

 As for VMWare, the reason behind it not accepting compressed or packed
 instances created by ovfconverter seems to be related to the old vmdk
 version.

 Problems on newest VirtualBox
 -----------------------------
 In Oracle VM Virtualbox 4.0+ there seems to be a problem when importing
 any OVF instance created by ovfconverter. Reasons are again unknown,
 this will be investigated.

 Disk space
 ----------
 The disk space requirements for both import and export are at the moment
 very large - we require free space up to about 3-4 times the size of
 disks. This will most likely be changed in future versions.


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

	Using ``ovfconverter`` from the ``tools`` directory, one can easily
	convert previously exported Ganeti instance into OVF package, supported
	by VMWare, VirtualBox and some other virtualization software. It is
	also possible to use instance exported from such a tool and convert it
	to Ganeti config file, used by ``gnt-backup import`` command.

	For the internal design of the converter and more detailed description,
	including listing of available command line options, please refer to
	:doc:`design-ovf-support`

	As the amount of Ganeti-specific details, that need to be provided in
	order to import an external instance, is rather large, we will present
	here some examples of importing instances from different sources.
	It is also worth noting that there are some limitations regarding
	support for different hardware.

	Limitations on import
	=====================

	Network
	-------
	Available modes for the network include ``bridged`` and ``routed``.
	There is no ``NIC`` mode, which is typically used e.g. by VirtualBox.
	For most usecases this should not be of any effect, since if
	``NetworkSection`` contains any networks which are not discovered as
	``bridged`` or ``routed``, the network mode is assigned automatically,
	using Ganeti's cluster defaults.

	Backend
	-------
	The only values that are taken into account regarding Virtual Hardware
	(described in ``VirtualHardwareSection`` of the ``.ovf`` file) are:

	- number of virtual CPUs
	- RAM memory
	- hard disks
	- networks

	Neither USB nor CD-ROM drive are used in Ganeti. We decided to simply
	ignore unused elements of this section, so their presence won't raise
	any warnings.

	Operating System
	----------------
	List of operating systems available on a cluster is viewable using
	``gnt-os list`` command. When importing from external source, providing
	OS type in a command line (``--os-type=...``) is required. This is
	because even if the type is given in OVF description, it is not detailed
	enough for Ganeti to know which os-specific scripts to use.
	Please note, that instance containing disks may only be imported using
	OS script that supports raw disk images.

	References
	----------
	Files listed in ``ovf:References`` section cannot be hyperlinks.


	Limitations on export
	=====================

	Disk content
	------------
	Most Ganeti instances do not contain grub. This results in some
	problems when importing to virtualization software that does expect it.
	Examples of such software include VirtualBox and VMWare.

	To avoid trouble, please install grub inside the instance before
	exporting it.


	Import to VirtualBox
	--------------------
	``format`` option should be set to ``vmdk`` in order for instance to be
	importable by VirtualBox.

	Tests using existing versions of VirtualBox (3.16) suggest, that
	VirtualBox does not support disk compression or OVA packaging. In future
	versions this might change.


	Import to VMWare
	----------------
	Importing Ganeti instance to VMWare was tested using ``ovftool``.

	``format`` option should be set to ``vmdk`` in order for instance to be
	importable by VMWare.

	Presence of Ganeti section does seem to cause some problems and
	therefore it is recommended to use ``--external`` option on export.

	Import of compressed disks generated by ovfconverter was impossible in
	current version of ``ovftool`` (2.1.0). This seems to be related to old
	``vmdk`` version. Since the conversion to ``vmdk`` format is done using
	``qemu-img``, it is possible and in fact expected, that future versions
	of the latter tool will resolve this problem.


	Import examples
	===============

	Ganeti's OVF
	------------
	If you are importing instance created using ``ovfconverter export`` --
	you most probably will not have to provide any additional information.
	In that case, the following is all you need (unless you wish to change
	some configuration options)::

	ovfconverter import ganeti.ovf
	[...]
	gnt-instance import -n <node> <instance name>


	Virtualbox, VMWare and other external sources
	---------------------------------------------
	In case of importing from external source, you will most likely have to
	provide the following details:

	- ``os-type`` can be any operating system listed on ``gnt-os list``
	- ``name`` that has to be resolvable, as it will be used as instance
	name (even if your external instance has a name, it most probably is
	not resolvable to an IP address)

	These are not the only options, but the recommended ones. For the
	complete list of available options please refer to
	`Command Line description <design-ovf-support.rst>`

	Minimalistic but complete example of importing Virtualbox's OVF
	instance may look like::

	ovfconverter virtualbox.ovf --os-type=lenny-image \
	--name=xen.test.i1 --disk-template=diskless
	[...]
	gnt-instance import -n node1.xen xen.test.i1



	Export example
	==============

	Exporting instance into ``.ovf`` format is pretty streightforward and
	requires little - if any - explanation. The only compulsory detail is
	the required disk format, provided using the ``--format`` option.

	Export to another Ganeti instance
	---------------------------------
	If for some reason it is convenient for you to use ``ovfconverter`` to
	move instance between clusters (e.g. because of the disk compression),
	the complete example of export may look like this::

	gnt-backup export -n node1.xen xen.test.i1
	[...]
	ovfconverter export --format=vmdk --ova \
	/srv/ganeti/export/xen.i1.node1.xen/config.ini
	[...]

	The result is then in
	``/srv/ganeti/export/xen.i1.node1.xen/xen.test.i1.ova``

	Export to Virtualbox/VMWare/other external tool
	-----------------------------------------------
	Typically, when exporting to external tool we do not want
	Ganeti-specific configuration to be saved. In that case, simply use the
	``--external`` option::

	gnt-backup export -n node1.xen xen.test.i1
	[...]
	ovfconverter export --external --output-dir ~/ganeti-instance/ \
	/srv/ganeti/export/xen.i1.node1.xen/config.ini


	Known issues
	============

	Conversion errors
	-----------------
	If you are encountering trouble when converting the disk, please ensure
	that you have newest ``qemu-img`` version.

	OVA and compression
	-------------------
	The compressed disks and OVA packaging do not work correctly in either
	VirtualBox (old version) or VMWare.

	VirtualBox (3.16 OSE) does not seem to support those two, so there is
	very little we can do about this.

	As for VMWare, the reason behind it not accepting compressed or packed
	instances created by ovfconverter seems to be related to the old vmdk
	version.

	Problems on newest VirtualBox
	-----------------------------
	In Oracle VM Virtualbox 4.0+ there seems to be a problem when importing
	any OVF instance created by ovfconverter. Reasons are again unknown,
	this will be investigated.

	Disk space
	----------
	The disk space requirements for both import and export are at the moment
	very large - we require free space up to about 3-4 times the size of
	disks. This will most likely be changed in future versions.


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