Extend the ovf-support design with format translation

Signed-off-by: Agata Murawska <agatamurawska@google.com>
Signed-off-by: Iustin Pop <iustin@google.com>
Reviewed-by: Iustin Pop <iustin@google.com>

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
 ======================