Revision 97c60815 doc/design-ovf-support.rst

b/doc/design-ovf-support.rst
38 38
distribution (e.g. by allowing usage of public key infrastructure and
39 39
providing tools for management of basic software licensing).
40 40

  
41
There are no limitations regarding hard drive images used, as long as
42
the description is provided. Any hardware described in a proper
43
i.e. CIM - Common Information Model) format is accepted, although
44
there is no guarantee that every virtualization software will support
45
all types of hardware.
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
45
hardware.
46 46

  
47
OVF package should contain one file with ``.ovf`` extension, which is an
48
XML file specifying the following (per virtual machine):
47
OVF package should contain exactly one file with ``.ovf`` extension,
48
which is an XML file specifying the following (per virtual machine):
49 49

  
50 50
- virtual disks
51 51
- network description
......
58 58
Additionally, the package may have some disk image files and other
59 59
additional resources (e.g. ISO images).
60 60

  
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
66
to be present.
67

  
61 68
Supported disk formats
62 69
----------------------
63 70

  
64 71
Although OVF is claimed to support 'any disk format', what we are
65
interested in is which of the formats are supported by VM managers
66
that currently use OVF.
72
interested in is which formats are supported by VM managers that
73
currently use OVF.
67 74

  
68 75
- VMWare: ``.vmdk`` (which comes in at least 3 different flavours:
69 76
  ``sparse``, ``compressed`` and ``streamOptimized``)
......
74 81
- Red Hat Enterprise Virtualization: ``.raw`` (raw disk format),
75 82
  ``.cow`` (qemu's ``QCOW2``)
76 83
- other: AbiCloud, OpenNode Cloud, SUSE Studio, Morfeo Claudia,
77
  OpenStack
84
  OpenStack: mostly ``.vmdk``
78 85

  
79
In our implementation of the OVF we plan to allow a choice between
80
raw, cow and vmdk disk formats for export. We will not limit the import
81
formats in any way, but the used format has to be supported by qemu-img.
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, but not tested.
82 89
The justification is the following:
83 90

  
84 91
- Raw format is supported as it is the main format of disk images used
......
88 95
  has the advantage of producing relatively small disk images, which
89 96
  is extremely important advantage when moving instances.
90 97

  
91
The conversion between RAW and the other formats will be done using
92
qemu-img, which transforms, among other, raw disk images to monolithic
93
sparse vmdk images.
94

  
95 98
Import and export - the closer look
96 99
===================================
97 100

  
......
122 125
            <gnt:DiskTemplate</gnt:DiskTemplate>
123 126
            <gnt:OperatingSystem>
124 127
                <gnt:Name/>
125
                <gnt:Parameters>
126
                </gnt:Parameters>
128
                <gnt:Parameters></gnt:Parameters>
127 129
            </gnt:OperatingSystem>
128 130
            <gnt:Hypervisor>
129 131
                <gnt:Name/>
130
                <gnt:Parameters>
131
                </gnt:Parameters>
132
                <gnt:Parameters></gnt:Parameters>
132 133
            </gnt:Hypervisor>
133 134
            <gnt:Network>
134 135
            <gnt:Mode/>
......
151 152
  [instance]
152 153
      disk0_dump = filename     => File in References
153 154
      disk0_ivname = name       => generated automatically
154
      disk0_size = size_in_mb   => calculated after conversion to RAW
155
      disk0_size = size_in_mb   => calculated after disk conversion
155 156
      disk_count = number       => generated automatically
156 157
      disk_template = disk_type => gnt:DiskTemplate
157 158
      hypervisor = hyp-name     => gnt:Name in gnt:Hypervisor
......
195 196
If this happens you can specify all the missing parameters in
196 197
the command line. Please refer to `Command Line`_ section.
197 198

  
198
In the `user's manual <TODO: link to manual>`_ we provide examples of
199
In the :doc:`ovfconverter` we provide examples of
199 200
options when converting from VirtualBox, VMWare and OpenSuseStudio.
200 201

  
201 202
Export to other virtualization software
......
247 248
Disks
248 249
-----
249 250

  
250
As mentioned, Ganeti will allow exporting only ``raw``, ``cow`` and
251
``vmdk`` formats.  As for import, we will support all that
252
``qemu-img`` can convert to raw format. At this point this means
253
``raw``, ``cow``, ``qcow``, ``qcow2``, ``vmdk`` and ``cloop``.  We do
254
not plan for now to support ``vdi`` or ``vhd``.
251
As mentioned, Ganeti will allow export in  ``raw``, ``cow`` and ``vmdk``
252
formats.  This means i.e. that the appropriate ``ovf:format``
253
will be provided. It does not mean that other formats cannot be used,
254
rather that we did not test them.
255
As for import, we will support all formats that ``qemu-img`` can convert
256
to ``raw``. At this point this means ``raw``, ``cow``, ``qcow``,
257
``qcow2``, ``vmdk`` and ``cloop``.  We do not plan for now to support
258
``vdi`` or ``vhd`` unless they become part of qemu-img supported formats.
255 259

  
256
We plan to support compression both for import and export - in tar.gz
260
We plan to support compression both for import and export - in gzip
257 261
format. There is also a possibility to provide virtual disk in chunks
258 262
of equal size. The latter will not be implemented in the first version,
259 263
but we do plan to support it eventually.
260 264

  
261
The ``ovf:format`` tag is not used in our case. Instead we use
262
``qemu-img info``, which provides enough information for our purposes
263
and is better standardized.
265

  
266
The ``ovf:format`` tag is not used in our case when importing. Instead
267
we use ``qemu-img info``, which provides enough information for our
268
purposes and is better standardized.
264 269

  
265 270
Please note, that due to security reasons we require the disk image to
266 271
be in the same directory as the ``.ovf`` description file.
......
278 283
present, we perform a simple check - if network name specified in
279 284
``NetworkSection`` contains words ``bridged`` or ``routed``, we consider
280 285
this to be the network type. Otherwise option ``auto`` is chosen, in
281
which case the clusters' default value for that field will be used when
282
importing. This provides a safe fallback in case of NAT networks usage,
283
which are commonly used e.g. in VirtualBox.
286
which case the cluster's default value for that field will be used when
287
importing.
288
This provides a safe fallback in case of NAT networks usage, which are
289
commonly used e.g. in VirtualBox.
284 290

  
285 291
Hardware
286 292
--------
......
299 305
Other
300 306
-----
301 307

  
302
The instance name (``gnt:VirtualSystem\gnt:Name``) has to be resolvable
303
in order for successful import using ``gnt-backup import``.
308
The instance name (``gnt:VirtualSystem\gnt:Name`` or command line's
309
``--name`` option ) has to be resolvable in order for successful import
310
using ``gnt-backup import``.
311

  
304 312

  
305 313
_`Command Line`
306 314
===============
......
308 316
The basic usage of the ovf tool is one of the following::
309 317

  
310 318
    ovfconverter import filename
311
    ovfconverter export filename
319
    ovfconverter export --format=<format> filename
312 320

  
313 321
This will result in a conversion based solely on the content of provided
314 322
file. In case some information required to make the conversion is
......
339 347
Disks
340 348
^^^^^
341 349
``--disk-template=diskless`` causes the converter to ignore all other
342
disk option - both from .ovf file and the command line.
350
disk option - both from .ovf file and the command line. Other disk
351
template options include ``plain``, ``drdb``, ``file``, ``sharedfile``
352
and ``blockdev``.
343 353

  
344 354
``--disk=number:size=value`` causes to create disks instead of
345 355
converting them from OVF package; numbers should start with ``0`` and be
......
370 380
``--tags=tag1,tag2,tag3`` is a means of providing tags specific for the
371 381
instance.
372 382

  
383

  
373 384
After the conversion is completed, you may use ``gnt-backup import`` to
374 385
import the instance into Ganeti.
375 386

  
376 387
Example::
377 388

  
378
	ovfconverter file.ovf --disk-template=diskless \
379
                        --os-type=lenny-image \
380
                        --backend=vcpus=1,memory=512,auto_balance \
381
                        -H:xen-pvm \
382
                        --net=0:mode=bridged,link=xen-br0 \
383
                        --name=xen.i1 \
384
                        -v
385
	[output]
389
	ovfconverter import file.ovf --disk-template=diskless \
390
          --os-type=lenny-image \
391
          --backend=vcpus=1,memory=512,auto_balance \
392
          -H:xen-pvm \
393
          --net=0:mode=bridged,link=xen-br0 \
394
          --name=xen.i1
395
	[...]
386 396
	gnt-backup import xen.i1
387
	[output]
397
	[...]
388 398
	gnt-instance list
389 399

  
390 400
Export options
391 401
--------------
392 402
Export options include choice of disk formats to convert the disk image
393
(``--format``; default=``raw`` with no conversion) and compression of
394
the disk into tar.gz format (``--compress``).
395
User has also the choice of allowing to skip the Ganeti-specific part of
396
the OVF document (``--external``).
403
(``--format``) and compression of the disk into gzip format
404
(``--compress``). User has also the choice of allowing to skip the
405
Ganeti-specific part of the OVF document (``--external``).
397 406

  
398 407
By default, exported OVF package will not be contained in the OVA
399 408
package, but this may be changed by adding ``--ova`` option.
400 409

  
401
[TODO: examples of usage]
402

  
403 410
Please note that in order to create an OVF package, it is first
404 411
required that you export your VM using ``gnt-backup export``.
405 412

  
406
[TODO: complete example of export]
413
Example::
414

  
415
	gnt-backup export -n node1.xen xen.i1
416
	[...]
417
	ovfconverter export --format=vmdk --ova --external \
418
	  --output-dir=~/xen.i1 \
419
	  /srv/ganeti/export/xen.i1.node1.xen/config.ini
407 420

  
408 421
Implementation details
409 422
======================
......
412 425
---------------
413 426

  
414 427
Disk conversion for both import and export is done using external tool
415
called qemu-tools. The same tool is used to determine the type of disks.
428
called qemu-tools. The same tool is used to determine the type of disk,
429
as well as its virtual size.
416 430

  
417 431

  
418 432
Import
......
454 468

  
455 469
- save gathered information in ``config.ini`` file
456 470

  
457
ToDo
458
====
459

  
460
This lists functionalities for import that are not yet implemented, but
461
should be before the initial release:
462

  
463
- Support for compressed disks
464

  
465 471

  
466 472
.. vim: set textwidth=72 :
467 473
.. Local Variables:

Also available in: Unified diff