Commit 97c60815 authored by Agata Murawska's avatar Agata Murawska Committed by René Nussbaumer
Browse files

Import: further doc updates


Signed-off-by: default avatarAgata Murawska <agatamurawska@google.com>
Signed-off-by: default avatarRené Nussbaumer <rn@google.com>
Reviewed-by: default avatarRené Nussbaumer <rn@google.com>
parent a52978c7
......@@ -38,14 +38,14 @@ host- and virtualization platform-independent and optimized for
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
......@@ -58,12 +58,19 @@ human-readable description to every piece of information given.
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``)
......@@ -74,11 +81,11 @@ that currently use OVF.
- 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
......@@ -88,10 +95,6 @@ The justification is the following:
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
===================================
......@@ -122,13 +125,11 @@ The basic structure of Ganeti ``.ovf`` file is the following::
<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/>
......@@ -151,7 +152,7 @@ where will the data be in OVF format::
[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
......@@ -195,7 +196,7 @@ will lack the ``gnt:GanetiSection``.
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
......@@ -247,20 +248,24 @@ option.
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.
......@@ -278,9 +283,10 @@ used network type, we add our own source of such information in
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
--------
......@@ -299,8 +305,10 @@ checked using ``gnt-os list`` command.
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`
===============
......@@ -308,7 +316,7 @@ _`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
......@@ -339,7 +347,9 @@ omitted ones will be set to cluster defaults (``auto``).
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
......@@ -370,40 +380,43 @@ Tags
``--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
======================
......@@ -412,7 +425,8 @@ Disk conversion
---------------
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
......@@ -454,14 +468,6 @@ Typical workflow for the import is very simple:
- 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:
......
......@@ -29,6 +29,7 @@ Contents:
iallocator.rst
rapi.rst
move-instance.rst
ovfconverter.rst
devnotes.rst
news.rst
glossary.rst
......
=============
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:
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment