diff --git a/doc/design-ovf-support.rst b/doc/design-ovf-support.rst index d238259a72143c025c708f16801d755d7214a723..060d47663b713e236337cf911f6aa25b1d0a7bb1 100644 --- a/doc/design-ovf-support.rst +++ b/doc/design-ovf-support.rst @@ -44,7 +44,7 @@ i.e. CIM - Common Information Model) format 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 +OVF package should contain one file with ``.ovf`` extension, which is an XML file specifying the following (per virtual machine): - virtual disks @@ -52,7 +52,7 @@ XML file specifying the following (per virtual machine): - list of virtual hardware - operating system, if any -Each of the elements in .ovf file may, if desired, contain a +Each of the elements in ``.ovf`` file may, if desired, contain a human-readable description to every piece of information given. Additionally, the package may have some disk image files and other @@ -92,6 +92,116 @@ 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 +=================================== + +This section contains an overview of how different parts of +Ganeti's export info are included in ``.ovf`` configuration file. +It also explains how import is designed to work with incomplete +information. + +Ganeti's backup format vs OVF +----------------------------- +.. highlight:: xml + +The basic structure of Ganeti ``.ovf`` file is the following:: + + <Envelope> + <References></References> + <DiskSection></DiskSection> + <NetworkSection></NetworkSection> + <VirtualSystem> + <Name></Name> + <OperatingSystemSection></OperatingSystemSection> + <VirtualHardwareSection><VirtualHardwareSection> + </VirtualSystem> + <gnt:GanetiSection> + <gnt:VersionId/> + <gnt:AutoBalance/> + <gnt:Tags></gnt:Tags> + <gnt:OSParameters></gnt:OSParameters> + <gnt:Hypervisor> + <gnt:HypervisorParameters> + </gnt:HypervisorParameters> + </gnt:Hypervisor> + </gnt:GanetiSection> + </Envelope> + +.. note :: + Tags with ``gnt:`` prefix are Ganeti-specific and are not a part of + OVF standard. + +.. highlight:: text + +Whereas Ganeti's export info is of the following form, ``=>`` showing +where will the data be in OVF format:: + + [instance] + disk0_dump = filename => References + disk0_ivname = name => ignored + disk0_size = size_in_mb => DiskSection + disk_count = number => ignored + disk_template = disk_type => References + hypervisor = hyp-name => gnt:HypervisorSection + name = inst-name => Name in VirtualSystem + nic0_ip = ip => Item in VirtualHardwareSection + nic0_link = link => Item in VirtualHardwareSection + nic0_mac = mac => Item in VirtualHardwareSection + nic0_mode = mode => Network in NetworkSection + nic_count = number => ignored + tags => gnt:Tags + + [backend] + auto_balanced => gnt:AutoBalance + memory = mem_in_mb => Item in VirtualHardwareSection + vcpus = number => Item in VirtualHardwareSection + + [export] + compression => DiskSection + os => OperatingSystemSection + source => ignored + timestamp => ignored + version => gnt:VersionId + + [os] => gnt:OSParameters + + [hypervisor] => gnt:HypervisorParameters + +In case of multiple networks/disks used by an instance, they will +all be saved in appropriate sections as specified above for the first +network/disk. + +Import from other virtualization software +----------------------------------------- +In case of importing to Ganeti OVF package generated in other software, +e.g. VirtualBox, some fields required for Ganeti to properly handle +import may be missing. Most often it will happen that such OVF package +will lack the ``gnt:GanetiSection``. + +If this happens, the tool will simply ask for all the necessary +information or otherwise you can specify all the missing parameters in +the command line. For the latter, please refer to [TODO: reference to +command line options] + +Export to other virtualization software +--------------------------------------- +When exporting to other virtualization software, you may notice that +there is a section ``gnt:GanetiSection``, containing Ganeti-specific +information. This may on **rare** cases cause trouble in importing your +instance. If that is the case please do one of the two: + +1. Export from Ganeti to OVF with ``--external`` option - this will +cause to skip the non-standard information. + +2. Manually remove the gnt:GanetiSection from the ``.ovf`` file. You +will also have to recompute sha1 sum (``sha1sum`` command) and update +your ``.mf`` file with new value. + +.. note:: + Manual change option is only recommended when you have exported your + instance with ``-format`` option other that ``raw`` or selected + ``--compress``. It saves you the time of converting or compressing + the disk image. Planned limitations =================== @@ -107,8 +217,8 @@ Package ------- There are no limitations regarding support for multiple files in -package or packing the ovf package into one OVA (Open Virtual -Appliance) file. As for certificates and licenses in the package, +package or packing the OVF package into one OVA (Open Virtual +Appliance) file. As for certificates and licenses in the package, their support will be under discussion after completion of the basic features implementation. @@ -129,9 +239,9 @@ As mentioned, Ganeti will allow exporting only ``raw``, ``cow`` and ``raw``, ``cow``, ``qcow``, ``qcow2``, ``vmdk`` and ``cloop``. We do not plan for now to support ``vdi`` or ``vhd``. -We support compression both for import and export - for export this -will use ovftools with chosen level of compression. There is also a -possibility to provide virtual disk in chunks of equal size. +We plan to support compression both for import and export - in tar.gz +format. There is also a possibility to provide virtual disk in chunks +of equal size. When no ``ovf:format`` tag is provided during import, we assume that the disk is to be created on import and proceed accordingly. @@ -154,6 +264,7 @@ TODO Other ----- + Implementation details ======================