Documentation update for ovfconverter

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

doc/design-ovf-support.rst

@@ -85,7 +85,7 @@ currently use OVF.
 
 In our implementation of the OVF we allow a choice between raw, cow and
 vmdk disk formats for both import and export. Other formats covertable
-using ``qemu-img`` are allowed, but not tested.
+using ``qemu-img`` are allowed in import mode, but not tested.
 The justification is the following:
 
 - Raw format is supported as it is the main format of disk images used
@@ -250,8 +250,7 @@ Disks
 
 As mentioned, Ganeti will allow export in  ``raw``, ``cow`` and ``vmdk``
 formats.  This means i.e. that the appropriate ``ovf:format``
-will be provided. It does not mean that other formats cannot be used,
-rather that we did not test them.
+will be provided.
 As for import, we will support all formats that ``qemu-img`` can convert
 to ``raw``. At this point this means ``raw``, ``cow``, ``qcow``,
 ``qcow2``, ``vmdk`` and ``cloop``.  We do not plan for now to support
@@ -268,7 +267,8 @@ we use ``qemu-img info``, which provides enough information for our
 purposes and is better standardized.
 
 Please note, that due to security reasons we require the disk image to
-be in the same directory as the ``.ovf`` description file.
+be in the same directory as the ``.ovf`` description file for both
+import and export.
 
 In order to completely ignore disk-related information in resulting
 config file, please use ``--disk-template=diskless`` option.
@@ -302,6 +302,11 @@ Support for different operating systems depends solely on their
 accessibility for Ganeti instances. List of installed OSes can be
 checked using ``gnt-os list`` command.
 
+References
+----------
+
+Files listed in ``ovf:References`` section cannot be hyperlinks.
+
 Other
 -----
 
@@ -425,8 +430,8 @@ Disk conversion
 ---------------
 
 Disk conversion for both import and export is done using external tool
-called qemu-tools. The same tool is used to determine the type of disk,
-as well as its virtual size.
+called ``qemu-img``. The same tool is used to determine the type of
+disk, as well as its virtual size.
 
 
 Import
@@ -492,6 +497,24 @@ Typical workflow for the export is even simpler, than for the import:
 - if ``--ova`` option was chosen, pack the results into ``.ova`` tarfile
 
 
+Work in progress
+----------------
+
+- conversion to/from raw disk should be quicker
+- add graphic card memory to export information (12 MB of memory)
+- space requirements for conversion + compression + ova are currently
+  enormous
+- add support for disks in chunks
+- add support for certificates
+- investigate why VMWare's ovftool does not work with ovfconverter's
+  compression and ova packaging -- maybe noteworty: if OVA archive does
+  not have a disk (i.e. in OVA package there is only .ovf ad .mf file),
+  then the ovftool works
+- investigate why new versions of VirtualBox have problems with OVF
+  created by ovfconverter (everything works fine with 3.16 version, but
+  not with 4.0)
+
+
 .. vim: set textwidth=72 :
 .. Local Variables:
 .. mode: rst

doc/ovfconverter.rst

@@ -44,14 +44,59 @@ Neither USB nor CD-ROM drive are used in Ganeti. We decided to simply
 ignore unused elements of this section, so their presence won't raise
 any warnings.
 
-
 Operating System
 ----------------
 List of operating systems available on a cluster is viewable using
 ``gnt-os list`` command. When importing from external source, providing
 OS type in a command line (``--os-type=...``) is **required**. This is
-because rven if the type is given in OVF description, it is not detailed
+because even if the type is given in OVF description, it is not detailed
 enough for Ganeti to know which os-specific scripts to use.
+Please note, that instance containing disks may only be imported using
+OS script that supports raw disk images.
+
+References
+----------
+Files listed in ``ovf:References`` section cannot be hyperlinks.
+
+
+Limitations on export
+=====================
+
+Disk content
+------------
+Most Ganeti instances do not contain grub. This results in some
+problems when importing to virtualization software that does expect it.
+Examples of such software include VirtualBox and VMWare.
+
+To avoid trouble, please install grub inside the instance before
+exporting it.
+
+
+Import to VirtualBox
+--------------------
+``format`` option should be set to ``vmdk`` in order for instance to be
+importable by VirtualBox.
+
+Tests using existing versions of VirtualBox (3.16) suggest, that
+VirtualBox does not support disk compression or OVA packaging. In future
+versions this might change.
+
+
+Import to VMWare
+----------------
+Importing Ganeti instance to VMWare was tested using ``ovftool``.
+
+``format`` option should be set to ``vmdk`` in order for instance to be
+importable by VMWare.
+
+Presence of Ganeti section does seem to cause some problems and
+therefore it is recommended to use ``--external`` option on export.
+
+Import of compressed disks generated by ovfconverter was impossible in
+current version of ``ovftool`` (2.1.0). This seems to be related to old
+``vmdk`` version. Since the conversion to ``vmdk`` format is done using
+``qemu-img``, it is possible and in fact expected, that future versions
+of the latter tool will resolve this problem.
 
 
 Import examples
@@ -130,11 +175,34 @@ Ganeti-specific configuration to be saved. In that case, simply use the
 Known issues
 ============
 
-Export
-------
-When exporting to **VirtualBox**, you may encounter errors regarding
-network. If that is the case, simply change the network type in options
-to ``NAT``.
+Conversion errors
+-----------------
+If you are encountering trouble when converting the disk, please ensure
+that you have newest ``qemu-img`` version.
+
+OVA and compression
+-------------------
+The compressed disks and OVA packaging do not work correctly in either
+VirtualBox (old version) or VMWare.
+
+VirtualBox (3.16 OSE) does not seem to support those two, so there is
+very little we can do about this.
+
+As for VMWare, the reason behind it not accepting compressed or packed
+instances created by ovfconverter seems to be related to the old vmdk
+version.
+
+Problems on newest VirtualBox
+-----------------------------
+In Oracle VM Virtualbox 4.0+ there seems to be a problem when importing
+any OVF instance created by ovfconverter. Reasons are again unknown,
+this will be investigated.
+
+Disk space
+----------
+The disk space requirements for both import and export are at the moment
+very large - we require free space up to about 3-4 times the size of
+disks. This will most likely be changed in future versions.
 
 
 .. vim: set textwidth=72 :