code.grnet.gr Git - ganeti-local/blob - doc/ovfconverter.rst

   1 =============
   2 OVF converter
   3 =============
   4
   5 Using ``ovfconverter`` from the ``tools`` directory, one can easily
   6 convert previously exported Ganeti instance into OVF package, supported
   7 by VMWare, VirtualBox and some other virtualization software. It is
   8 also possible to use instance exported from such a tool and convert it
   9 to Ganeti config file, used by ``gnt-backup import`` command.
  10
  11 For the internal design of the converter and more detailed description,
  12 including listing of available command line options, please refer to
  13 :doc:`design-ovf-support`
  14
  15 As the amount of Ganeti-specific details, that need to be provided in
  16 order to import an external instance, is rather large, we will present
  17 here some examples of importing instances from different sources.
  18 It is also worth noting that there are some limitations regarding
  19 support for different hardware.
  20
  21 Limitations on import
  22 =====================
  23
  24 Network
  25 -------
  26 Available modes for the network include ``bridged`` and ``routed``.
  27 There is no ``NIC`` mode, which is typically used e.g. by VirtualBox.
  28 For most usecases this should not be of any effect, since if
  29 ``NetworkSection`` contains any networks which are not discovered as
  30 ``bridged`` or ``routed``, the network mode is assigned automatically,
  31 using Ganeti's cluster defaults.
  32
  33 Backend
  34 -------
  35 The only values that are taken into account regarding Virtual Hardware
  36 (described in ``VirtualHardwareSection`` of the ``.ovf`` file) are:
  37
  38 - number of virtual CPUs
  39 - RAM memory
  40 - hard disks
  41 - networks
  42
  43 Neither USB nor CD-ROM drive are used in Ganeti. We decided to simply
  44 ignore unused elements of this section, so their presence won't raise
  45 any warnings.
  46
  47 Operating System
  48 ----------------
  49 List of operating systems available on a cluster is viewable using
  50 ``gnt-os list`` command. When importing from external source, providing
  51 OS type in a command line (``--os-type=...``) is **required**. This is
  52 because even if the type is given in OVF description, it is not detailed
  53 enough for Ganeti to know which os-specific scripts to use.
  54 Please note, that instance containing disks may only be imported using
  55 OS script that supports raw disk images.
  56
  57 References
  58 ----------
  59 Files listed in ``ovf:References`` section cannot be hyperlinks.
  60
  61
  62 Limitations on export
  63 =====================
  64
  65 Disk content
  66 ------------
  67 Most Ganeti instances do not contain grub. This results in some
  68 problems when importing to virtualization software that does expect it.
  69 Examples of such software include VirtualBox and VMWare.
  70
  71 To avoid trouble, please install grub inside the instance before
  72 exporting it.
  73
  74
  75 Import to VirtualBox
  76 --------------------
  77 ``format`` option should be set to ``vmdk`` in order for instance to be
  78 importable by VirtualBox.
  79
  80 Tests using existing versions of VirtualBox (3.16) suggest, that
  81 VirtualBox does not support disk compression or OVA packaging. In future
  82 versions this might change.
  83
  84
  85 Import to VMWare
  86 ----------------
  87 Importing Ganeti instance to VMWare was tested using ``ovftool``.
  88
  89 ``format`` option should be set to ``vmdk`` in order for instance to be
  90 importable by VMWare.
  91
  92 Presence of Ganeti section does seem to cause some problems and
  93 therefore it is recommended to use ``--external`` option on export.
  94
  95 Import of compressed disks generated by ovfconverter was impossible in
  96 current version of ``ovftool`` (2.1.0). This seems to be related to old
  97 ``vmdk`` version. Since the conversion to ``vmdk`` format is done using
  98 ``qemu-img``, it is possible and in fact expected, that future versions
  99 of the latter tool will resolve this problem.
 100
 101
 102 Import examples
 103 ===============
 104
 105 Ganeti's OVF
 106 ------------
 107 If you are importing instance created using ``ovfconverter export`` --
 108 you most probably will not have to provide any additional information.
 109 In that case, the following is all you need (unless you wish to change
 110 some configuration options)::
 111
 112         ovfconverter import ganeti.ovf
 113         [...]
 114         gnt-instance import -n <node> <instance name>
 115
 116
 117 Virtualbox, VMWare and other external sources
 118 ---------------------------------------------
 119 In case of importing from external source, you will most likely have to
 120 provide the following details:
 121
 122 - ``os-type`` can be any operating system listed on ``gnt-os list``
 123 - ``name`` that has to be resolvable, as it will be used as instance
 124   name (even if your external instance has a name, it most probably is
 125   not resolvable to an IP address)
 126
 127 These are not the only options, but the recommended ones. For the
 128 complete list of available options please refer to
 129 `Command Line description <design-ovf-support.rst>`
 130
 131 Minimalistic but complete example of importing Virtualbox's OVF
 132 instance may look like::
 133
 134     ovfconverter virtualbox.ovf --os-type=lenny-image \
 135       --name=xen.test.i1 --disk-template=diskless
 136     [...]
 137     gnt-instance import -n node1.xen xen.test.i1
 138
 139
 140
 141 Export example
 142 ==============
 143
 144 Exporting instance into ``.ovf`` format is pretty streightforward and
 145 requires little - if any - explanation. The only compulsory detail is
 146 the required disk format, provided using the ``--format`` option.
 147
 148 Export to another Ganeti instance
 149 ---------------------------------
 150 If for some reason it is convenient for you to use ``ovfconverter`` to
 151 move instance between clusters (e.g. because of the disk compression),
 152 the complete example of export may look like this::
 153
 154     gnt-backup export -n node1.xen xen.test.i1
 155     [...]
 156     ovfconverter export --format=vmdk --ova \
 157       /srv/ganeti/export/xen.i1.node1.xen/config.ini
 158     [...]
 159
 160 The result is then in
 161 ``/srv/ganeti/export/xen.i1.node1.xen/xen.test.i1.ova``
 162
 163 Export to Virtualbox/VMWare/other external tool
 164 -----------------------------------------------
 165 Typically, when exporting to external tool we do not want
 166 Ganeti-specific configuration to be saved. In that case, simply use the
 167 ``--external`` option::
 168
 169     gnt-backup export -n node1.xen xen.test.i1
 170     [...]
 171     ovfconverter export --external --output-dir ~/ganeti-instance/ \
 172       /srv/ganeti/export/xen.i1.node1.xen/config.ini
 173
 174
 175 Known issues
 176 ============
 177
 178 Conversion errors
 179 -----------------
 180 If you are encountering trouble when converting the disk, please ensure
 181 that you have newest ``qemu-img`` version.
 182
 183 OVA and compression
 184 -------------------
 185 The compressed disks and OVA packaging do not work correctly in either
 186 VirtualBox (old version) or VMWare.
 187
 188 VirtualBox (3.16 OSE) does not seem to support those two, so there is
 189 very little we can do about this.
 190
 191 As for VMWare, the reason behind it not accepting compressed or packed
 192 instances created by ovfconverter seems to be related to the old vmdk
 193 version.
 194
 195 Problems on newest VirtualBox
 196 -----------------------------
 197 In Oracle VM Virtualbox 4.0+ there seems to be a problem when importing
 198 any OVF instance created by ovfconverter. Reasons are again unknown,
 199 this will be investigated.
 200
 201 Disk space
 202 ----------
 203 The disk space requirements for both import and export are at the moment
 204 very large - we require free space up to about 3-4 times the size of
 205 disks. This will most likely be changed in future versions.
 206
 207
 208 .. vim: set textwidth=72 :
 209 .. Local Variables:
 210 .. mode: rst
 211 .. fill-column: 72
 212 .. End: