1 ==============================================================
2 Ganeti Instance Import/Export using Open Virtualization Format
3 ==============================================================
8 Open Virtualization Format is an open standard for packaging
9 information regarding virtual machines. It is used, among other, by
10 VMWare, VirtualBox and XenServer. OVF allows users to migrate between
11 virtualization software without the need of reconfiguring hardware,
12 network or operating system.
14 Currently, exporting instance in Ganeti results with a configuration
15 file that is readable only for Ganeti. It disallows the users to
16 change the platform they use without loosing all the machine's
17 configuration. Import function in Ganeti is also currently limited to
18 the previously prepared instances.
20 Implementation of OVF support allows users to migrate to Ganeti from
21 other platforms, thus potentially increasing the usage. It also
22 enables virtual machine end-users to create their own machines
23 (e.g. in VirtualBox or SUSE Studio) and then add them to Ganeti
24 cluster, thus providing better personalization.
29 Open Virtualization Format description
30 --------------------------------------
32 According to the DMTF document introducing the standard: "The Open
33 Virtualization Format (OVF) Specification describes an open, secure,
34 portable, efficient and extensible format for the packaging and
35 distribution of software to be run in virtual machines." OVF supports
36 both single and multiple- configurations of VMs in one package, is
37 host- and virtualization platform-independent and optimized for
38 distribution (e.g. by allowing usage of public key infrastructure and
39 providing tools for management of basic software licensing).
41 There are no limitations regarding disk images used, as long as the
42 description is provided. Any hardware described in a proper format
43 (i.e. CIM - Common Information Model) is accepted, although there is no
44 guarantee that every virtualization software will support all types of
47 OVF package should contain exactly one file with ``.ovf`` extension,
48 which is an XML file specifying the following (per virtual machine):
52 - list of virtual hardware
53 - operating system, if any
55 Each of the elements in ``.ovf`` file may, if desired, contain a
56 human-readable description to every piece of information given.
58 Additionally, the package may have some disk image files and other
59 additional resources (e.g. ISO images).
61 In order to provide secure means of distribution for OVF packages, the
62 manifest and certificate are provided. Manifest (``.mf`` file) contains
63 checksums for all the files in OVF package, whereas certificate
64 (``.cert`` file) contains X.509 certificate and a checksum of manifest
65 file. Both files are not compulsory, but certificate requires manifest
68 Supported disk formats
69 ----------------------
71 Although OVF is claimed to support 'any disk format', what we are
72 interested in is which formats are supported by VM managers that
75 - VMWare: ``.vmdk`` (which comes in at least 3 different flavours:
76 ``sparse``, ``compressed`` and ``streamOptimized``)
77 - VirtualBox: ``.vdi`` (VirtualBox's format), ``.vmdk``, ``.vhd``
78 (Microsoft and XenServer); export disk format is always ``.vmdk``
79 - XenServer: ``.vmdk``, ``.vhd``; export disk format is always
81 - Red Hat Enterprise Virtualization: ``.raw`` (raw disk format),
82 ``.cow`` (qemu's ``QCOW2``)
83 - other: AbiCloud, OpenNode Cloud, SUSE Studio, Morfeo Claudia,
84 OpenStack: mostly ``.vmdk``
86 In our implementation of the OVF we allow a choice between raw, cow and
87 vmdk disk formats for both import and export. Other formats covertable
88 using ``qemu-img`` are allowed in import mode, but not tested.
89 The justification is the following:
91 - Raw format is supported as it is the main format of disk images used
92 in Ganeti, thus it is effortless to provide support for this format
94 - Vmdk is most commonly supported in virtualization software, it also
95 has the advantage of producing relatively small disk images, which
96 is extremely important advantage when moving instances.
98 Import and export - the closer look
99 ===================================
101 This section contains an overview of how different parts of
102 Ganeti's export info are included in ``.ovf`` configuration file.
103 It also explains how import is designed to work with incomplete
106 Ganeti's backup format vs OVF
107 -----------------------------
110 The basic structure of Ganeti ``.ovf`` file is the following::
113 <References></References>
114 <DiskSection></DiskSection>
115 <NetworkSection></NetworkSection>
118 <OperatingSystemSection></OperatingSystemSection>
119 <VirtualHardwareSection><VirtualHardwareSection>
124 <gnt:Tags></gnt:Tags>
125 <gnt:DiskTemplate</gnt:DiskTemplate>
126 <gnt:OperatingSystem>
128 <gnt:Parameters></gnt:Parameters>
129 </gnt:OperatingSystem>
132 <gnt:Parameters></gnt:Parameters>
144 Tags with ``gnt:`` prefix are Ganeti-specific and are not a part of
149 Whereas Ganeti's export info is of the following form, ``=>`` showing
150 where will the data be in OVF format::
153 disk0_dump = filename => File in References
154 disk0_ivname = name => generated automatically
155 disk0_size = size_in_mb => calculated after disk conversion
156 disk_count = number => generated automatically
157 disk_template = disk_type => gnt:DiskTemplate
158 hypervisor = hyp-name => gnt:Name in gnt:Hypervisor
159 name = inst-name => Name in VirtualSystem
160 nic0_ip = ip => gnt:IPAddress in gnt:Network
161 nic0_link = link => gnt:Link in gnt:Network
162 nic0_mac = mac => gnt:MACAddress in gnt:Network or
163 Item in VirtualHardwareSection
164 nic0_mode = mode => gnt:Mode in gnt:Network
165 nic_count = number => generated automatically
169 auto_balanced => gnt:AutoBalance
170 memory = mem_in_mb => Item in VirtualHardwareSection
171 vcpus = number => Item in VirtualHardwareSection
174 compression => ignored
175 os => gnt:Name in gnt:OperatingSystem
178 version => gnt:VersionId or
179 constants.EXPORT_VERSION
181 [os] => gnt:Parameters in gnt:OperatingSystem
183 [hypervisor] => gnt:Parameters in gnt:Hypervisor
185 In case of multiple networks/disks used by an instance, they will
186 all be saved in appropriate sections as specified above for the first
189 Import from other virtualization software
190 -----------------------------------------
191 In case of importing to Ganeti OVF package generated in other software,
192 e.g. VirtualBox, some fields required for Ganeti to properly handle
193 import may be missing. Most often it will happen that such OVF package
194 will lack the ``gnt:GanetiSection``.
196 If this happens you can specify all the missing parameters in
197 the command line. Please refer to `Command Line`_ section.
199 In the :doc:`ovfconverter` we provide examples of
200 options when converting from VirtualBox, VMWare and OpenSuseStudio.
202 Export to other virtualization software
203 ---------------------------------------
204 When exporting to other virtualization software, you may notice that
205 there is a section ``gnt:GanetiSection``, containing Ganeti-specific
206 information. This may on **rare** cases cause trouble in importing your
207 instance. If that is the case please do one of the two:
209 1. Export from Ganeti to OVF with ``--external`` option - this will
210 cause to skip the non-standard information.
212 2. Manually remove the gnt:GanetiSection from the ``.ovf`` file. You
213 will also have to recompute sha1 sum (``sha1sum`` command) of the .ovf
214 file and update your ``.mf`` file with new value.
217 Manual change option is only recommended when you have exported your
218 instance with ``-format`` option other that ``raw`` or selected
219 ``--compress``. It saves you the time of converting or compressing
225 The limitations regarding import of the OVF instances generated
226 outside Ganeti will be (in general) the same, as limitations for
227 Ganeti itself. The desired behavior in case of encountering
228 unsupported element will be to ignore this element's tag without
229 interruption of the import process.
234 There are no limitations regarding support for multiple files in
235 package or packing the OVF package into one OVA (Open Virtual
236 Appliance) file. As for certificates and licenses in the package,
237 their support will be under discussion after completion of the basic
238 features implementation.
240 Multiple Virtual Systems
241 ------------------------
243 At first only singular instances (i.e. VirtualSystem, not
244 VirtualSystemCollection) will be supported. In the future multi-tiered
245 appliances containing whole nodes (or even clusters) are considered an
251 As mentioned, Ganeti will allow export in ``raw``, ``cow`` and ``vmdk``
252 formats. This means i.e. that the appropriate ``ovf:format``
254 As for import, we will support all formats that ``qemu-img`` can convert
255 to ``raw``. At this point this means ``raw``, ``cow``, ``qcow``,
256 ``qcow2``, ``vmdk`` and ``cloop``. We do not plan for now to support
257 ``vdi`` or ``vhd`` unless they become part of qemu-img supported formats.
259 We plan to support compression both for import and export - in gzip
260 format. There is also a possibility to provide virtual disk in chunks
261 of equal size. The latter will not be implemented in the first version,
262 but we do plan to support it eventually.
265 The ``ovf:format`` tag is not used in our case when importing. Instead
266 we use ``qemu-img info``, which provides enough information for our
267 purposes and is better standardized.
269 Please note, that due to security reasons we require the disk image to
270 be in the same directory as the ``.ovf`` description file for both
273 In order to completely ignore disk-related information in resulting
274 config file, please use ``--disk-template=diskless`` option.
279 Ganeti provides support for routed and bridged mode for the networks.
280 Since the standard OVF format does not contain any information regarding
281 used network type, we add our own source of such information in
282 ``gnt:GanetiSection``. In case this additional information is not
283 present, we perform a simple check - if network name specified in
284 ``NetworkSection`` contains words ``bridged`` or ``routed``, we consider
285 this to be the network type. Otherwise option ``auto`` is chosen, in
286 which case the cluster's default value for that field will be used when
288 This provides a safe fallback in case of NAT networks usage, which are
289 commonly used e.g. in VirtualBox.
294 The supported hardware is limited to virtual CPUs, RAM memory, disks and
295 networks. In particular, no USB support is currently provided, as Ganeti
296 does not support them.
301 Support for different operating systems depends solely on their
302 accessibility for Ganeti instances. List of installed OSes can be
303 checked using ``gnt-os list`` command.
308 Files listed in ``ovf:References`` section cannot be hyperlinks.
313 The instance name (``gnt:VirtualSystem\gnt:Name`` or command line's
314 ``--name`` option ) has to be resolvable in order for successful import
315 using ``gnt-backup import``.
321 The basic usage of the ovf tool is one of the following::
323 ovfconverter import filename
324 ovfconverter export --format=<format> filename
326 This will result in a conversion based solely on the content of provided
327 file. In case some information required to make the conversion is
328 missing, an error will occur.
330 If output directory should be different than the standard Ganeti export
331 directory (usually ``/srv/ganeti/export``), option ``--output-dir``
334 If name of resulting entity should be different than the one read from
335 the file, use ``--name`` option.
340 Import options that ``ovfconverter`` supports include options for
341 backend, disks, hypervisor, networks and operating system. If an option
342 is given, it overrides the values provided in the OVF file.
346 ``--backend=option=value`` can be used to set auto balance, number of
347 vcpus and amount of RAM memory.
349 Please note that when you do not provide full set of options, the
350 omitted ones will be set to cluster defaults (``auto``).
354 ``--disk-template=diskless`` causes the converter to ignore all other
355 disk option - both from .ovf file and the command line. Other disk
356 template options include ``plain``, ``drdb``, ``file``, ``sharedfile``
359 ``--disk=number:size=value`` causes to create disks instead of
360 converting them from OVF package; numbers should start with ``0`` and be
365 ``-H hypervisor_name`` and ``-H hypervisor_name:option=value``
366 provide options for hypervisor.
370 ``--no-nics`` option causes converter to ignore any network information
373 ``--network=number:option=value`` sets network information according to
374 provided data, ignoring the OVF package configuration.
378 ``--os-type=type`` sets os type accordingly, this option is **required**
379 when importing from OVF instance not created from Ganeti config file.
381 ``--os-parameters`` provides options for chosen operating system.
385 ``--tags=tag1,tag2,tag3`` is a means of providing tags specific for the
389 After the conversion is completed, you may use ``gnt-backup import`` to
390 import the instance into Ganeti.
394 ovfconverter import file.ovf --disk-template=diskless \
395 --os-type=lenny-image \
396 --backend=vcpus=1,memory=512,auto_balance \
398 --net=0:mode=bridged,link=xen-br0 \
401 gnt-backup import xen.i1
407 Export options include choice of disk formats to convert the disk image
408 (``--format``) and compression of the disk into gzip format
409 (``--compress``). User has also the choice of allowing to skip the
410 Ganeti-specific part of the OVF document (``--external``).
412 By default, exported OVF package will not be contained in the OVA
413 package, but this may be changed by adding ``--ova`` option.
415 Please note that in order to create an OVF package, it is first
416 required that you export your VM using ``gnt-backup export``.
420 gnt-backup export -n node1.xen xen.i1
422 ovfconverter export --format=vmdk --ova --external \
423 --output-dir=~/xen.i1 \
424 /srv/ganeti/export/xen.i1.node1.xen/config.ini
426 Implementation details
427 ======================
432 Disk conversion for both import and export is done using external tool
433 called ``qemu-img``. The same tool is used to determine the type of
434 disk, as well as its virtual size.
440 Import functionality is implemented using two classes - OVFReader and
443 OVFReader class is used to read the contents of the ``.ovf`` file. Every
444 action that requires ``.ovf`` file access is done through that class.
445 It also performs validation of manifest, if one is present.
447 The result of reading some part of file is typically a dictionary or a
448 string, containing options which correspond to the ones in
449 ``config.ini`` file. Only in case of disks, the resulting value is
450 different - it is then a list of disk names. The reason for that is the
453 OVFImporter class performs all the command-line-like tasks, such as
454 unpacking OVA package, removing temporary directory, converting disk
455 file to raw format or saving the configuration file on disk.
456 It also contains a set of functions that read the options provided in
460 Typical workflow for the import is very simple:
462 - read the ``.ovf`` file into memory
464 - parse each element of the configuration file: name, disk template,
465 hypervisor, operating system, backend parameters, network and disks
467 - check if option for the element can be read from command line
470 - if yes: parse options from command line
472 - otherwise: read the appropriate portion of ``.ovf`` file
474 - save gathered information in ``config.ini`` file
479 Similar to import, export functionality also uses two classes -
480 OVFWriter and OVFExporter.
482 OVFWriter class produces XML output based on the information given. Its
483 sole role is to separate the creation of ``.ovf`` file content.
485 OVFExporter class gathers information from ``config.ini`` file or
486 command line and performs necessary operations like disk conversion, disk
487 compression, manifest creation and OVA package creation.
489 Typical workflow for the export is even simpler, than for the import:
491 - read the ``config.ini`` file into memory
492 - gather information about certain parts of the instance, convert and
493 compress disks if desired
494 - save each of these elements as a fragment of XML tree
495 - save the XML tree as ``.ovf`` file
496 - create manifest file and fill it with appropriate checksums
497 - if ``--ova`` option was chosen, pack the results into ``.ova`` tarfile
503 - conversion to/from raw disk should be quicker
504 - add graphic card memory to export information (12 MB of memory)
505 - space requirements for conversion + compression + ova are currently
507 - add support for disks in chunks
508 - add support for certificates
509 - investigate why VMWare's ovftool does not work with ovfconverter's
510 compression and ova packaging -- maybe noteworty: if OVA archive does
511 not have a disk (i.e. in OVA package there is only .ovf ad .mf file),
512 then the ovftool works
513 - investigate why new versions of VirtualBox have problems with OVF
514 created by ovfconverter (everything works fine with 3.16 version, but
518 .. vim: set textwidth=72 :