Import: further doc updates

Signed-off-by: Agata Murawska <agatamurawska@google.com>
Signed-off-by: René Nussbaumer <rn@google.com>
Reviewed-by: René Nussbaumer <rn@google.com>

doc/design-ovf-support.rst

@@ -38,14 +38,14 @@ host- and virtualization platform-independent and optimized for
 distribution (e.g. by allowing usage of public key infrastructure and
 providing tools for management of basic software licensing).
 
-There are no limitations regarding hard drive images used, as long as
-the description is provided. Any hardware described in a proper
-i.e. CIM - Common Information Model) format is accepted, although
-there is no guarantee that every virtualization software will support
-all types of hardware.
+There are no limitations regarding disk images used, as long as the
+description is provided. Any hardware described in a proper format
+(i.e. CIM - Common Information Model) 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
-XML file specifying the following (per virtual machine):
+OVF package should contain exactly one file with ``.ovf`` extension,
+which is an XML file specifying the following (per virtual machine):
 
 - virtual disks
 - network description
@@ -58,12 +58,19 @@ human-readable description to every piece of information given.
 Additionally, the package may have some disk image files and other
 additional resources (e.g. ISO images).
 
+In order to provide secure means of distribution for OVF packages, the
+manifest and certificate are provided. Manifest (``.mf`` file) contains
+checksums for all the files in OVF package, whereas certificate
+(``.cert`` file) contains X.509 certificate and a checksum of manifest
+file. Both files are not compulsory, but certificate requires manifest
+to be present.
+
 Supported disk formats
 ----------------------
 
 Although OVF is claimed to support 'any disk format', what we are
-interested in is which of the formats are supported by VM managers
-that currently use OVF.
+interested in is which formats are supported by VM managers that
+currently use OVF.
 
 - VMWare: ``.vmdk`` (which comes in at least 3 different flavours:
   ``sparse``, ``compressed`` and ``streamOptimized``)
@@ -74,11 +81,11 @@ that currently use OVF.
 - Red Hat Enterprise Virtualization: ``.raw`` (raw disk format),
   ``.cow`` (qemu's ``QCOW2``)
 - other: AbiCloud, OpenNode Cloud, SUSE Studio, Morfeo Claudia,
-  OpenStack
+  OpenStack: mostly ``.vmdk``
 
-In our implementation of the OVF we plan to allow a choice between
-raw, cow and vmdk disk formats for export. We will not limit the import
-formats in any way, but the used format has to be supported by qemu-img.
+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.
 The justification is the following:
 
 - Raw format is supported as it is the main format of disk images used
@@ -88,10 +95,6 @@ The justification is the following:
   has the advantage of producing relatively small disk images, which
   is extremely important advantage when moving instances.
 
-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
 ===================================
 
@@ -122,13 +125,11 @@ The basic structure of Ganeti ``.ovf`` file is the following::
             <gnt:DiskTemplate</gnt:DiskTemplate>
             <gnt:OperatingSystem>
                 <gnt:Name/>
-                <gnt:Parameters>
-                </gnt:Parameters>
+                <gnt:Parameters></gnt:Parameters>
             </gnt:OperatingSystem>
             <gnt:Hypervisor>
                 <gnt:Name/>
-                <gnt:Parameters>
-                </gnt:Parameters>
+                <gnt:Parameters></gnt:Parameters>
             </gnt:Hypervisor>
             <gnt:Network>
             <gnt:Mode/>
@@ -151,7 +152,7 @@ where will the data be in OVF format::
   [instance]
       disk0_dump = filename     => File in References
       disk0_ivname = name       => generated automatically
-      disk0_size = size_in_mb   => calculated after conversion to RAW
+      disk0_size = size_in_mb   => calculated after disk conversion
       disk_count = number       => generated automatically
       disk_template = disk_type => gnt:DiskTemplate
       hypervisor = hyp-name     => gnt:Name in gnt:Hypervisor
@@ -195,7 +196,7 @@ will lack the ``gnt:GanetiSection``.
 If this happens you can specify all the missing parameters in
 the command line. Please refer to `Command Line`_ section.
 
-In the `user's manual <TODO: link to manual>`_ we provide examples of
+In the :doc:`ovfconverter` we provide examples of
 options when converting from VirtualBox, VMWare and OpenSuseStudio.
 
 Export to other virtualization software
@@ -247,20 +248,24 @@ option.
 Disks
 -----
 
-As mentioned, Ganeti will allow exporting only ``raw``, ``cow`` and
-``vmdk`` formats.  As for import, we will support all that
-``qemu-img`` can convert to raw format. At this point this means
-``raw``, ``cow``, ``qcow``, ``qcow2``, ``vmdk`` and ``cloop``.  We do
-not plan for now to support ``vdi`` or ``vhd``.
+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.
+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
+``vdi`` or ``vhd`` unless they become part of qemu-img supported formats.
 
-We plan to support compression both for import and export - in tar.gz
+We plan to support compression both for import and export - in gzip
 format. There is also a possibility to provide virtual disk in chunks
 of equal size. The latter will not be implemented in the first version,
 but we do plan to support it eventually.
 
-The ``ovf:format`` tag is not used in our case. Instead we use
-``qemu-img info``, which provides enough information for our purposes
-and is better standardized.
+
+The ``ovf:format`` tag is not used in our case when importing. Instead
+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.
@@ -278,9 +283,10 @@ used network type, we add our own source of such information in
 present, we perform a simple check - if network name specified in
 ``NetworkSection`` contains words ``bridged`` or ``routed``, we consider
 this to be the network type. Otherwise option ``auto`` is chosen, in
-which case the clusters' default value for that field will be used when
-importing. This provides a safe fallback in case of NAT networks usage,
-which are commonly used e.g. in VirtualBox.
+which case the cluster's default value for that field will be used when
+importing.
+This provides a safe fallback in case of NAT networks usage, which are
+commonly used e.g. in VirtualBox.
 
 Hardware
 --------
@@ -299,8 +305,10 @@ checked using ``gnt-os list`` command.
 Other
 -----
 
-The instance name (``gnt:VirtualSystem\gnt:Name``) has to be resolvable
-in order for successful import using ``gnt-backup import``.
+The instance name (``gnt:VirtualSystem\gnt:Name`` or command line's
+``--name`` option ) has to be resolvable in order for successful import
+using ``gnt-backup import``.
+
 
 _`Command Line`
 ===============
@@ -308,7 +316,7 @@ _`Command Line`
 The basic usage of the ovf tool is one of the following::
 
     ovfconverter import filename
-    ovfconverter export filename
+    ovfconverter export --format=<format> filename
 
 This will result in a conversion based solely on the content of provided
 file. In case some information required to make the conversion is
@@ -339,7 +347,9 @@ omitted ones will be set to cluster defaults (``auto``).
 Disks
 ^^^^^
 ``--disk-template=diskless`` causes the converter to ignore all other
-disk option - both from .ovf file and the command line.
+disk option - both from .ovf file and the command line. Other disk
+template options include ``plain``, ``drdb``, ``file``, ``sharedfile``
+and ``blockdev``.
 
 ``--disk=number:size=value`` causes to create disks instead of
 converting them from OVF package; numbers should start with ``0`` and be
@@ -370,40 +380,43 @@ Tags
 ``--tags=tag1,tag2,tag3`` is a means of providing tags specific for the
 instance.
 
+
 After the conversion is completed, you may use ``gnt-backup import`` to
 import the instance into Ganeti.
 
 Example::
 
-	ovfconverter file.ovf --disk-template=diskless \
-                        --os-type=lenny-image \
-                        --backend=vcpus=1,memory=512,auto_balance \
-                        -H:xen-pvm \
-                        --net=0:mode=bridged,link=xen-br0 \
-                        --name=xen.i1 \
-                        -v
-	[output]
+	ovfconverter import file.ovf --disk-template=diskless \
+          --os-type=lenny-image \
+          --backend=vcpus=1,memory=512,auto_balance \
+          -H:xen-pvm \
+          --net=0:mode=bridged,link=xen-br0 \
+          --name=xen.i1
+	[...]
 	gnt-backup import xen.i1
-	[output]
+	[...]
 	gnt-instance list
 
 Export options
 --------------
 Export options include choice of disk formats to convert the disk image
-(``--format``; default=``raw`` with no conversion) and compression of
-the disk into tar.gz format (``--compress``).
-User has also the choice of allowing to skip the Ganeti-specific part of
-the OVF document (``--external``).
+(``--format``) and compression of the disk into gzip format
+(``--compress``). User has also the choice of allowing to skip the
+Ganeti-specific part of the OVF document (``--external``).
 
 By default, exported OVF package will not be contained in the OVA
 package, but this may be changed by adding ``--ova`` option.
 
-[TODO: examples of usage]
-
 Please note that in order to create an OVF package, it is first
 required that you export your VM using ``gnt-backup export``.
 
-[TODO: complete example of export]
+Example::
+
+	gnt-backup export -n node1.xen xen.i1
+	[...]
+	ovfconverter export --format=vmdk --ova --external \
+	  --output-dir=~/xen.i1 \
+	  /srv/ganeti/export/xen.i1.node1.xen/config.ini
 
 Implementation details
 ======================
@@ -412,7 +425,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 disks.
+called qemu-tools. The same tool is used to determine the type of disk,
+as well as its virtual size.
 
 
 Import
@@ -454,14 +468,6 @@ Typical workflow for the import is very simple:
 
 - save gathered information in ``config.ini`` file
 
-ToDo
-====
-
-This lists functionalities for import that are not yet implemented, but
-should be before the initial release:
-
-- Support for compressed disks
-
 
 .. vim: set textwidth=72 :
 .. Local Variables:

doc/index.rst

@@ -29,6 +29,7 @@ Contents:
    iallocator.rst
    rapi.rst
    move-instance.rst
+   ovfconverter.rst
    devnotes.rst
    news.rst
    glossary.rst

doc/ovfconverter.rst

+=============
+OVF converter
+=============
+
+Using ``ovfconverter`` from the ``tools`` directory, one can easily
+convert previously exported Ganeti instance into OVF package, supported
+by VMWare, VirtualBox and some other virtualization software. It is
+also possible to use instance exported from such a tool and convert it
+to Ganeti config file, used by ``gnt-backup import`` command.
+
+For the internal design of the converter and more detailed description,
+including listing of available command line options, please refer to
+:doc:`design-ovf-support`
+
+As the amount of Ganeti-specific details, that need to be provided in
+order to import an external instance, is rather large, we will present
+here some examples of importing instances from different sources.
+It is also worth noting that there are some limitations regarding
+support for different hardware.
+
+Limitations on import
+=====================
+
+Network
+-------
+Available modes for the network include ``bridged`` and ``routed``.
+There is no ``NIC`` mode, which is typically used e.g. by VirtualBox.
+For most usecases this should not be of any effect, since if
+``NetworkSection`` contains any networks which are not discovered as
+``bridged`` or ``routed``, the network mode is assigned automatically,
+using Ganeti's cluster defaults.
+
+Backend
+-------
+The only values that are taken into account regarding Virtual Hardware
+(described in ``VirtualHardwareSection`` of the ``.ovf`` file) are:
+
+- number of virtual CPUs
+- RAM memory
+- hard disks
+- networks
+
+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
+enough for Ganeti to know which os-specific scripts to use.
+
+
+Import examples
+===============
+
+Ganeti's OVF
+------------
+If you are importing instance created using ``ovfconverter export`` --
+you most probably will not have to provide any additional information.
+In that case, the following is all you need (unless you wish to change
+some configuration options)::
+
+	ovfconverter import ganeti.ovf
+	[...]
+	gnt-instance import -n <node> <instance name>
+
+
+Virtualbox, VMWare and other external sources
+---------------------------------------------
+In case of importing from external source, you will most likely have to
+provide the following details:
+
+- ``os-type`` can be any operating system listed on ``gnt-os list``
+- ``name`` that has to be resolvable, as it will be used as instance
+  name (even if your external instance has a name, it most probably is
+  not resolvable to an IP address)
+
+These are not the only options, but the recommended ones. For the
+complete list of available options please refer to
+`Command Line description <design-ovf-support.rst>`
+
+Minimalistic but complete example of importing Virtualbox's OVF
+instance may look like::
+
+    ovfconverter virtualbox.ovf --os-type=lenny-image \
+      --name=xen.test.i1 --disk-template=diskless
+    [...]
+    gnt-instance import -n node1.xen xen.test.i1
+
+
+.. vim: set textwidth=72 :
+.. Local Variables:
+.. mode: rst
+.. fill-column: 72
+.. End: