[sheepdog] [PATCH] Add "Introduction" section of the SHEEPDOG ADMINISTRATOR GUIDE.

[Liu Yuan]

Hi Valerio,

    Thanks for your great work. Some strivial comments below.

On Sat, Sep 21, 2013 at 11:33:08AM +0200, Valerio Pachera wrote:
> This manual may help users that download sheepdog sources and whant to install and start a cluster.
> Next sectiona only need a short review and will be add soon.
> 

We should keep commit log at most 80 characters per line as convention.

>
> Signed-off-by: Valerio Pachera <sirio81 at gmail.com>
> ---
>  doc/about_this_guide.rst     |   27 ++++++++++++++++++
>  doc/author_and_licensing.rst |   16 +++++++++++
>  doc/goals.rst                |   49 ++++++++++++++++++++++++++++++++
>  doc/index.rst                |   63 ++++++++++++++++++++++++++++++++++++++++++
>  doc/main_futures.rst         |   13 +++++++++
>  doc/project_history.rst      |    5 ++++
>  doc/project_status.rst       |   16 +++++++++++
>  7 files changed, 189 insertions(+)
>  create mode 100644 doc/about_this_guide.rst
>  create mode 100644 doc/author_and_licensing.rst
>  create mode 100644 doc/goals.rst
>  create mode 100644 doc/index.rst
>  create mode 100644 doc/main_futures.rst
>  create mode 100644 doc/project_history.rst
>  create mode 100644 doc/project_status.rst
> 
> diff --git a/doc/about_this_guide.rst b/doc/about_this_guide.rst
> new file mode 100644
> index 0000000..40601fa
> --- /dev/null
> +++ b/doc/about_this_guide.rst
> @@ -0,0 +1,27 @@
> +About This Guide
> +================
> +
> +This guide is for users who intend to install and administer a sheepdog cluster.
> +
> +It's divided in three main sections:
> +
> +- Sheepdog Basics
> +- Sheepdog Advanced Use
> +- Suggestions And Special Cases
> +
> +You have to be familiar with GNU/Linux operation systems, the shell, networking and virtualization (in general), ssh and kvm (specifically).
> +In this guide we use a "simple" scenario of a small cluster with 4 nodes.
> +
> +Here are some of the terms used in this document:
> +
> +::
> +
> +    cluster = group of servers
> +    host = a server
> +    vm / guest = a virtual machine running on a host
> +    node = a host running sheepdog

better as
node = a host running sheepdog daemon

> +    vdi = virtual disk used by sheepdog

better as
vdi = virtual disk image, exported by sheepdog as a thin-provision virtual
      disk for the guest.

>
> +    sheep = vary according to the context. It may be
> +        - the sheepdog daemon process name
> +        - the command to run the daemon
> +        - the host running the daemon

I think for third case, we should use 'node'.

>
> diff --git a/doc/author_and_licensing.rst b/doc/author_and_licensing.rst
> new file mode 100644
> index 0000000..4eaf4c9
> --- /dev/null
> +++ b/doc/author_and_licensing.rst
> @@ -0,0 +1,16 @@
> +Author And Licensing
> +====================
> +
> +|cc logo| 
> +
> +This manual has been created by *Valerio Pachera* for the Sheepdog Project and it's released under `Creative Commons Attribution 3.0 Unported`_ license.
> +
> +.. _`Creative Commons Attribuzione 3.0 Unported`: http://creativecommons.org/licenses/by/3.0/deed.it
> +
> +.. |cc logo| image:: http://i.creativecommons.org/l/by/3.0/88x31.png
> +    :scale: 200 %
> +    :alt: Creative Commons Logo
> +    :target: http://creativecommons.org/licenses/by/3.0/deed.it
> +    
> +.. commento
> +    
> \ No newline at end of file
> diff --git a/doc/goals.rst b/doc/goals.rst
> new file mode 100644
> index 0000000..7c3abeb
> --- /dev/null
> +++ b/doc/goals.rst
> @@ -0,0 +1,49 @@
> +Goals
> +=====
> +
> +Common Problems Related To Virtual Server Management:
> +*****************************************************
> +
> +Host Dependence:
> +    A virtualized environment allows several operation systems to run on a single physical server.

operation system -> operating system ?

> +    This results in better resource optimization but it implies more services going down if the host has problems.

resource optimization -> resource utilization ?

> +    Eventually we'll have to do some maintenance on our servers or they may simply stop working.
> +    When we stop a host, it would be a good thing to be able to run its guests on another server.
> +    
> +Downtime:
> +    We may copy the guests files to a second server or even move the physical hard disks on it.
> +    This requires time, effort and probably the physical access to the servers.
> +    
> +Single Point of Failure:
> +    Another common solution is to have a shared storage.
> +    That simply means to have a nfs folder on a nas like server, where our guests disks are stored.
> +    This way, if the server running the virtual machines (name it front-end server) needs maintenance, we may simply start the guests on the second server.
> +    But what do we do if the nas breaks down?
> +
> +Resource waste:
> +    The disadvantage of this approach is that we need more hardware for the back-end (the shared storage) but we still have to worry about the back-end failover.
> +    Furthermore, the hard disks on the front-end hosts are almost useless.
> +    
> +Raid complexity:
> +    It's common practice to use RAID (1,5,6,10) to avoid down time due to disk failure.
> +    This implies to buy hardware controllers or to use software RAID.
> +
> +Sheepdog Benefits
> +*****************
> +
> +Host Independence:
> +    We can run any guest on any host of the cluster, as with a common shared storage.
> +    
> +Less Downtime:
> +    Because of the host independence, we do not need to fix the broken host before running its guests.
> +    
> +No Single Point of Failure:
> +    There's not a single shared storage.
> +    Multiple hosts failure can be easily handled.
> +    
> +Less Resource Waste:
> +    Each node is, at the same time, a virtualization and storage server.
> +    
> +No Raid Necessary:
> +    Sheepdog doesn't manage a single device but as many as we wish.

how about
A single node in the sheepdog cluster can manage as much as unlimited disks
within the server in a RAID0 like way.

>
> +    It also manages disks in a clever way to reduce network traffic in case of a single disk failure.
> diff --git a/doc/index.rst b/doc/index.rst
> new file mode 100644
> index 0000000..71e1679
> --- /dev/null
> +++ b/doc/index.rst
> @@ -0,0 +1,63 @@
> +
> +SHEEPDOG ADMINISTRATOR GUIDE
> +============================
> +
> +Sheepdog is a distributed storage system for QEMU/KVM. It provides highly available block level storage volumes that can be attached to QEMU/KVM virtual machines. Sheepdog scales to several hundreds nodes, and supports advanced volume management features such as snapshot, cloning, and thin provisioning.

We are not bound to KVM actually, our virtual disk driver is intergrated in the
QEMU. So QEMU/KVM --> QEMU.

As a general trivial comment, we should also keep 80 characters per line too for
the content.

Thanks
Yuan