distribution (e.g. by allowing usage of public key infrastructure and
providing tools for management of basic software licensing).
-There are no limitations regarding hard drive images used, as long as
-the description is provided. Any hardware described in a proper
-i.e. CIM - Common Information Model) format is accepted, although
-there is no guarantee that every virtualization software will support
-all types of hardware.
+There are no limitations regarding disk images used, as long as the
+description is provided. Any hardware described in a proper format
+(i.e. CIM - Common Information Model) is accepted, although there is no
+guarantee that every virtualization software will support all types of
+hardware.
-OVF package should contain one file with ``.ovf`` extension, which is an
-XML file specifying the following (per virtual machine):
+OVF package should contain exactly one file with ``.ovf`` extension,
+which is an XML file specifying the following (per virtual machine):
- virtual disks
- network description
Additionally, the package may have some disk image files and other
additional resources (e.g. ISO images).
+In order to provide secure means of distribution for OVF packages, the
+manifest and certificate are provided. Manifest (``.mf`` file) contains
+checksums for all the files in OVF package, whereas certificate
+(``.cert`` file) contains X.509 certificate and a checksum of manifest
+file. Both files are not compulsory, but certificate requires manifest
+to be present.
+
Supported disk formats
----------------------
Although OVF is claimed to support 'any disk format', what we are
-interested in is which of the formats are supported by VM managers
-that currently use OVF.
+interested in is which formats are supported by VM managers that
+currently use OVF.
- VMWare: ``.vmdk`` (which comes in at least 3 different flavours:
``sparse``, ``compressed`` and ``streamOptimized``)
- Red Hat Enterprise Virtualization: ``.raw`` (raw disk format),
``.cow`` (qemu's ``QCOW2``)
- other: AbiCloud, OpenNode Cloud, SUSE Studio, Morfeo Claudia,
- OpenStack
+ OpenStack: mostly ``.vmdk``
-In our implementation of the OVF we plan to allow a choice between
-raw, cow and vmdk disk formats for export. We will not limit the import
-formats in any way, but the used format has to be supported by qemu-img.
+In our implementation of the OVF we allow a choice between raw, cow and
+vmdk disk formats for both import and export. Other formats covertable
+using ``qemu-img`` are allowed, but not tested.
The justification is the following:
- Raw format is supported as it is the main format of disk images used
has the advantage of producing relatively small disk images, which
is extremely important advantage when moving instances.
-The conversion between RAW and the other formats will be done using
-qemu-img, which transforms, among other, raw disk images to monolithic
-sparse vmdk images.
-
Import and export - the closer look
===================================
<gnt:DiskTemplate</gnt:DiskTemplate>
<gnt:OperatingSystem>
<gnt:Name/>
- <gnt:Parameters>
- </gnt:Parameters>
+ <gnt:Parameters></gnt:Parameters>
</gnt:OperatingSystem>
<gnt:Hypervisor>
<gnt:Name/>
- <gnt:Parameters>
- </gnt:Parameters>
+ <gnt:Parameters></gnt:Parameters>
</gnt:Hypervisor>
<gnt:Network>
<gnt:Mode/>
[instance]
disk0_dump = filename => File in References
disk0_ivname = name => generated automatically
- disk0_size = size_in_mb => calculated after conversion to RAW
+ disk0_size = size_in_mb => calculated after disk conversion
disk_count = number => generated automatically
disk_template = disk_type => gnt:DiskTemplate
hypervisor = hyp-name => gnt:Name in gnt:Hypervisor
If this happens you can specify all the missing parameters in
the command line. Please refer to `Command Line`_ section.
-In the `user's manual <TODO: link to manual>`_ we provide examples of
+In the :doc:`ovfconverter` we provide examples of
options when converting from VirtualBox, VMWare and OpenSuseStudio.
Export to other virtualization software
Disks
-----
-As mentioned, Ganeti will allow exporting only ``raw``, ``cow`` and
-``vmdk`` formats. As for import, we will support all that
-``qemu-img`` can convert to raw format. At this point this means
-``raw``, ``cow``, ``qcow``, ``qcow2``, ``vmdk`` and ``cloop``. We do
-not plan for now to support ``vdi`` or ``vhd``.
+As mentioned, Ganeti will allow export in ``raw``, ``cow`` and ``vmdk``
+formats. This means i.e. that the appropriate ``ovf:format``
+will be provided. It does not mean that other formats cannot be used,
+rather that we did not test them.
+As for import, we will support all formats that ``qemu-img`` can convert
+to ``raw``. At this point this means ``raw``, ``cow``, ``qcow``,
+``qcow2``, ``vmdk`` and ``cloop``. We do not plan for now to support
+``vdi`` or ``vhd`` unless they become part of qemu-img supported formats.
-We plan to support compression both for import and export - in tar.gz
+We plan to support compression both for import and export - in gzip
format. There is also a possibility to provide virtual disk in chunks
of equal size. The latter will not be implemented in the first version,
but we do plan to support it eventually.
-The ``ovf:format`` tag is not used in our case. Instead we use
-``qemu-img info``, which provides enough information for our purposes
-and is better standardized.
+
+The ``ovf:format`` tag is not used in our case when importing. Instead
+we use ``qemu-img info``, which provides enough information for our
+purposes and is better standardized.
Please note, that due to security reasons we require the disk image to
be in the same directory as the ``.ovf`` description file.
present, we perform a simple check - if network name specified in
``NetworkSection`` contains words ``bridged`` or ``routed``, we consider
this to be the network type. Otherwise option ``auto`` is chosen, in
-which case the clusters' default value for that field will be used when
-importing. This provides a safe fallback in case of NAT networks usage,
-which are commonly used e.g. in VirtualBox.
+which case the cluster's default value for that field will be used when
+importing.
+This provides a safe fallback in case of NAT networks usage, which are
+commonly used e.g. in VirtualBox.
Hardware
--------
Other
-----
-The instance name (``gnt:VirtualSystem\gnt:Name``) has to be resolvable
-in order for successful import using ``gnt-backup import``.
+The instance name (``gnt:VirtualSystem\gnt:Name`` or command line's
+``--name`` option ) has to be resolvable in order for successful import
+using ``gnt-backup import``.
+
_`Command Line`
===============
The basic usage of the ovf tool is one of the following::
ovfconverter import filename
- ovfconverter export filename
+ ovfconverter export --format=<format> filename
This will result in a conversion based solely on the content of provided
file. In case some information required to make the conversion is
Disks
^^^^^
``--disk-template=diskless`` causes the converter to ignore all other
-disk option - both from .ovf file and the command line.
+disk option - both from .ovf file and the command line. Other disk
+template options include ``plain``, ``drdb``, ``file``, ``sharedfile``
+and ``blockdev``.
``--disk=number:size=value`` causes to create disks instead of
converting them from OVF package; numbers should start with ``0`` and be
``--tags=tag1,tag2,tag3`` is a means of providing tags specific for the
instance.
+
After the conversion is completed, you may use ``gnt-backup import`` to
import the instance into Ganeti.
Example::
- ovfconverter file.ovf --disk-template=diskless \
- --os-type=lenny-image \
- --backend=vcpus=1,memory=512,auto_balance \
- -H:xen-pvm \
- --net=0:mode=bridged,link=xen-br0 \
- --name=xen.i1 \
- -v
- [output]
+ ovfconverter import file.ovf --disk-template=diskless \
+ --os-type=lenny-image \
+ --backend=vcpus=1,memory=512,auto_balance \
+ -H:xen-pvm \
+ --net=0:mode=bridged,link=xen-br0 \
+ --name=xen.i1
+ [...]
gnt-backup import xen.i1
- [output]
+ [...]
gnt-instance list
Export options
--------------
Export options include choice of disk formats to convert the disk image
-(``--format``; default=``raw`` with no conversion) and compression of
-the disk into tar.gz format (``--compress``).
-User has also the choice of allowing to skip the Ganeti-specific part of
-the OVF document (``--external``).
+(``--format``) and compression of the disk into gzip format
+(``--compress``). User has also the choice of allowing to skip the
+Ganeti-specific part of the OVF document (``--external``).
By default, exported OVF package will not be contained in the OVA
package, but this may be changed by adding ``--ova`` option.
-[TODO: examples of usage]
-
Please note that in order to create an OVF package, it is first
required that you export your VM using ``gnt-backup export``.
-[TODO: complete example of export]
+Example::
+
+ gnt-backup export -n node1.xen xen.i1
+ [...]
+ ovfconverter export --format=vmdk --ova --external \
+ --output-dir=~/xen.i1 \
+ /srv/ganeti/export/xen.i1.node1.xen/config.ini
Implementation details
======================
---------------
Disk conversion for both import and export is done using external tool
-called qemu-tools. The same tool is used to determine the type of disks.
+called qemu-tools. The same tool is used to determine the type of disk,
+as well as its virtual size.
Import
- save gathered information in ``config.ini`` file
-ToDo
-====
-
-This lists functionalities for import that are not yet implemented, but
-should be before the initial release:
-
-- Support for compressed disks
-
.. vim: set textwidth=72 :
.. Local Variables:
--- /dev/null
+=============
+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 rven if the type is given in OVF description, it is not detailed
+enough for Ganeti to know which os-specific scripts to use.
+
+
+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
+
+
+.. vim: set textwidth=72 :
+.. Local Variables:
+.. mode: rst
+.. fill-column: 72
+.. End:
projects / ganeti-local / commitdiff