Added Aptira's Remaining Training Material

Brief Summary:

    Added Modules and Lab Sections of Aptira's Existing
    OpenStack Training Docs. Please do refer Full Summary
    for more details.

    For those who want to review this and save some time on
    building it, I have hosted the content on

                http://office.aptira.in

    Please talk to Sean Robetrs if you are concerened about
    repetition of Doc Content or similar issues like short URLs
    etc., this is supposed to be a rough patch and not final.

Full Summary:

    Added the following modules.

        1. Module001 - Introduction To OpenStack.
                     - Brief Overview of OpenStack.
                     - Basic Concepts
                     - Detailed Description of Core
                       Projects (Grizzly) under OpenStack.
                     - All But Networking and Swift.
        2. Module002 - OpenStack Networking In detail.
        3. Module003 - OpenStack Object Storage In detail.
        4. Lab001    - OpenStack Control Node and Compute Node.
        5. Lab002    - OpenStack Network Node.

    Full Summary added due to the size of the commit. I Apologize
    for the size of this commit and will try not to commit huge
    content like in this patch. The reason for the size of this
    commit is to meet OpenStack Training Sprint day.

bp/training-manuals

Change-Id: Ie3c44527992868b4d9571b66cc1c048e558ec669

doc/training-guide/lab000-important-terms.xml

@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="5.0"
+  xml:id="lab000-important-terms">
+  <title>Important Terms</title>
+  <para><emphasis role="bold">Host Operating System (Host)
+      :</emphasis></para>
+  <para>‘Host OS’ or ‘Host’ is commonly referred to the Operating
+    System installed on your hardware (Laptop/Desktop) and hosts the
+    virtual machines. In short, the machine on which your Virtual Box
+    is installed.</para>
+  <para><emphasis role="bold">Guest Operating System
+      (Guest):</emphasis></para>
+  <para>    ‘Guest OS’ or ‘Guest’ is commonly referred to the
+    Operating System installed on your Virtual Box Virtual Machine and
+    is an Virtual Instance independent of the host OS.</para>
+  <para><emphasis role="bold">Node :</emphasis></para>
+  <para>Node in this context is referring specifically to Servers.
+    Each OpenStack server is a node.</para>
+  <para><emphasis role="bold">Control Node:</emphasis></para>
+  <para>    Control Node hosts the Database, Keystone (Middleware) and
+    the servers for the scope of the current OpenStack deployment. It
+    is kind of like the ‘brains behind OpenStack’ and drives the
+    services like authentication, database etc.</para>
+  <para><emphasis role="bold">Compute Node:</emphasis></para>
+  <para>    Compute Node has the required Hypervisor (Qemu/KVM), and
+    is your Virtual Machine Host.</para>
+  <para><emphasis role="bold">Network Node:</emphasis></para>
+  <para>    Network Node provides Network as a Service and is
+    responsible for providing virtual networks for OpenStack.</para>
+  <para><guilabel>Using OpenSSH</guilabel></para>
+  <itemizedlist>
+    <listitem>
+      <para>Once you are done with setting up of network interfaces
+        file, you may switch over to SSH session by remote login into
+        the required server node (Control, Network, Compute) by using
+        OpenSSH Client.</para>
+    </listitem>
+    <listitem>
+      <para>Open Terminal on your Host machine, and type in the
+        following command</para>
+    </listitem>
+  </itemizedlist>
+ <programlisting>$ssh-keygen -t rsa</programlisting>
+  <itemizedlist>
+    <listitem>
+      <para>You should see similar output  :</para>
+      <programlisting>Generating public/private rsa key pair.
+Enter file in which to save the key (/u/kim/.ssh/id_rsa): [RETURN]
+Enter passphrase (empty for no passphrase): &lt;can be left empty>
+Enter same passphrase again: &lt;can be left empty>
+Your identification has been saved in /home/user/.ssh/id_rsa.
+Your public key has been saved in /home/user/.ssh/id_rsa.pub.
+The key fingerprint is:  
+b7:18:ad:3b:0b:50:5c:e1:da:2d:6f:5b:65:82:94:c5 xyz@example</programlisting>
+    </listitem>
+  </itemizedlist>
+</chapter>

doc/training-guide/lab000-openstack-training-labs.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+  xml:id="lab000-openstack-training-labs">
+  <title>OpenStack Training Labs</title>
+  <xi:include href="lab000-important-terms.xml"/>
+  <xi:include href="lab000-virtualbox-basics.xml"/>
+  <xi:include href="lab001-control-node.xml"/>
+  <xi:include href="lab001-compute-node.xml"/>
+  <xi:include href="lab002-network-node.xml"/>
+  <xi:include href="lab003-openstack-production.xml"/>
+</book>

doc/training-guide/lab000-virtualbox-basics.xml

@@ -0,0 +1,652 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="5.0"
+  xml:id="lab000-virtualbox-basics">
+  <title>VirtualBox Basics</title>
+  <para><guilabel>Getting Started</guilabel></para>
+  <para>The following are the conventional methods of deploying
+    OpenStack on Virtual Box for the sake of a test/sandbox or just to
+    try out OpenStack on commodity hardware.</para>
+    <para>1. DevStack</para>
+    <para>2. Vagrant</para>
+    <para>But DevStack and Vagrant bring in some level of automated
+      deployment as running the scripts will get your VirtualBox
+      Instance configured as the required OpenStack deployment. We
+      will be manually deploying OpenStack on VirtualBox Instance to
+      get better view of how OpenStack works.</para>
+    <para><guilabel>Prerequisite:</guilabel></para>
+    <para>Well, its a daunting task to just cover all of OpenStack’s
+      concepts let alone Virtualization and Networking. So some basic
+      idea/knowledge on Virtualization, Networking and Linux is
+      required. Even though I will try to keep the level as low as
+      possible for making it easy for Linux Newbies as well as
+      experts.</para>
+    <para>These Virtual Machines and Virtual Networks will be given
+      equal privilege as a physical machine on a physical
+      network.</para>
+    <para>Just for those who would want to do a deeper research or
+      study, for more information you may refer the following
+      links</para>
+    <para><emphasis role="bold">OpenStack:</emphasis>OpenStack
+    Official Documentation (docs.openstack.org)</para>
+    <para><emphasis role="bold">Networking:</emphasis>Computer
+    Networks (5th Edition) by Andrew S. Tanenbaum </para>
+    <para><emphasis role="bold">VirtualBox:</emphasis>Virtual Box
+    Manual (http://www.virtualbox.org/manual/UserManual.html)</para>
+    <para><emphasis role="bold">Requirements :</emphasis></para>
+    <para>Operating Systems - I recommend Ubuntu Server 12.04 LTS,
+    Ubuntu Server 13.10 or Debian Wheezy</para>
+    <para><emphasis role="bold">Note :</emphasis>Ubuntu 12.10 is not
+    supporting OpenStack Grizzly Packages. Ubuntu team has decided not
+    to package Grizzly Packages for Ubuntu 12.10.</para>
+    <itemizedlist>
+      <listitem>
+        <para>Recommended Requirements.</para>
+      </listitem>
+    </itemizedlist>
+    <informaltable class="c25">
+      <tbody>
+        <tr>
+          <td rowspan="1" colspan="1">VT Enabled PC:</td>
+          <td rowspan="1" colspan="1">Intel ix or Amd QuadCore</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">4GB Ram:</td>
+          <td rowspan="1" colspan="1">DDR2/DDR3</td>
+        </tr>
+      </tbody>
+    </informaltable>
+    <itemizedlist>
+      <listitem>
+        <para>Minimum Requirements.</para>
+      </listitem>
+    </itemizedlist>
+    <informaltable class="c25">
+      <tbody>
+        <tr>
+          <td rowspan="1" colspan="1">Non-VT PC's:</td>
+          <td rowspan="1" colspan="1">Intel Core 2 Duo or Amd Dual
+            Core</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">2GB Ram:</td>
+          <td rowspan="1" colspan="1">DDR2/DDR3</td>
+        </tr>
+      </tbody>
+    </informaltable>
+    <para>If you don't know whether your processor is VT enabled, you
+      could check it by installing cpu checker</para>
+    <informaltable class="c25">
+      <tbody>
+        <tr>
+          <td rowspan="1" colspan="1">$sudo apt-get install
+            cpu-checker$sudo kvm-ok</td>
+        </tr>
+      </tbody>
+    </informaltable>
+    <para>If your device does not support VT it will show</para>
+    <para>INFO:Your CPU does not support KVM extensions</para>
+    <para>KVM acceleration can NOT be used</para>
+    <para>You will still be able to use Virtual Box but the instances
+      will be very slow.</para>
+    <para>There are many ways to configure your OpenStack Setup, we
+    will be deploying OpenStack Multi Node using OVS as the Network
+    Plugin and QEMU/ KVM as the hypervisor.</para>
+  <para><emphasis role="bold">Host Only Connections:</emphasis></para>
+    <itemizedlist>
+      <listitem>
+        <para>Host only connections provide an Internal network
+          between your host and the Virtual Machine instances up and
+          running on your host machine.This network is not traceable
+          by other networks.</para>
+      </listitem>
+      <listitem>
+        <para>You may even use Bridged connection if you have a
+          router/switch. I am assuming the worst case (one IP without
+          any router), so that it is simple to get the required
+          networks running without the hassle of IP tables.</para>
+      </listitem>
+      <listitem>
+        <para>The following are the host only connections that you
+          will be setting up later on :</para>
+      </listitem>
+    </itemizedlist>
+    <orderedlist>
+      <listitem>
+        <para>vboxnet0 - OpenStack Management Network - Host static IP
+          10.10.10.1</para>
+      </listitem>
+      <listitem>
+        <para>vboxnet1 - VM Conf.Network - Host Static IP
+          10.20.20.1</para>
+      </listitem>
+      <listitem>
+        <para>vboxnet2 - VM External Network Access (Host
+        Machine)</para>
+      <para><emphasis role="bold">Network Diagram :</emphasis></para>
+      </listitem>
+    </orderedlist>
+  <figure>
+    <title>Network Diagram</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image03.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para>Vboxnet0, Vboxnet1, Vboxnet2 - are virtual networks setup up
+      by virtual box with your host machine. This is the way your host
+      can communicate with the virtual machines. These networks are in
+      turn used by virtual box VM’s for OpenStack networks, so that
+      OpenStack’s services can communicate with each other.</para>
+  <para><guilabel>Setup Your VM Environment</guilabel></para>
+  <para>Before you can start configuring your Environment you need to
+    download some of the following stuff:</para>
+  
+  <orderedlist>
+    <listitem>
+      <para><link xlink:href="https://www.virtualbox.org/wiki/Downloads">
+        Oracle Virtual Box</link></para>
+    </listitem>
+   </orderedlist>
+   <para>Note:You cannot set up a amd64 VM on a x86 machine.</para>
+   <orderedlist>
+    <listitem>
+      <para><link xlink:href="http://www.ubuntu.com/download/server">
+        Ubuntu 12.04 Server or Ubuntu 13.04 Server</link></para>
+     </listitem>
+   </orderedlist>
+   <para>Note:You need a x86 image for VM's if kvm-ok fails, even
+      though you are on amd64 machine.</para>
+   <para>Note: Even Though I'm using Ubuntu as Host, the same is
+      applicable to Windows, Mac and other Linux Hosts.</para>
+   <itemizedlist>
+      <listitem>
+        <para>If you have i5 or i7 2nd gen processor you can have VT
+        technology inside VM's provided by VmWare. This means that
+        your OpenStack nodes(Which are in turn VM's) will give
+        positive result on KVM-OK. (I call it - Nesting of type-2
+        Hypervisors). Rest of the configurations remain same except
+        for the UI and few other trivial differences.</para>
+      </listitem>
+    </itemizedlist>
+  <para><guilabel>Configure Virtual Networks</guilabel></para>
+    <itemizedlist>
+      <listitem>
+        <para>This section of the guide will help you setup your
+          networks for your Virtual Machine.</para>
+      </listitem>
+      <listitem>
+        <para>Launch Virtual Box</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+        <para>Click on <emphasis role="bold"
+          >File>Preferences</emphasis> present on the menu bar of
+        Virtual Box.</para>
+      </listitem>
+      <listitem>
+        <para>Select the <emphasis role="bold">Network
+        tab</emphasis>.</para>
+      </listitem>
+      <listitem>
+        <para>On the right side you will see an option to add
+        Host-Only networks.</para>
+      </listitem>
+    </itemizedlist>
+  <figure>
+    <title>Create Host Only Networks</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image13.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <itemizedlist>
+      <listitem>
+        <para>Create three Host-Only Network Connections. As shown
+          above.</para>
+      </listitem>
+      <listitem>
+        <para>Edit the Host-Only Connections to have the following
+          settings.</para>
+      </listitem>
+    </itemizedlist>
+    <para><emphasis role="bold">Vboxnet0</emphasis></para>
+    
+    
+    <informaltable class="c25">
+      <tbody>
+        <tr>
+          <th rowspan="1" colspan="1">Option</th>
+          <th rowspan="1" colspan="1">Value</th>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">IPv4 Address:</td>
+          <td rowspan="1" colspan="1">10.10.10.1</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">IPv4 Network Mask:</td>
+          <td rowspan="1" colspan="1">255.255.255.0</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">IPv6 Address:</td>
+          <td rowspan="1" colspan="1">Can be Left Blank</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">IPv6 Network Mask Length :</td>
+          <td rowspan="1" colspan="1">Can be Left Blank</td>
+        </tr>
+      </tbody>
+    </informaltable>
+  <figure>
+    <title>Vboxnet0</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image19.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para><emphasis role="bold">Vboxnet1</emphasis></para>
+    
+    
+    <informaltable class="c25">
+      <tbody>
+        <tr>
+          <th rowspan="1" colspan="1">Option</th>
+          <th rowspan="1" colspan="1">Value</th>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">IPv4 Address:</td>
+          <td rowspan="1" colspan="1">10.20.20.1</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">IPv4 Network Mask:</td>
+          <td rowspan="1" colspan="1">255.255.255.0</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">IPv6 Address:</td>
+          <td rowspan="1" colspan="1">Can be Left Blank</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">IPv6 Network Mask Length :</td>
+          <td rowspan="1" colspan="1">Can be Left Blank</td>
+        </tr>
+      </tbody>
+    </informaltable>
+  <figure>
+    <title>Vboxnet1</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image16.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para><emphasis role="bold">Vboxnet2</emphasis></para>
+    
+    
+    <informaltable class="c25">
+      <tbody>
+        <tr>
+          <th rowspan="1" colspan="1">Option</th>
+          <th rowspan="1" colspan="1">Value</th>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">IPv4 Address:</td>
+          <td rowspan="1" colspan="1">192.168.100.1</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">IPv4 Network Mask:</td>
+          <td rowspan="1" colspan="1">255.255.255.0</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">IPv6 Address:</td>
+          <td rowspan="1" colspan="1">Can be Left Blank</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">IPv6 Network Mask Length :</td>
+          <td rowspan="1" colspan="1">Can be Left Blank</td>
+        </tr>
+      </tbody>
+    </informaltable>
+  <figure>
+    <title>Image: Vboxnet2</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image08.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+  <para><guilabel>Install SSH and FTP</guilabel></para>
+    <itemizedlist>
+      <listitem>
+        <para>You may benefit by installing SSH and FTP so that you
+          could use your remote shell to login into the machine and
+          use your terminal which is more convenient that using the
+          Virtual Machines tty through the Virtual Box's UI. You get a
+          few added comforts like copy - paste commands into the
+          remote terminal which is not possible directly on VM.</para>
+      </listitem>
+      <listitem>
+        <para>FTP is for transferring files to and fro ... you can
+          also use SFTP or install FTPD on both HOST and VM's.</para>
+      </listitem>
+      <listitem>
+        <para>Installation of SSH and FTP with its configuration is
+          out of scope of this GUIDE and I may put it up but it
+          depends upon my free time. If someone wants to contribute to
+          this - please do so.</para>
+      </listitem>
+    </itemizedlist>
+    <para><emphasis role="bold">Note:</emphasis>Please set up the
+    Networks from inside the VM before trying to SSH and FTP into the
+    machines. I would suggest setting it up at once just after the
+    installation of the Server on VM's is over.</para>
+    <para><guilabel>Install Your VM's Instances</guilabel></para>
+    <itemizedlist>
+      <listitem>
+        <para>During Installation of The Operating Systems you will be
+          asked for Custom Software to Install , if you are confused
+          or not sure about this, just skip this step by pressing
+          Enter Key without selecting any of the given Options.</para>
+      </listitem>
+    </itemizedlist>
+    <para><emphasis role="bold">Warning</emphasis> - Please do not
+    install any of the other packages except for which are mentioned
+    below unless you know what you are doing. There is a good chance
+    that you may end up getting unwanted errors, package conflicts ...
+    due to the same.</para>
+    <para><guilabel>Control Node:</guilabel></para>
+    <para>Create a new virtual machine. Select Ubuntu Server</para>
+  <figure>
+    <title>Create New Virtual Machine</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image11.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para>Select appropriate RAM, minimum 512 MB of RAM for Control
+      Node. Rest all can be default settings. The hard disk size can
+      be 8GB as default.</para>
+    <para>Configure the networks</para>
+    <para>(Ignore the IP Address for now, you will set it up from
+      inside the VM)</para>
+    
+    
+    <informaltable class="c25">
+      <tbody>
+        <tr>
+          <th rowspan="1" colspan="1">Network Adapter</th>
+          <th rowspan="1" colspan="1">Host-Only Adapter Name</th>
+          <th rowspan="1" colspan="1">IP Address</th>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">eth0</td>
+          <td rowspan="1" colspan="1">Vboxnet0</td>
+          <td rowspan="1" colspan="1">10.10.10.51</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">eth1</td>
+          <td rowspan="1" colspan="1">Vboxnet2</td>
+          <td rowspan="1" colspan="1">10.20.20.51</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">eth2</td>
+          <td rowspan="1" colspan="1">NAT</td>
+          <td rowspan="1" colspan="1">DHCP</td>
+        </tr>
+      </tbody>
+    </informaltable>
+    <para><emphasis role="bold">Adapter 1 (Vboxnet0)</emphasis></para>
+  <figure>
+    <title>Adapter1 - Vboxnet0</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image07.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para><emphasis role="bold">Adapter 2 (Vboxnet2)</emphasis></para>
+  <figure>
+    <title>Adapter2 - Vboxnet2</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image18.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para><emphasis role="bold">Adapter 3 (NAT)</emphasis></para>
+  <figure>
+    <title>Adapter3 - NAT</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image14.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para>Now Install Ubuntu Server 12.04 or 13.04 on this
+      machine.</para>
+    <para><emphasis role="bold">Note :</emphasis>Install SSH server
+    when asked for Custom Software to Install. Rest of the packages
+    are not required and may come in the way of OpenStack packages -
+    like DNS servers etc. (not necessary). Unless you know what you
+    are doing.</para>
+    <para><guilabel>Network Node:</guilabel></para>
+    <para>Create a new Virtual Machine,</para>
+    <para>Minimum RAM is 512MB. Rest all can be left default. Minimum
+    HDD space 8GB.</para>
+  <figure>
+    <title>Create New Virtual Machine</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image12.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para>Configure the networks</para>
+    <para>(Ignore the IP Address for now, you will set it up from
+      inside the VM)</para>
+    
+    
+    <informaltable class="c25">
+      <tbody>
+        <tr>
+          <th rowspan="1" colspan="1">Network Adapter</th>
+          <th rowspan="1" colspan="1">Host-Only Adapter Name</th>
+          <th rowspan="1" colspan="1">IP Address</th>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">eth0</td>
+          <td rowspan="1" colspan="1">Vboxnet0</td>
+          <td rowspan="1" colspan="1">10.10.10.52</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">eth1</td>
+          <td rowspan="1" colspan="1">Vboxnet1</td>
+          <td rowspan="1" colspan="1">10.20.20.52</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">eth2</td>
+          <td rowspan="1" colspan="1">Vboxnet2</td>
+          <td rowspan="1" colspan="1">192.168.100.51</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">eth3</td>
+          <td rowspan="1" colspan="1">NAT</td>
+          <td rowspan="1" colspan="1">DHCP</td>
+        </tr>
+      </tbody>
+    </informaltable>
+    <para><emphasis role="bold">Adapter 1 (Vboxnet0)</emphasis></para>
+  <figure>
+    <title>Adapter 1 - Vboxnet0</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image05.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para><emphasis role="bold">Adapter 2 (Vboxnet1)</emphasis></para>
+  <figure>
+    <title>Adapter2 - Vboxnet1</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image17.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para><emphasis role="bold">Adapter 3 (Vboxnet2)</emphasis></para>
+  <figure>
+    <title>Adapter3 - Vboxnet2</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image02.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para><emphasis role="bold">Adapter 4 (NAT)</emphasis></para>
+  <figure>
+    <title>Adapter4 - NAT</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image00.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para>Now Install Ubuntu Server 12.04 or 13.04 on this
+      machine.</para>
+    <para><emphasis role="bold">Note :</emphasis>Install SSH server
+    when asked for Custom Software to Install. Rest of the packages
+    are not required and may come in the way of OpenStack packages -
+    like DNS servers etc. (not necessary). Unless you know what you
+    are doing.</para>
+    <para><guilabel>Compute Node:</guilabel></para>
+    <para>Create a new virtual machine, give it atleast 1,000 MB RAM.
+    Rest all can be left as defaults. Give atleast 8GB HDD.</para>
+  <figure>
+    <title>Create New Virtual Machine</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image04.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para>Configure the networks</para>
+    <para>(Ignore the IP Address for now, you will set it up from
+      inside the VM)</para>
+    
+    
+    <informaltable class="c25">
+      <tbody>
+        <tr>
+          <th rowspan="1" colspan="1">Network Adapter</th>
+          <th rowspan="1" colspan="1">Host-Only Adapter Name</th>
+          <th rowspan="1" colspan="1">IP Address</th>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">eth0</td>
+          <td rowspan="1" colspan="1">Vboxnet0</td>
+          <td rowspan="1" colspan="1">10.10.10.53</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">eth1</td>
+          <td rowspan="1" colspan="1">Vboxnet1</td>
+          <td rowspan="1" colspan="1">10.20.20.53</td>
+        </tr>
+        <tr>
+          <td rowspan="1" colspan="1">eth2</td>
+          <td rowspan="1" colspan="1">NAT</td>
+          <td rowspan="1" colspan="1">DHCP</td>
+        </tr>
+      </tbody>
+    </informaltable>
+    <para><emphasis role="bold">Adapter 1 (Vboxnet0)</emphasis></para>
+  <figure>
+    <title>Adapter1 - Vboxnet0</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image15.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para><emphasis role="bold">Adapter 2 (Vboxnet1)</emphasis></para>
+  <figure>
+    <title>Adapter2 - Vboxnet1</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image10.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para><emphasis role="bold">Adapter 3 (NAT)</emphasis></para>
+  <figure>
+    <title>Adapter3 - NAT</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image01.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para>Now Install Ubuntu Server 12.04 or 13.04 on this
+      machine.</para>
+    <para><emphasis role="bold">Note :</emphasis>Install SSH server
+    when asked for Custom Software to Install. Rest of the packages
+    are not required and may come in the way of OpenStack packages -
+    like DNS servers etc. (not necessary). Unless you know what you
+    are doing.</para>
+  <para><guilabel>Warnings/Advice :</guilabel></para>
+      <itemizedlist>
+        <listitem>
+          <para>Well there are a few warnings that I must give you out
+            of experience due to common habits that most people may
+            have :</para>
+        </listitem>
+      </itemizedlist>
+      <para>Sometimes shutting down your Virtual Machine may lead to
+        malfunctioning of OpenStack Services. Try not to direct
+        shutdown your 3. In case your VM's don't get internet.</para>
+      <itemizedlist>
+        <listitem>
+          <para>From your VM Instance, Use ping command to see whether
+            Internet is on.</para>
+        </listitem>
+      </itemizedlist>
+      <programlisting>$ping www.google.com</programlisting>
+      <itemizedlist>
+        <listitem>
+          <para>If its not connected, restart networking
+            service-</para>
+        </listitem>
+      </itemizedlist>
+      <programlisting>$sudo service networking restart
+$ping www.google.com</programlisting>
+      <itemizedlist>
+        <listitem>
+          <para>If this doesn't work, you need to check your network
+            settings from Virtual Box, you may have left something or
+            misconfigured it.</para>
+        </listitem>
+        <listitem>
+          <para>This should reconnect your network about 99% of the
+            times. If you are really unlucky you must be having some
+            other problems or your Internet connection itself is not
+            functioning.</para>
+        </listitem>
+        <listitem>
+          <para>Note :There are known bugs with the ping under NAT.
+            Although the latest versions of Virtual Box have better
+            performance, sometimes ping may not work even if your
+            Network is connected to internet.</para>
+        </listitem>
+      </itemizedlist>
+      <para>Congrats, you are ready with the infrastructure for
+        deploying OpenStack. Just make sure that you have installed
+        Ubuntu Server on the above setup Virtual Box Instances. In the
+        next section we will go through deploying OpenStack using the
+        above created Virtual Box instances.</para>
+    
+</chapter>

doc/training-guide/lab001-compute-node.xml

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="5.0"
+  xml:id="lab001-compute-node">
+  <title>Compute Node</title>
+  <orderedlist>
+    <listitem>
+      <para><emphasis role="bold">Network Diagram :</emphasis></para>
+    </listitem>
+  </orderedlist>
+  <figure>
+    <title>Network Diagram</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image03.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+  <para><emphasis role="bold">Vboxnet0</emphasis>, <emphasis
+      role="bold">Vboxnet1</emphasis>, <emphasis role="bold"
+      >Vboxnet2</emphasis> - are virtual networks setup up by virtual
+    box with your host machine. This is the way your host can
+    communicate with the virtual machines. These networks are in turn
+    used by virtual box VM’s for OpenStack networks, so that
+    OpenStack’s services can communicate with each other.</para>
+  <para><guilabel>Compute Node</guilabel></para>
+  <para> Start your Controller Node the one you setup in previous
+    section.</para>
+  <para><emphasis role="bold">Preparing Ubuntu
+    13.04/12.04</emphasis></para>
+  <itemizedlist>
+    <listitem>
+      <para>After you install Ubuntu Server, go in sudo mode</para>
+      <para>
+        <programlisting>$sudo su</programlisting>
+      </para>
+    </listitem>
+    <listitem>
+      <para>Add Grizzly repositories:</para>
+      <para><programlisting>#apt-get install ubuntu-cloud-keyring python-software-properties software-properties-common python-keyring 
+# echo deb http://ubuntu-cloud.archive.canonical.com/ubuntu precise-updates/grizzly main >> /etc/apt/sources.list.d/grizzly.list </programlisting></para>
+    </listitem>
+    <listitem>
+      <para> Update your system: </para>
+      <para><programlisting>#apt-get update
+#apt-get upgrade
+#apt-get dist-upgrade</programlisting></para>
+    </listitem>
+  </itemizedlist>
+  <para>More Content To be Added soon.</para>
+</chapter>

doc/training-guide/lab001-control-node.xml

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="5.0"
+  xml:id="lab001-control-node.xml">
+  <title>Control Node</title>
+  <para><emphasis role="bold">Network Diagram :</emphasis></para>
+  <figure>
+    <title>Network Diagram</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image03.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+  <para><emphasis role="bold">Vboxnet0</emphasis>, <emphasis
+      role="bold">Vboxnet1</emphasis>, <emphasis role="bold"
+      >Vboxnet2</emphasis> - are virtual networks setup up by virtual
+    box with your host machine. This is the way your host can
+    communicate with the virtual machines. These networks are in turn
+    used by virtual box VM’s for OpenStack networks, so that
+    OpenStack’s services can communicate with each other.</para>
+  <para><guilabel>Controller Node</guilabel></para>
+  <para> Start your Controller Node the one you setup in previous
+    section.</para>
+  <para><emphasis role="bold">Preparing Ubuntu
+    13.04/12.04</emphasis></para>
+    <itemizedlist>
+      <listitem>
+        <para>After you install Ubuntu Server, go in sudo mode</para>
+        <para>
+          <programlisting>$sudo su</programlisting>
+        </para>
+      </listitem>
+      <listitem>
+        <para>Add Grizzly repositories:</para>
+        <para><programlisting>#apt-get install ubuntu-cloud-keyring python-software-properties software-properties-common python-keyring 
+# echo deb http://ubuntu-cloud.archive.canonical.com/ubuntu precise-updates/grizzly main >> /etc/apt/sources.list.d/grizzly.list </programlisting></para>
+      </listitem>
+      <listitem>
+        <para> Update your system: </para>
+        <para><programlisting>#apt-get update
+#apt-get upgrade
+#apt-get dist-upgrade</programlisting></para>
+      </listitem>
+    </itemizedlist>
+  <para>More Content To be Added soon.</para>
+</chapter>

doc/training-guide/lab002-network-node.xml

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="5.0"
+  xml:id="lab002-network-node.xml">
+  <title>Network Node</title>
+  <orderedlist>
+    <listitem>
+      <para><emphasis role="bold">Network Diagram :</emphasis></para>
+    </listitem>
+  </orderedlist>
+  <figure>
+    <title>Network Diagram</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/lab000-virtual-box/image03.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+  <para><emphasis role="bold">Vboxnet0</emphasis>, <emphasis
+      role="bold">Vboxnet1</emphasis>, <emphasis role="bold"
+      >Vboxnet2</emphasis> - are virtual networks setup up by virtual
+    box with your host machine. This is the way your host can
+    communicate with the virtual machines. These networks are in turn
+    used by virtual box VM’s for OpenStack networks, so that
+    OpenStack’s services can communicate with each other.</para>
+  <para><guilabel>Network Node</guilabel></para>
+  <para> Start your Controller Node the one you setup in previous
+    section.</para>
+  <para><emphasis role="bold">Preparing Ubuntu
+    13.04/12.04</emphasis></para>
+  <itemizedlist>
+    <listitem>
+      <para>After you install Ubuntu Server, go in sudo mode</para>
+      <para>
+        <programlisting>$sudo su</programlisting>
+      </para>
+    </listitem>
+    <listitem>
+      <para>Add Grizzly repositories:</para>
+      <para><programlisting>#apt-get install ubuntu-cloud-keyring python-software-properties software-properties-common python-keyring 
+# echo deb http://ubuntu-cloud.archive.canonical.com/ubuntu precise-updates/grizzly main >> /etc/apt/sources.list.d/grizzly.list </programlisting></para>
+    </listitem>
+    <listitem>
+      <para> Update your system: </para>
+      <para><programlisting>#apt-get update
+#apt-get upgrade
+#apt-get dist-upgrade</programlisting></para>
+    </listitem>
+  </itemizedlist>
+  <para>More Content To be Added soon.</para>
+</chapter>

doc/training-guide/lab003-openstack-production.xml

@@ -3,7 +3,7 @@
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xmlns:xlink="http://www.w3.org/1999/xlink"
  version="5.0"
-  xml:id="module001-ch011-block-storage">
+  xml:id="lab003-openstack-production.xml">
-  <title>OpenStack Block Storage</title>
+  <title>OpenStack In Production</title>
-  <para>To be Added</para>
+  <para>More Content To be Added.</para>
-</chapter>
+</chapter>

doc/training-guide/module001-ch001-intro-text.xml

@@ -8,7 +8,7 @@
   <para>Cloud Computing’s hype has certainly attracted IT Giants and
     the entire Open Source community's attention, amidst all this
     chaos of disrupting the software world and the way we saw and
-    thought about it, we need to enlighten ourselves with this massive
+    thought about it. We need to enlighten ourselves with this massive
     change as time again, entire Open Source community has seen the
     rise of yet another project which is called as OpenStack. It is
     believed that OpenStack will have a similar impact on the future
@@ -23,7 +23,7 @@
     locked in at high level scientific and corporate places which are
     usually tough to get in touch with, further innovating the pace of
     education and expanding its possibilities. Being open in nature,
-    these resources are free to use and modify, talor them at no cost,
+    these resources are free to use and modify, tailor them at no cost,
     shape them as per your requirements and let the cloud do all the
     hard work. </para>
   <para>In data centers today, many computers suffer under-utilization

doc/training-guide/module001-ch003-core-projects.xml

@@ -1,9 +1,654 @@
 <?xml version="1.0" encoding="utf-8"?>
-<chapter xmlns="http://docbook.org/ns/docbook"
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="module001-ch003-core-projects">
-  xmlns:xi="http://www.w3.org/2001/XInclude"
+  <title>OpenStack Projects, History and Releases Overview</title>
-  xmlns:xlink="http://www.w3.org/1999/xlink"
+  <para><guilabel>Project history and releases overview.</guilabel></para>
- version="5.0"
+  <para>OpenStack is a cloud computing project to provide an
-  xml:id="module001-ch003-core-projects">
+    infrastructure as a service (IaaS). It is free open source
-  <title>Core Projects</title>
+    software released under the terms of the Apache License. The
-  <para>More Content To be Added ...</para>
+    project is managed by the OpenStack Foundation, a non-profit
-</chapter>
+    corporate entity established in September 2012 to promote
+    OpenStack software and its community.</para>
+  <para>More than 200 companies joined the project among which are
+    AMD, Brocade Communications Systems, Canonical, Cisco, Dell, EMC,
+    Ericsson, Groupe Bull, HP, IBM, Inktank, Intel, NEC, Rackspace
+    Hosting, Red Hat, SUSE Linux, VMware, and Yahoo!</para>
+  <para>The technology consists of a series of interrelated projects
+    that control pools of processing, storage, and networking
+    resources throughout a datacenter, all managed through a dashboard
+    that gives administrators control while empowering its users to
+    provision resources through a web interface.</para>
+  <para>The OpenStack community collaborates around a six-month,
+    time-based release cycle with frequent development milestones.
+    During the planning phase of each release, the community gathers
+    for the OpenStack Design Summit to facilitate developer working
+    sessions and assemble plans.</para>
+  <para>In July 2010 Rackspace Hosting and NASA jointly launched an
+    open-source cloud-software initiative known as OpenStack. The
+    OpenStack project intended to help organizations which offer
+    cloud-computing services running on standard hardware. The
+    community’s first official release, code-named Austin, appeared
+    four months later, with plans to release regular updates of the
+    software every few months. The early code came from NASA’s Nebula
+    platform as well as from Rackspace’s Cloud Files platform. In July
+    2011 developers of the Ubuntu Linux distribution decided to adopt
+    OpenStack.</para>
+  <para><emphasis role="bold">Openstack Releases</emphasis></para>
+  <informaltable class="c20">
+    <tbody>
+      <tr>
+        <td rowspan="1" colspan="1">Release Name</td>
+        <td rowspan="1" colspan="1">Release Date</td>
+        <td rowspan="1" colspan="1">Included Components</td>
+      </tr>
+      <tr>
+        <td rowspan="1" colspan="1">Austin</td>
+        <td rowspan="1" colspan="1">21 October 2010</td>
+        <td rowspan="1" colspan="1">Nova, Swift</td>
+      </tr>
+      <tr>
+        <td rowspan="1" colspan="1">Bexar</td>
+        <td rowspan="1" colspan="1">3 February 2011</td>
+        <td rowspan="1" colspan="1">Nova, Glance, Swift</td>
+      </tr>
+      <tr>
+        <td rowspan="1" colspan="1">Cactus</td>
+        <td rowspan="1" colspan="1">15 April 2011</td>
+        <td rowspan="1" colspan="1">Nova, Glance, Swift</td>
+      </tr>
+      <tr>
+        <td rowspan="1" colspan="1">Diablo</td>
+        <td rowspan="1" colspan="1">22 September 2011</td>
+        <td rowspan="1" colspan="1">Nova, Glance, Swift</td>
+      </tr>
+      <tr>
+        <td rowspan="1" colspan="1">Essex</td>
+        <td rowspan="1" colspan="1">5 April 2012</td>
+        <td rowspan="1" colspan="1">Nova, Glance, Swift,
+          Horizon, Keystone</td>
+      </tr>
+      <tr>
+        <td rowspan="1" colspan="1">Folsom</td>
+        <td rowspan="1" colspan="1">27 September 2012</td>
+        <td rowspan="1" colspan="1">Nova, Glance, Swift,
+          Horizon, Keystone, Quantum, Cinder</td>
+      </tr>
+      <tr>
+        <td rowspan="1" colspan="1">Grizzly</td>
+        <td rowspan="1" colspan="1">4 April 2013</td>
+        <td rowspan="1" colspan="1">Nova, Glance, Swift,
+          Horizon, Keystone, Quantum, Cinder</td>
+      </tr>
+      <tr>
+        <td rowspan="1" colspan="1">Havana</td>
+        <td rowspan="1" colspan="1">17 October 2013</td>
+        <td rowspan="1" colspan="1">Nova, Glance, Swift,
+          Horizon, Keystone, Neutron, Cinder</td>
+      </tr>
+      <tr>
+        <td rowspan="1" colspan="1">IceHouse</td>
+        <td rowspan="1" colspan="1">April 2014</td>
+        <td rowspan="1" colspan="1">Nova, Glance, Swift,
+          Horizon, Keystone, Neutron, Cinder, (More to be
+          added)</td>
+      </tr>
+    </tbody>
+  </informaltable>
+  <para>Some OpenStack users include:</para>
+  <itemizedlist>
+    <listitem>
+      <para>PayPal / eBay</para>
+    </listitem>
+    <listitem>
+      <para>NASA</para>
+    </listitem>
+    <listitem>
+      <para>CERN</para>
+    </listitem>
+    <listitem>
+      <para>Yahoo!</para>
+    </listitem>
+    <listitem>
+      <para>Rackspace Cloud</para>
+    </listitem>
+    <listitem>
+      <para>HP Public Cloud</para>
+    </listitem>
+    <listitem>
+      <para>MercadoLibre.com</para>
+    </listitem>
+    <listitem>
+      <para>AT&amp;T</para>
+    </listitem>
+    <listitem>
+      <para>KT (formerly Korea Telecom)</para>
+    </listitem>
+    <listitem>
+      <para>Deutsche Telekom</para>
+    </listitem>
+    <listitem>
+      <para>Wikimedia Labs</para>
+    </listitem>
+    <listitem>
+      <para>Hostalia of Telef nica Group</para>
+    </listitem>
+    <listitem>
+      <para>SUSE Cloud solution</para>
+    </listitem>
+    <listitem>
+      <para>Red Hat OpenShift PaaS solution</para>
+    </listitem>
+    <listitem>
+      <para>Zadara Storage</para>
+    </listitem>
+    <listitem>
+      <para>Mint Services</para>
+    </listitem>
+    <listitem>
+      <para>GridCentric</para>
+    </listitem>
+  </itemizedlist>
+  <para>and many more such users of OpenStack make it a true open
+    standard innovating and driving the worlds biggest Open Cloud
+    Standards (more on User Stories here <link xlink:href="http://goo.gl/aF4lsL">http://goo.gl/aF4lsL</link>).</para>
+  <para><guilabel>Release Cycle</guilabel></para>
+  <figure>
+    <title>Community Heartbeat</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image05.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para>OpenStack is based on a coordinated 6-month release cycle
+      with frequent development milestones. You can find a link to the
+      current development release schedule here. The Release Cycle is
+      made of four major stages. Various OpenStack releases are named
+      as follows Various Companies Contributing to OpenStack</para>
+  <figure>
+    <title>Various Projects under OpenStack</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image16.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para>In a Nutshell, OpenStack...</para>
+    <itemizedlist>
+      <listitem>
+        <para>has had 64,396 commits made by 1,128 contributors</para>
+      </listitem>
+      <listitem>
+        <para>representing 908,491 lines of code</para>
+      </listitem>
+      <listitem>
+        <para>is mostly written in Python</para>
+      </listitem>
+      <listitem>
+        <para>with an average number of source code comments</para>
+      </listitem>
+      <listitem>
+        <para>has a codebase with a long source history</para>
+      </listitem>
+      <listitem>
+        <para>maintained by a very large development team</para>
+      </listitem>
+      <listitem>
+        <para>with increasing Y-O-Y commits</para>
+      </listitem>
+      <listitem>
+        <para>took an estimated 249 years of effort (COCOMO
+        model)</para>
+      </listitem>
+      <listitem>
+        <para>starting with its first commit in May, 2010. (I have
+        deliberatly not</para>
+      </listitem>
+      <listitem>
+        <para>included last commit date since this is an active
+          project with</para>
+      </listitem>
+      <listitem>
+        <para>people working on it from all round the world).</para>
+      </listitem>
+    </itemizedlist>
+  <figure>
+    <title>Programming Languages used to design OpenStack</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image06.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para>For more overview on OpenStack refer
+      http://www.openstack.org or http://goo.gl/4q7nVI, most of the
+      common questions and queries are covered here so as to address
+      the massive amount of questions that may arise out of
+      this.</para>
+  <para><guilabel>Core Projects Overview</guilabel></para>
+  <para>Let’s take a dive into some technical aspects of OpenStack,
+    its amazing scalability and flexibility are few of its awesome
+    features that make it a rock-solid cloud computing platform but
+    the OpenSource Nature of it and the fact that its Community
+    driven, it is explicitly meant to serve the OpenSource community
+    and its demands.</para>
+  <para>Being a cloud computing platform, OpenStack consists of many
+    core and incubated projects which as a whole makes it really good
+    as an IaaS cloud computing platform/Operating System. But the
+    following points are the main components of OpenStack that are
+    necessary to be present in the cloud to call it as OpenStack
+    Cloud.</para>
+  <para><guimenu>Components of OpenStack</guimenu></para>
+  <para>OpenStack has a modular architecture with various code names
+      for its components. OpenStack has several shared services that
+      span the three pillars of compute, storage and networking,
+      making it easier to implement and operate your cloud. These
+      services - including identity, image management and a web
+      interface - integrate the OpenStack components with each other
+      as well as external systems to provide a unified experience for
+      users as they interact with different cloud resources.</para>
+  <para><guisubmenu>Compute (Nova)</guisubmenu></para>
+      <para>The OpenStack cloud operating system enables enterprises
+        and service providers to offer on-demand computing resources,
+        by provisioning and managing large networks of virtual
+        machines. Compute resources are accessible via APIs for
+        developers building cloud applications and via web interfaces
+        for administrators and users. The compute architecture is
+        designed to scale horizontally on standard hardware, enabling
+        the cloud economics companies have come to expect.</para>
+  <figure>
+    <title>OpenStack Compute:Provision and manage large networks of
+      virtual machines</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image03.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+      <para>OpenStack Compute (Nova) is a cloud computing fabric
+        controller (the main part of an IaaS system). It is written in
+        Python and uses many external libraries such as Eventlet (for
+        concurrent programming), Kombu (for AMQP communication), and
+        SQLAlchemy (for database access). Nova's architecture is
+        designed to scale horizontally on standard hardware with no
+        proprietary hardware or software requirements and provide the
+        ability to integrate with legacy systems and third party
+        technologies. It is designed to manage and automate pools of
+        computer resources and can work with widely available
+        virtualization technologies, as well as bare metal and
+        high-performance computing (HPC) configurations. KVM and
+        XenServer are available choices for hypervisor technology,
+        together with Hyper-V and Linux container technology such as
+        LXC. In addition to different hypervisors, OpenStack runs on
+        ARM.</para>
+  <para><emphasis role="bold">Popular Use Cases:</emphasis></para>
+        <itemizedlist>
+          <listitem>
+            <para>Service providers offering an IaaS compute platform
+              or services higher up the stack</para>
+          </listitem>
+          <listitem>
+            <para>IT departments acting as cloud service providers for
+              business units and project teams</para>
+          </listitem>
+          <listitem>
+            <para>Processing big data with tools like Hadoop</para>
+          </listitem>
+          <listitem>
+            <para>Scaling compute up and down to meet demand for web
+              resources and applications</para>
+          </listitem>
+          <listitem>
+            <para>High-performance computing (HPC) environments
+              processing diverse and intensive workloads</para>
+          </listitem>
+        </itemizedlist>
+  <para><guisubmenu>Object Storage(Swift)</guisubmenu></para>
+      <para>In addition to traditional enterprise-class storage
+        technology, many organizations now have a variety of storage
+        needs with varying performance and price requirements.
+        OpenStack has support for both Object Storage and Block
+        Storage, with many deployment options for each depending on
+        the use case.</para>
+  <figure>
+    <title>OpenStack Storage: Object and Block storage for use with
+      servers and applications</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image17.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+      <para>OpenStack Object Storage (Swift) is a scalable redundant
+        storage system. Objects and files are written to multiple disk
+        drives spread throughout servers in the data center, with the
+        OpenStack software responsible for ensuring data replication
+        and integrity across the cluster. Storage clusters scale
+        horizontally simply by adding new servers. Should a server or
+        hard drive fail, OpenStack replicates its content from other
+        active nodes to new locations in the cluster. Because
+        OpenStack uses software logic to ensure data replication and
+        distribution across different devices, inexpensive commodity
+        hard drives and servers can be used.</para>
+      <para>Object Storage is ideal for cost effective, scale-out
+        storage. It provides a fully distributed, API-accessible
+        storage platform that can be integrated directly into
+        applications or used for backup, archiving and data retention.
+        Block Storage allows block devices to be exposed and connected
+        to compute instances for expanded storage, better performance
+        and integration with enterprise storage platforms, such as
+        NetApp, Nexenta and SolidFire.</para>
+      <para>A few details on OpenStack’s Object Storage</para>
+      <itemizedlist>
+        <listitem>
+          <para>OpenStack provides redundant, scalable object storage using
+                clusters of standardized servers capable of storing
+                petabytes of data</para>
+        </listitem>
+        <listitem>
+          <para>Object Storage is not a traditional file system, but rather a
+                distributed storage system for static data such as
+                virtual machine images, photo storage, email storage,
+                backups and archives. Having no central "brain" or
+                master point of control provides greater scalability,
+                redundancy and durability.</para>
+        </listitem>
+        <listitem>
+          <para>Objects and files are written to multiple disk drives spread
+                throughout servers in the data center, with the
+                OpenStack software responsible for ensuring data
+                replication and integrity across the cluster.</para>
+        </listitem>
+        <listitem>
+          <para>Storage clusters scale horizontally simply by adding new servers.
+                Should a server or hard drive fail, OpenStack
+                replicates its content from other active nodes to new
+                locations in the cluster. Because OpenStack uses
+                software logic to ensure data replication and
+                distribution across different devices, inexpensive
+                commodity hard drives and servers can be used in lieu
+                of more expensive equipment.</para>
+        </listitem>
+      </itemizedlist>
+  <para><guisubmenu>Block Storage(Cinder)</guisubmenu></para>
+      <para>OpenStack Block Storage (Cinder) provides persistent block
+        level storage devices for use with OpenStack compute
+        instances. The block storage system manages the creation,
+        attaching and detaching of the block devices to servers. Block
+        storage volumes are fully integrated into OpenStack Compute
+        and the Dashboard allowing for cloud users to manage their own
+        storage needs. In addition to local Linux server storage, it
+        can use storage platforms including Ceph, CloudByte, Coraid,
+        EMC (VMAX and VNX), GlusterFS, IBM Storage (Storwize family,
+        SAN Volume Controller, and XIV Storage System), Linux LIO,
+        NetApp, Nexenta, Scality, SolidFire and HP (Store Virtual and
+        StoreServ 3Par families). Block storage is appropriate for
+        performance sensitive scenarios such as database storage,
+        expandable file systems, or providing a server with access to
+        raw block level storage. Snapshot management provides powerful
+        functionality for backing up data stored on block storage
+        volumes. Snapshots can be restored or used to create a new
+        block storage volume.</para>
+      <para><emphasis role="bold">A few points on OpenStack Block
+      Storage:</emphasis></para>
+      <itemizedlist>
+        <listitem>
+          <para>OpenStack provides persistent block level storage
+            devices for use with OpenStack compute instances.</para>
+        </listitem>
+        <listitem>
+          <para>The block storage system manages the creation,
+            attaching and detaching of the block devices to servers.
+            Block storage volumes are fully integrated into OpenStack
+            Compute and the Dashboard allowing for cloud users to
+            manage their own storage needs.</para>
+        </listitem>
+        <listitem>
+          <para>In addition to using simple Linux server storage, it
+            has unified storage support for numerous storage platforms
+            including Ceph, NetApp, Nexenta, SolidFire, and
+            Zadara.</para>
+        </listitem>
+        <listitem>
+          <para>Block storage is appropriate for performance sensitive
+            scenarios such as database storage, expandable file
+            systems, or providing a server with access to raw block
+            level storage.</para>
+        </listitem>
+        <listitem>
+          <para>Snapshot management provides powerful functionality
+            for backing up data stored on block storage volumes.
+            Snapshots can be restored or used to create a new block
+            storage volume.</para>
+        </listitem>
+      </itemizedlist>
+  <para><guisubmenu>Networking(Neutron)</guisubmenu></para>
+      <para>Today's datacenter networks contain more devices than ever
+        before servers, network equipment, storage systems and
+        security appliances many of which are further divided into
+        virtual machines and virtual networks. The number of IP
+        addresses, routing configurations and security rules can
+        quickly grow into the millions. Traditional network management
+        techniques fall short of providing a truly scalable, automated
+        approach to managing these next-generation networks. At the
+        same time, users expect more control and flexibility with
+        quicker provisioning.</para>
+      <para>OpenStack Networking is a pluggable, scalable and
+        API-driven system for managing networks and IP addresses. Like
+        other aspects of the cloud operating system, it can be used by
+        administrators and users to increase the value of existing
+        datacenter assets. OpenStack Networking ensures the network
+        will not be the bottleneck or limiting factor in a cloud
+        deployment and gives users real self-service, even over their
+        network configurations.</para>
+  <figure>
+    <title>OpenStack Networking: Pluggable, scalable, API-driven
+      network and IP management</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image26.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+      <para>OpenStack Networking (Neutron, formerly Quantum]) is a
+        system for managing networks and IP addresses. Like other
+        aspects of the cloud operating system, it can be used by
+        administrators and users to increase the value of existing
+        data center assets. OpenStack Networking ensures the network
+        will not be the bottleneck or limiting factor in a cloud
+        deployment and gives users real self-service, even over their
+        network configurations.</para>
+      <para>OpenStack Neutron provides networking models for different
+        applications or user groups. Standard models include flat
+        networks or VLANs for separation of servers and traffic.
+        OpenStack Networking manages IP addresses, allowing for
+        dedicated static IPs or DHCP. Floating IPs allow traffic to be
+        dynamically re routed to any of your compute resources, which
+        allows you to redirect traffic during maintenance or in the
+        case of failure. Users can create their own networks, control
+        traffic and connect servers and devices to one or more
+        networks. Administrators can take advantage of
+        software-defined networking (SDN) technology like OpenFlow to
+        allow for high levels of multi-tenancy and massive scale.
+        OpenStack Networking has an extension framework allowing
+        additional network services, such as intrusion detection
+        systems (IDS), load balancing, firewalls and virtual private
+        networks (VPN) to be deployed and managed.</para>
+  <para>Networking Capabilities</para>
+        <itemizedlist>
+          <listitem>
+            <para>OpenStack provides flexible networking models to
+              suit the needs of different applications or user groups.
+              Standard models include flat networks or VLANs for
+              separation of servers and traffic.</para>
+          </listitem>
+          <listitem>
+            <para>OpenStack Networking manages IP addresses, allowing
+              for dedicated static IPs or DHCP. Floating IPs allow
+              traffic to be dynamically rerouted to any of your
+              compute resources, which allows you to redirect traffic
+              during maintenance or in the case of failure.</para>
+          </listitem>
+          <listitem>
+            <para>Users can create their own networks, control traffic
+              and connect servers and devices to one or more
+              networks.</para>
+          </listitem>
+          <listitem>
+            <para>The pluggable backend architecture lets users take
+              advantage of commodity gear or advanced networking
+              services from supported vendors.</para>
+          </listitem>
+          <listitem>
+            <para>Administrators can take advantage of
+              software-defined networking (SDN) technology like
+              OpenFlow to allow for high levels of multi-tenancy and
+              massive scale.</para>
+          </listitem>
+          <listitem>
+            <para>OpenStack Networking has an extension framework
+              allowing additional network services, such as intrusion
+              detection systems (IDS), load balancing, firewalls and
+              virtual private networks (VPN) to be deployed and
+              managed.</para>
+          </listitem>
+        </itemizedlist>
+  <para><guisubmenu>Dashboard(Horizon)</guisubmenu></para>
+      <para>OpenStack Dashboard (Horizon) provides administrators and
+        users a graphical interface to access, provision and automate
+        cloud-based resources. The design allows for third party
+        products and services, such as billing, monitoring and
+        additional management tools. The dashboard is also brandable
+        for service providers and other commercial vendors who want to
+        make use of it.</para>
+      <para>The dashboard is just one way to interact with OpenStack
+        resources. Developers can automate access or build tools to
+        manage their resources using the native OpenStack API or the
+        EC2 compatibility API.</para>
+  <para><guisubmenu>Identity Service(Keystone)</guisubmenu></para>
+      <para>OpenStack Identity (Keystone) provides a central directory
+        of users mapped to the OpenStack services they can access. It
+        acts as a common authentication system across the cloud
+        operating system and can integrate with existing backend
+        directory services like LDAP. It supports multiple forms of
+        authentication including standard username and password
+        credentials, token-based systems and AWS-style (i.e. Amazon
+        Web Services) logins. Additionally, the catalog provides a
+        queryable list of all of the services deployed in an OpenStack
+        cloud in a single registry. Users and third-party tools can
+        programmatically determine which resources they can
+        access.</para>
+      <para>Additionally, the catalog provides a queryable list of all
+        of the services deployed in an OpenStack cloud in a single
+        registry. Users and third-party tools can programmatically
+        determine which resources they can access.</para>
+      <para>As an administrator, OpenStack Identity enables you
+        to:</para>
+      <itemizedlist>
+        <listitem>
+          <para>Configure centralized policies across users and
+            systems</para>
+        </listitem>
+        <listitem>
+          <para>Create users and tenants and define permissions for
+            compute, storage and networking resources using role-based
+            access control (RBAC) features</para>
+        </listitem>
+        <listitem>
+          <para>Integrate with an existing directory like LDAP,
+            allowing for a single source of identity authentication
+            across the enterprise.</para>
+        </listitem>
+        <listitem>
+          <para>As a user, OpenStack Identity enables you to:</para>
+        </listitem>
+      </itemizedlist>
+      <itemizedlist>
+        <listitem>
+          <para>Get a list of the services that you can access.</para>
+        </listitem>
+        <listitem>
+          <para>Make API requests</para>
+        </listitem>
+        <listitem>
+          <para>Log into the web dashboard to create resources owned
+            by your account</para>
+        </listitem>
+      </itemizedlist>
+  <para><guisubmenu>Image Service(Glance)</guisubmenu></para>
+      <para>OpenStack Image Service (Glance) provides discovery,
+        registration and delivery services for disk and server images.
+        Stored images can be used as a template. It can also be used
+        to store and catalog an unlimited number of backups. The Image
+        Service can store disk and server images in a variety of
+        back-ends, including OpenStack Object Storage. The Image
+        Service API provides a standard REST interface for querying
+        information about disk images and lets clients stream the
+        images to new servers.</para>
+      <para>The Image Service can store disk and server images in a
+        variety of back-ends, including OpenStack Object Storage.  The
+        Image Service API provides a standard REST interface for
+        querying information about disk images and lets clients stream
+        the images to new servers.</para>
+      <para>Capabilities of the Image Service include:</para>
+      <itemizedlist>
+        <listitem>
+          <para>Administrators can create base templates from which
+            their users can start new compute instances</para>
+        </listitem>
+        <listitem>
+          <para>Users can choose from available images, or create
+            their own from existing servers</para>
+        </listitem>
+        <listitem>
+          <para>Snapshots can also be stored in the Image Service so
+            that virtual machines can be backed up quickly</para>
+        </listitem>
+      </itemizedlist>
+      <para>A multi-format image registry, the image service allows
+        uploads of private and public images in a variety of formats,
+        including:</para>
+      <itemizedlist>
+        <listitem>
+          <para>Raw</para>
+        </listitem>
+        <listitem>
+          <para>Machine (kernel/ramdisk outside of image, a.k.a.
+            AMI)</para>
+        </listitem>
+        <listitem>
+          <para>VHD (Hyper-V)</para>
+        </listitem>
+        <listitem>
+          <para>VDI (VirtualBox)</para>
+        </listitem>
+        <listitem>
+          <para>qcow2 (Qemu/KVM)</para>
+        </listitem>
+        <listitem>
+          <para>VMDK (VMWare)</para>
+        </listitem>
+        <listitem>
+          <para>OVF (VMWare, others)</para>
+        </listitem>
+      </itemizedlist>
+      <para>To checkout the complete list of Core and Incubated
+        projects under OpenStack check out OpenStack’s Launchpad
+        Project Page here : http://goo.gl/ka4SrV</para>
+  <para><guisubmenu>Amazon Web Services compatibility</guisubmenu></para>
+      <para>OpenStack APIs are compatible with Amazon EC2 and Amazon
+        S3 and thus client applications written for Amazon Web
+        Services can be used with OpenStack with minimal porting
+        effort.</para>
+  <para><guilabel>Governance</guilabel></para>
+      <para>OpenStack is governed by a non-profit foundation and its
+        board of directors, a technical committee and a user
+        committee.</para>
+      <para>The foundation's stated mission is by providing shared
+        resources to help achieve the OpenStack Mission by Protecting,
+        Empowering, and Promoting OpenStack software and the community
+        around it, including users, developers and the entire
+        ecosystem. Though, it has little to do with the development of
+        the software, which is managed by the technical committee - an
+        elected group that represents the contributors to the project,
+        and has oversight on all technical matters.</para>
+</chapter>

doc/training-guide/module001-ch004-openstack-architecture.xml

@@ -5,5 +5,373 @@
  version="5.0"
   xml:id="module001-ch004-openstack-architecture">
   <title>OpenStack Architecture</title>
-  <para>More Content To be Added ...</para>
+  <para><guilabel>Conceptual Architecture</guilabel></para>
+    <para>The OpenStack project as a whole is designed to deliver a
+      massively scalable cloud operating system. To achieve this, each
+      of the constituent services are designed to work together to
+      provide a complete Infrastructure as a Service (IaaS). This
+      integration is facilitated through public application
+      programming interfaces (APIs) that each service offers (and in
+      turn can consume). While these APIs allow each of the services
+      to use another service, it also allows an implementer to switch
+      out any service as long as they maintain the API. These are
+      (mostly) the same APIs that are available to end users of the
+      cloud.</para>
+    <para>Conceptually, you can picture the relationships between the
+      services as so:</para>
+  <figure>
+    <title>Conceptual Diagram</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image13.jpg"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <itemizedlist>
+      <listitem>
+        <para>Dashboard ("Horizon") provides a web front end to the
+          other OpenStack services</para>
+      </listitem>
+      <listitem>
+        <para>Compute ("Nova") stores and retrieves virtual disks
+          ("images") and associated metadata in Image
+          ("Glance")</para>
+      </listitem>
+      <listitem>
+        <para>Network ("Quantum") provides virtual networking for
+          Compute.</para>
+      </listitem>
+      <listitem>
+        <para>Block Storage ("Cinder") provides storage volumes for
+          Compute.</para>
+      </listitem>
+      <listitem>
+        <para>Image ("Glance") can store the actual virtual disk files
+          in the Object Store("Swift")</para>
+      </listitem>
+      <listitem>
+        <para>All the services authenticate with Identity
+          ("Keystone")</para>
+      </listitem>
+    </itemizedlist>
+    <para>This is a stylized and simplified view of the architecture,
+      assuming that the implementer is using all of the services
+      together in the most common configuration. It also only shows
+      the "operator" side of the cloud -- it does not picture how
+      consumers of the cloud may actually use it. For example, many
+      users will access object storage heavily (and directly).</para>
+  <para><guilabel>Logical Architecture</guilabel></para>
+    <para>This picture is consistent with the conceptual architecture
+      above:</para>
+  <figure>
+    <title>Logical Diagram</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image31.jpg"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <itemizedlist>
+      <listitem>
+        <para>End users can interact through a common web interface
+          (Horizon) or directly to each service through their
+          API</para>
+      </listitem>
+      <listitem>
+        <para>All services authenticate through a common source
+          (facilitated through keystone)</para>
+      </listitem>
+      <listitem>
+        <para>Individual services interact with each other through
+          their public APIs (except where privileged administrator
+          commands are necessary)</para>
+      </listitem>
+    </itemizedlist>
+    <para>In the sections below, we'll delve into the architecture for
+      each of the services.</para>
+  <para><guilabel>Dashboard</guilabel></para>
+      <para>Horizon is a modular Django web application that provides
+    an end user and administrator interface to OpenStack
+    services.</para>
+  <figure>
+    <title>Horizon Dashboard</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image10.jpg"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+      <para>As with most web applications, the architecture is fairly
+        simple:</para>
+      <itemizedlist>
+        <listitem>
+          <para>Horizon is usually deployed via mod_wsgi in Apache.
+            The code itself is separated into a reusable python module
+            with most of the logic (interactions with various
+            OpenStack APIs) and presentation (to make it easily
+            customizable for different sites).</para>
+        </listitem>
+        <listitem>
+          <para>A database (configurable as to which one). As it
+            relies mostly on the other services for data, it stores
+            very little data of its own.</para>
+        </listitem>
+      </itemizedlist>
+      <para>From a network architecture point of view, this service
+        will need to be customer accessible as well as be able to talk
+        to each service's public APIs. If you wish to use the
+        administrator functionality (i.e. for other services), it will
+        also need connectivity to their Admin API endpoints (which
+        should be non-customer accessible).</para>
+  <para><guilabel>Compute</guilabel></para>
+      <para>Nova is the most complicated and distributed component of
+        OpenStack. A large number of processes cooperate to turn end
+        user API requests into running virtual machines. Below is a
+        list of these processes and their functions:</para>
+      <itemizedlist>
+        <listitem>
+          <para>nova-api accepts and responds to end user compute API
+            calls. It supports OpenStack Compute API, Amazon's EC2 API
+            and a special Admin API (for privileged users to perform
+            administrative actions). It also initiates most of the
+            orchestration activities (such as running an instance) as
+            well as enforces some policy (mostly quota checks).</para>
+        </listitem>
+        <listitem>
+          <para>The nova-compute process is primarily a worker daemon
+            that creates and terminates virtual machine instances via
+            hypervisor's APIs (XenAPI for XenServer/XCP, libvirt for
+            KVM or QEMU, VMwareAPI for VMware, etc.). The process by
+            which it does so is fairly complex but the basics are
+            simple: accept actions from the queue and then perform a
+            series of system commands (like launching a KVM instance)
+            to carry them out while updating state in the
+            database.</para>
+        </listitem>
+        <listitem>
+          <para>nova-volume manages the creation, attaching and
+            detaching of z volumes to compute instances (similar
+            functionality to Amazon’s Elastic Block Storage). It can
+            use volumes from a variety of providers such as iSCSI or
+            Rados Block Device in Ceph. A new OpenStack project,
+            Cinder, will eventually replace nova-volume functionality.
+            In the Folsom release, nova-volume and the Block Storage
+            service will have similar functionality.</para>
+        </listitem>
+        <listitem>
+          <para>The nova-network worker daemon is very similar to
+            nova-compute and nova-volume. It accepts networking tasks
+            from the queue and then performs tasks to manipulate the
+            network (such as setting up bridging interfaces or
+            changing iptables rules). This functionality is being
+            migrated to Quantum, a separate OpenStack service. In the
+            Folsom release, much of the functionality will be
+            duplicated between nova-network and Quantum.</para>
+        </listitem>
+        <listitem>
+          <para>The nova-schedule process is conceptually the simplest
+            piece of code in OpenStack Nova: take a virtual machine
+            instance request from the queue and determines where it
+            should run (specifically, which compute server host it
+            should run on).</para>
+        </listitem>
+        <listitem>
+          <para>The queue provides a central hub for passing messages
+            between daemons. This is usually implemented with RabbitMQ
+            today, but could be any AMPQ message queue (such as Apache
+            Qpid). New to the Folsom release is support for Zero
+            MQ.</para>
+        </listitem>
+        <listitem>
+          <para>The SQL database stores most of the build-time and
+            runtime state for a cloud infrastructure. This includes
+            the instance types that are available for use, instances
+            in use, networks available and projects. Theoretically,
+            OpenStack Nova can support any database supported by
+            SQL-Alchemy but the only databases currently being widely
+            used are sqlite3 (only appropriate for test and
+            development work), MySQL and PostgreSQL.</para>
+        </listitem>
+        <listitem>
+          <para>Nova also provides console services to allow end users
+            to access their virtual instance's console through a
+            proxy. This involves several daemons (nova-console,
+            nova-novncproxy and nova-consoleauth).</para>
+        </listitem>
+      </itemizedlist>
+      <para>Nova interacts with many other OpenStack services:
+        Keystone for authentication, Glance for images and Horizon for
+        web interface. The Glance interactions are central. The API
+        process can upload and query Glance while nova-compute will
+        download images for use in launching images.</para>
+  <para><guilabel>Object Store</guilabel></para>
+      <para>The swift architecture is very distributed to prevent any
+        single point of failure as well as to scale horizontally. It
+        includes the following components:</para>
+      <itemizedlist>
+        <listitem>
+          <para>Proxy server (swift-proxy-server) accepts incoming
+            requests via the OpenStack Object API or just raw HTTP. It
+            accepts files to upload, modifications to metadata or
+            container creation. In addition, it will also serve files
+            or container listing to web browsers. The proxy server may
+            utilize an optional cache (usually deployed with memcache)
+            to improve performance.</para>
+        </listitem>
+        <listitem>
+          <para>Account servers manage accounts defined with the
+            object storage service.</para>
+        </listitem>
+        <listitem>
+          <para>Container servers manage a mapping of containers (i.e
+            folders) within the object store service.</para>
+        </listitem>
+        <listitem>
+          <para>Object servers manage actual objects (i.e. files) on
+            the storage nodes.</para>
+        </listitem>
+        <listitem>
+          <para>There are also a number of periodic process which run
+            to perform housekeeping tasks on the large data store. The
+            most important of these is the replication services, which
+            ensures consistency and availability through the cluster.
+            Other periodic processes include auditors, updaters and
+            reapers.</para>
+        </listitem>
+      </itemizedlist>
+      <para>Authentication is handled through configurable WSGI
+        middleware (which will usually be Keystone).</para>
+  <para><guilabel>Image Store</guilabel></para>
+      <para>The Glance architecture has stayed relatively stable since
+        the Cactus release. The biggest architectural change has been
+        the addition of authentication, which was added in the Diablo
+        release. Just as a quick reminder, Glance has four main parts
+        to it:</para>
+      <itemizedlist>
+        <listitem>
+          <para>glance-api accepts Image API calls for image
+            discovery, image retrieval and image storage.</para>
+        </listitem>
+        <listitem>
+          <para>glance-registry stores, processes and retrieves
+            metadata about images (size, type, etc.).</para>
+        </listitem>
+        <listitem>
+          <para>A database to store the image metadata. Like Nova, you
+            can choose your database depending on your preference (but
+            most people use MySQL or SQlite).</para>
+        </listitem>
+        <listitem>
+          <para>A storage repository for the actual image files. In
+            the diagram above, Swift is shown as the image repository,
+            but this is configurable. In addition to Swift, Glance
+            supports normal filesystems, RADOS block devices, Amazon
+            S3 and HTTP. Be aware that some of these choices are
+            limited to read-only usage.</para>
+        </listitem>
+      </itemizedlist>
+      <para>There are also a number of periodic process which run on
+        Glance to support caching. The most important of these is the
+        replication services, which ensures consistency and
+        availability through the cluster. Other periodic processes
+        include auditors, updaters and reapers.</para>
+      <para>As you can see from the diagram in the Conceptual
+        Architecture section, Glance serves a central role to the
+        overall IaaS picture. It accepts API requests for images (or
+        image metadata) from end users or Nova components and can
+        store its disk files in the object storage service,
+        Swift.</para>
+  <para><guilabel>Identity</guilabel></para>
+      <para>Keystone provides a single point of integration for
+        OpenStack policy, catalog, token and authentication.</para>
+      <itemizedlist>
+        <listitem>
+          <para>keystone handles API requests as well as providing
+            configurable catalog, policy, token and identity
+            services.</para>
+        </listitem>
+        <listitem>
+          <para>Each Keystone function has a pluggable backend which
+            allows different ways to use the particular service. Most
+            support standard backends like LDAP or SQL, as well as Key
+            Value Stores (KVS).</para>
+        </listitem>
+      </itemizedlist>
+      <para>Most people will use this as a point of customization for
+        their current authentication services.</para>
+  <para><guilabel>Network</guilabel></para>
+      <para>Quantum provides "network connectivity as a service"
+        between interface devices managed by other OpenStack services
+        (most likely Nova). The service works by allowing users to
+        create their own networks and then attach interfaces to them.
+        Like many of the OpenStack services, Quantum is highly
+        configurable due to it's plug-in architecture. These plug-ins
+        accommodate different networking equipment and software. As
+        such, the architecture and deployment can vary dramatically.
+        In the above architecture, a simple Linux networking plug-in
+        is shown.</para>
+      <itemizedlist>
+        <listitem>
+          <para>quantum-server accepts API requests and then routes
+            them to the appropriate quantum plugin for action.</para>
+        </listitem>
+        <listitem>
+          <para>Quantum plugins and agents perform the actual actions
+            such as plugging and unplugging ports, creating networks
+            or subnets and IP addressing. These plugins and agents
+            differ depending on the vendor and technologies used in
+            the particular cloud. Quantum ships with plugins and
+            agents for: Cisco virtual and physical switches, Nicira
+            NVP product, NEC OpenFlow products, Openvswitch, Linux
+            bridging and the Ryu Network Operating System.</para>
+        </listitem>
+        <listitem>
+          <para>The common agents are L3 (layer 3), DHCP (dynamic host
+            IP addressing) and the specific plug-in agent.</para>
+        </listitem>
+        <listitem>
+          <para>Most Quantum installations will also make use of a
+            messaging queue to route information between the
+            quantum-server and various agents as well as a database to
+            store networking state for particular plugins.</para>
+        </listitem>
+      </itemizedlist>
+      <para>Quantum will interact mainly with Nova, where it will
+        provide networks and connectivity for its instances.</para>
+  <para><guilabel>Block Storage</guilabel></para>
+      <para>Cinder separates out the persistent block storage
+        functionality that was previously part of Openstack Compute
+        (in the form of nova-volume) into it's own service. The
+        OpenStack Block Storage API allows for manipulation of
+        volumes, volume types (similar to compute flavors) and volume
+        snapshots.</para>
+      <itemizedlist>
+        <listitem>
+          <para>cinder-api accepts API requests and routes them to
+            cinder-volume for action.</para>
+        </listitem>
+        <listitem>
+          <para>cinder-volume acts upon the requests by reading or
+            writing to the Cinder database to maintain state,
+            interacting with other processes (like cinder-scheduler)
+            through a message queue and directly upon block storage
+            providing hardware or software. It can interact with a
+            variety of storage providers through a driver
+            architecture. Currently, there are drivers for IBM,
+            SolidFire, NetApp, Nexenta, Zadara, linux iSCSI and other
+            storage providers.</para>
+        </listitem>
+        <listitem>
+          <para>Much like nova-scheduler, the cinder-scheduler daemon
+            picks the optimal block storage provider node to create
+            the volume on.</para>
+        </listitem>
+        <listitem>
+          <para>Cinder deployments will also make use of a messaging
+            queue to route information between the cinder processes as
+            well as a database to store volume state.</para>
+        </listitem>
+      </itemizedlist>
+      <para>Like Quantum, Cinder will mainly interact with Nova,
+        providing volumes for its instances.</para>
 </chapter>

doc/training-guide/module001-ch005-vm-provisioning-walk-through.xml

@@ -6,4 +6,234 @@
   xml:id="module001-ch005-vm-provisioning-walk-through">
   <title>VM Provisioning Walk Through</title>
   <para>More Content To be Added ...</para>
-</chapter>
+  <para>OpenStack Compute gives you a tool to orchestrate a cloud,
+    including running instances, managing networks, and controlling
+    access to the cloud through users and projects. The underlying
+    open source project's name is Nova, and it provides the software
+    that can control an Infrastructure as a Service (IaaS) cloud
+    computing platform. It is similar in scope to Amazon EC2 and
+    Rackspace Cloud Servers. OpenStack Compute does not include any
+    virtualization software; rather it defines drivers that interact
+    with underlying virtualization mechanisms that run on your host
+    operating system, and exposes functionality over a web-based
+    API.</para>
+  <para><guilabel>Hypervisors</guilabel></para>
+    <para>OpenStack Compute requires a hypervisor and Compute controls
+      the hypervisors through an API server. The process for selecting
+      a hypervisor usually means prioritizing and making decisions
+      based on budget and resource constraints as well as the
+      inevitable list of supported features and required technical
+      specifications. The majority of development is done with the KVM
+      and Xen-based hypervisors. Refer to 
+      <link xlink:href="http://wiki.openstack.org/HypervisorSupportMatrix"></link>
+      <link xlink:href="http://goo.gl/n7AXnC">
+        http://goo.gl/n7AXnC</link>
+      for a detailed list of features and support across the hypervisors.</para>
+    <para>With OpenStack Compute, you can orchestrate clouds using
+      multiple hypervisors in different zones. The types of
+      virtualization standards that may be used with Compute
+      include:</para>
+    <itemizedlist>
+      <listitem>
+        <para>KVM- Kernel-based Virtual Machine (visit <link
+            xlink:href="http://goo.gl/70dvRb"
+            >http://goo.gl/70dvRb</link>)</para>
+      </listitem>
+      <listitem>
+        <para>LXC- Linux Containers (through libvirt) (visit <link
+            xlink:href="http://goo.gl/Ous3ly"
+            >http://goo.gl/Ous3ly</link>)</para>
+      </listitem>
+      <listitem>
+        <para>QEMU- Quick EMUlator (visit <link
+            xlink:href="http://goo.gl/WWV9lL"
+            >http://goo.gl/WWV9lL</link>)</para>
+      </listitem>
+      <listitem>
+        <para>UML- User Mode Linux (visit <link
+            xlink:href="http://goo.gl/4HAkJj"
+            >http://goo.gl/4HAkJj</link>)</para>
+      </listitem>
+      <listitem>
+        <para>VMWare vSphere4.1 update 1 and newer (visit <link
+            xlink:href="http://goo.gl/0DBeo5"
+            >http://goo.gl/0DBeo5</link>)</para>
+      </listitem>
+      <listitem>
+        <para>Xen- Xen, Citrix XenServer and Xen Cloud Platform (XCP)
+          (visit <link xlink:href="http://goo.gl/yXP9t1"
+            >http://goo.gl/yXP9t1</link>)</para>
+      </listitem>
+      <listitem>
+        <para>Bare Metal- Provisions physical hardware via pluggable
+          sub-drivers. (visit <link xlink:href="http://goo.gl/exfeSg"
+            >http://goo.gl/exfeSg</link>)</para>
+      </listitem>
+    </itemizedlist>
+  <para><guilabel>Users and Tenants (Projects)</guilabel></para>
+    <para>The OpenStack Compute system is designed to be used by many
+      different cloud computing consumers or customers, basically
+      tenants on a shared system, using role-based access assignments.
+      Roles control the actions that a user is allowed to perform. In
+      the default configuration, most actions do not require a
+      particular role, but this is configurable by the system
+      administrator editing the appropriate policy.json file that
+      maintains the rules. For example, a rule can be defined so that
+      a user cannot allocate a public IP without the admin role. A
+      user's access to particular images is limited by tenant, but the
+      username and password are assigned per user. Key pairs granting
+      access to an instance are enabled per user, but quotas to
+      control resource consumption across available hardware resources
+      are per tenant.</para>
+    <para>While the original EC2 API supports users, OpenStack Compute
+      adds the concept of tenants. Tenants are isolated resource
+      containers forming the principal organizational structure within
+      the Compute service. They consist of a separate VLAN, volumes,
+      instances, images, keys, and users. A user can specify which
+      tenant he or she wishes to be known as by appending :project_id
+      to his or her access key. If no tenant is specified in the API
+      request, Compute attempts to use a tenant with the same ID as
+      the user</para>
+    <para>For tenants, quota controls are available to limit
+      the:</para>
+    <itemizedlist>
+      <listitem>
+        <para>Number of volumes which may be created</para>
+      </listitem>
+      <listitem>
+        <para>Total size of all volumes within a project as measured
+          in GB</para>
+      </listitem>
+      <listitem>
+        <para>Number of instances which may be launched</para>
+      </listitem>
+      <listitem>
+        <para>Number of processor cores which may be allocated</para>
+      </listitem>
+      <listitem>
+        <para>Floating IP addresses (assigned to any instance when it
+          launches so the instance has the same publicly accessible IP
+          addresses)</para>
+      </listitem>
+      <listitem>
+        <para>Fixed IP addresses (assigned to the same instance each
+          time it boots, publicly or privately accessible, typically
+          private for management purposes)</para>
+      </listitem>
+    </itemizedlist>
+  <para><guilabel>Images and Instances</guilabel></para>
+    <para>This introduction provides a high level overview of what
+      images and instances are and description of the life-cycle of a
+      typical virtual system within the cloud. There are many ways to
+      configure the details of an OpenStack cloud and many ways to
+      implement a virtual system within that cloud. These
+      configuration details as well as the specific command line
+      utilities and API calls to perform the actions described are
+      presented in the Image Managementand Volume
+      Managementchapters.</para>
+    <para>Images are disk images which are templates for virtual
+      machine file systems. The image service, Glance, is responsible
+      for the storage and management of images within
+      OpenStack.</para>
+    <para>Instances are the individual virtual machines running on
+      physical compute nodes. The compute service, Nova, manages
+      instances. Any number of instances maybe started from the same
+      image. Each instance is run from a copy of the base image so
+      runtime changes made by an instance do not change the image it
+      is based on. Snapshots of running instances may be taken which
+      create a new image based on the current disk state of a
+      particular instance.</para>
+    <para>When starting an instance a set of virtual resources known
+      as a flavor must be selected. Flavors define how many virtual
+      CPUs an instance has and the amount of RAM and size of its
+      ephemeral disks. OpenStack provides a number of predefined
+      flavors which cloud administrators may edit or add to. Users
+      must select from the set of available flavors defined on their
+      cloud.</para>
+    <para>Additional resources such as persistent volume storage and
+      public IP address may be added to and removed from running
+      instances. The examples below show the cinder-volume service
+      which provide persistent block storage as opposed to the
+      ephemeral storage provided by the instance flavor.</para>
+    <para>Here is an example of the life cycle of a typical virtual
+      system within an OpenStack cloud to illustrate these
+      concepts.</para>
+    <para><guilabel>Initial State</guilabel></para>
+  <para><guilabel>Images and Instances</guilabel></para>
+    <para>The following diagram shows the system state prior to
+      launching an instance. The image store fronted by the image
+      service, Glance, has some number of predefined images. In the
+      cloud there is an available compute node with available vCPU,
+      memory and local disk resources. Plus there are a number of
+      predefined volumes in the cinder-volume service.</para>
+    <para>Figure 2.1. Base image state with no running
+      instances</para>
+  <figure>
+    <title>Initial State</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image21.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+  <para><guilabel>Launching an instance</guilabel></para>
+    <para>To launch an instance the user selects an image, a flavor
+      and optionally other attributes. In this case the selected
+      flavor provides a root volume (as all flavors do) labeled vda in
+      the diagram and additional ephemeral storage labeled vdb in the
+      diagram. The user has also opted to map a volume from the
+      cinder-volume store to the third virtual disk, vdc, on this
+      instance.</para>
+    <para>Figure 2.2. Instance creation from image and run time
+      state</para>
+  <figure>
+    <title>Launch VM Instance</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image09.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para>The OpenStack system copies the base image from the image
+      store to local disk which is used as the first disk of the
+      instance (vda), having small images will result in faster start
+      up of your instances as less data needs to be copied across the
+      network. The system also creates a new empty disk image to
+      present as the second disk (vdb). Be aware that the second disk
+      is an empty disk with an emphemeral life as it is destroyed when
+      you delete the instance. The compute node attaches to the
+      requested cinder-volume using iSCSI and maps this to the third
+      disk (vdc) as requested. The vCPU and memory resources are
+      provisioned and the instance is booted from the first drive. The
+      instance runs and changes data on the disks indicated in red in
+      the diagram.</para>
+    <para>There are many possible variations in the details of the
+      scenario, particularly in terms of what the backing storage is
+      and the network protocols used to attach and move storage. One
+      variant worth mentioning here is that the ephemeral storage used
+      for volumes vda and vdb in this example may be backed by network
+      storage rather than local disk. The details are left for later
+      chapters.</para>
+    <para><guilabel>End State</guilabel></para>
+      <para>Once the instance has served its purpose and is deleted
+        all state is reclaimed, except the persistent volume. The
+        ephemeral storage is purged. Memory and vCPU resources are
+        released. And of course the image has remained unchanged
+        throughout.</para>
+      <para>Figure 2.3. End state of image and volume after instance
+        exits</para>
+  <figure>
+    <title>End State</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image22.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+      <para>Once you launch a VM in OpenStack, theres something more
+        going on in the background. To understand what's happening
+        behind the Dashboard, lets take a deeper dive into OpenStack’s
+        VM provisioning. For launching a VM, you can either use
+        Command Line Interface or the OpenStack Horizon Dashboard.
+      </para>
+</chapter>

doc/training-guide/module001-ch007-keystone-arch.xml

@@ -6,4 +6,193 @@
   xml:id="module001-ch007-keystone-arch">
   <title>Ketstone Architecture</title>
   <para>More Content To be Added ...</para>
+  
+    <para><guilabel>Identity Service Concepts</guilabel></para>
+    <para>The Identity service performs the following
+      functions:</para>
+    <itemizedlist>
+      <listitem>
+        <para>User management. Tracks users and their
+          permissions.</para>
+      </listitem>
+      <listitem>
+        <para>Service catalog. Provides a catalog of available
+          services with their API endpoints.</para>
+      </listitem>
+    </itemizedlist>
+    <para>To understand the Identity Service, you must understand the
+      following concepts:</para>
+    
+      <para><guilabel>User</guilabel></para>
+      <para>Digital representation of a person, system, or service who
+        uses OpenStack cloud services. Identity authentication
+        services will validate that incoming request are being made by
+        the user who claims to be making the call. Users have a login
+        and may be assigned tokens to access resources. Users may be
+        directly assigned to a particular tenant and behave as if they
+        are contained in that tenant.</para>
+    
+    
+      <para><guilabel><anchor xml:id="h.i1npk4aiu35h"/>Credentials</guilabel></para>
+      <para>Data that is known only by a user that proves who they
+        are. In the Identity Service, examples are:</para>
+      <itemizedlist>
+        <listitem>
+          <para>Username and password</para>
+        </listitem>
+        <listitem>
+          <para>Username and API key</para>
+        </listitem>
+        <listitem>
+          <para>An authentication token provided by the Identity
+            Service</para>
+        </listitem>
+      </itemizedlist>
+    
+    
+      <para><guilabel><anchor xml:id="h.aa29gdlbf7qa"/>Authentication</guilabel></para>
+      <para>The act of confirming the identity of a user. The Identity
+        Service confirms an incoming request by validating a set of
+        credentials supplied by the user. These credentials are
+        initially a username and password or a username and API key.
+        In response to these credentials, the Identity Service issues
+        the user an authentication token, which the user provides in
+        subsequent requests.</para>
+    
+    
+      <para><guilabel><anchor xml:id="h.grqljkbnx8fs"/>Token</guilabel></para>
+      <para>An arbitrary bit of text that is used to access resources.
+        Each token has a scope which describes which resources are
+        accessible with it. A token may be revoked at anytime and is
+        valid for a finite duration.</para>
+      <para>While the Identity Service supports token-based
+        authentication in this release, the intention is for it to
+        support additional protocols in the future. The intent is for
+        it to be an integration service foremost, and not aspire to be
+        a full-fledged identity store and management solution.</para>
+    
+    
+      <para><guilabel><anchor xml:id="h.qz798xvt751f"/>Tenant</guilabel></para>
+      <para>A container used to group or isolate resources and/or
+        identity objects. Depending on the service operator, a tenant
+        may map to a customer, account, organization, or
+        project.</para>
+    
+    
+      <para><guilabel><anchor xml:id="h.ayp97sn984my"/>Service</guilabel></para>
+      <para>An OpenStack service, such as Compute (Nova), Object
+        Storage (Swift), or Image Service (Glance). Provides one or
+        more endpoints through which users can access resources and
+        perform operations.</para>
+    
+    
+      <para><guilabel><anchor xml:id="h.74y77xwdnwlm"/>Endpoint</guilabel></para>
+      <para>An network-accessible address, usually described by URL,
+        from where you access a service. If using an extension for
+        templates, you can create an endpoint template, which
+        represents the templates of all the consumable services that
+        are available across the regions.</para>
+    
+    
+      <para><guilabel><anchor xml:id="h.r7samiog05in"/>Role</guilabel></para>
+      <para>A personality that a user assumes that enables them to
+        perform a specific set of operations. A role includes a set of
+        rights and privileges. A user assuming that role inherits
+        those rights and privileges.</para>
+      <para>In the Identity Service, a token that is issued to a user
+        includes the list of roles that user can assume. Services that
+        are being called by that user determine how they interpret the
+        set of roles a user has and which operations or resources each
+        role grants access to.</para>
+  <figure>
+    <title>Keystone Authentication</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image19.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    
+  
+  
+    <para><guilabel><anchor xml:id="h.rdpcpnbvn06w"/>User management</guilabel></para>
+    <para>The main components of Identity user management are:</para>
+    <itemizedlist>
+      <listitem>
+        <para>Users</para>
+      </listitem>
+      <listitem>
+        <para>Tenants</para>
+      </listitem>
+      <listitem>
+        <para>Roles</para>
+      </listitem>
+    </itemizedlist>
+    <para>A userrepresents a human user, and has associated
+      information such as username, password and email. This example
+      creates a user named "alice":</para>
+    <para>$ keystone user-create --name=alice --pass=mypassword123
+      --email=alice@example.com</para>
+    <para>A tenantcan be a project, group, or organization. Whenever
+      you make requests to OpenStack services, you must specify a
+      tenant. For example, if you query the Compute service for a list
+      of running instances, you will receive a list of all of the
+      running instances in the tenant you specified in your query.
+      This example creates a tenant named "acme":</para>
+    <para>$ keystone tenant-create --name=acmeA rolecaptures what
+      operations a user is permitted to perform in a given tenant.
+      This example creates a role named "compute-user":</para>
+    <para>$ keystone role-create --name=compute-userThe Identity
+      service associates a user with a tenant and a role. To continue
+      with our previous examples, we may wish to assign the "alice"
+      user the "compute-user" role in the "acme" tenant:</para>
+    <para>$ keystone user-list</para>
+    <para>$ keystone user-role-add --user=892585 --role=9a764e
+      --tenant-id=6b8fd2   </para>
+    <para>A user can be assigned different roles in different tenants:
+      for example, Alice may also have the "admin" role in the
+      "Cyberdyne" tenant. A user can also be assigned multiple roles
+      in the same tenant.</para>
+    <para>The /etc/[SERVICE_CODENAME]/policy.json controls what users
+      are allowed to do for a given service. For example,
+      /etc/nova/policy.json specifies the access policy for the
+      Compute service, /etc/glance/policy.json specifies the access
+      policy for the Image service, and /etc/keystone/policy.json
+      specifies the access policy for the Identity service.</para>
+    <para>The default policy.json files in the Compute, Identity, and
+      Image service recognize only the admin role: all operations that
+      do not require the admin role will be accessible by any user
+      that has any role in a tenant.</para>
+    <para>If you wish to restrict users from performing operations in,
+      say, the Compute service, you need to create a role in the
+      Identity service and then modify /etc/nova/policy.json so that
+      this role is required for Compute operations.</para>
+    <para>For example, this line in /etc/nova/policy.json specifies
+      that there are no restrictions on which users can create
+      volumes: if the user has any role in a tenant, they will be able
+      to create volumes in that tenant.</para>
+    
+      <para><guilabel><anchor xml:id="h.f5989v85c3fd"/></guilabel></para>
+    
+  
+  
+    <para><guilabel><anchor xml:id="h.1rrjgvz0nkwh"/>Service
+      management</guilabel></para>
+    <para>The Identity Service provides the following service
+      management functions:</para>
+    <itemizedlist>
+      <listitem>
+        <para>Services</para>
+      </listitem>
+      <listitem>
+        <para>Endpoints</para>
+      </listitem>
+    </itemizedlist>
+    <para>The Identity Service also maintains a user that corresponds
+      to each service (such as, a user named nova, for the Compute
+      service) and a special service tenant, which is called
+      service.</para>
+    <para>The commands for creating services and endpoints are
+      described in a later section.</para>
+  
 </chapter>

doc/training-guide/module001-ch008-queues-messaging.xml

@@ -1,9 +1,440 @@
 <?xml version="1.0" encoding="utf-8"?>
-<chapter xmlns="http://docbook.org/ns/docbook"
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="module001-ch008-queues-messaging">
-  xmlns:xi="http://www.w3.org/2001/XInclude"
-  xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0"
-  xml:id="module001-ch008-queues-messaging">
   <title>OpenStack Messaging and Queues</title>
-  <para>More Content To be Added ...</para>
+  <figure>
+    <title>Messaging in OpenStack</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image04.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+  <para>AMQP is the messaging technology chosen by the OpenStack
+    cloud. The AMQP broker, either RabbitMQ or Qpid, sits between any
+    two Nova components and allows them to communicate in a loosely
+    coupled fashion. More precisely, Nova components (the compute
+    fabric of OpenStack) use Remote Procedure Calls (RPC hereinafter)
+    to communicate to one another; however such a paradigm is built
+    atop the publish/subscribe paradigm so that the following benefits
+    can be achieved:</para>
+  <itemizedlist>
+    <listitem>
+      <para>Decoupling between client and servant (such as the client
+        does not need to know where the servant’s reference
+        is).</para>
+    </listitem>
+    <listitem>
+      <para>Full a-synchronism between client and servant (such as the
+        client does not need the servant to run at the same time of
+        the remote call).</para>
+    </listitem>
+    <listitem>
+      <para>Random balancing of remote calls (such as if more servants
+        are up and running, one-way calls are transparently dispatched
+        to the first available servant).</para>
+    </listitem>
+  </itemizedlist>
+  <para>Nova uses direct, fanout, and topic-based exchanges. The
+    architecture looks like the one depicted in the figure
+    below:</para>
+  <figure>
+    <title>AMQP</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image24.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+  <para>Nova implements RPC (both request+response, and one-way,
+    respectively nicknamed ‘rpc.call’ and ‘rpc.cast’) over AMQP by
+    providing an adapter class which take cares of marshaling and
+    unmarshaling of messages into function calls. Each Nova service
+    (for example Compute, Scheduler, etc.) create two queues at the
+    initialization time, one which accepts messages with routing keys
+    ‘NODE-TYPE.NODE-ID’ (for example compute.hostname) and another,
+    which accepts messages with routing keys as generic ‘NODE-TYPE’
+    (for example compute). The former is used specifically when
+    Nova-API needs to redirect commands to a specific node like
+    ‘euca-terminate instance’. In this case, only the compute node
+    whose host’s hypervisor is running the virtual machine can kill
+    the instance. The API acts as a consumer when RPC calls are
+    request/response, otherwise is acts as publisher only.</para>
+    <para><guilabel>Nova RPC Mappings</guilabel></para>
+    <para>The figure below shows the internals of a message broker
+      node (referred to as a RabbitMQ node in the diagrams) when a
+      single instance is deployed and shared in an OpenStack cloud.
+      Every Nova component connects to the message broker and,
+      depending on its personality (for example a compute node or a
+      network node), may use the queue either as an Invoker (such as
+      API or Scheduler) or a Worker (such as Compute or Network).
+      Invokers and Workers do not actually exist in the Nova object
+      model, but we are going to use them as an abstraction for sake
+      of clarity. An Invoker is a component that sends messages in the
+      queuing system via two operations: 1) rpc.call and ii) rpc.cast;
+      a Worker is a component that receives messages from the queuing
+      system and reply accordingly to rcp.call operations.</para>
+    <para>Figure 2 shows the following internal elements:</para>
+    <itemizedlist>
+      <listitem>
+        <para><emphasis role="bold">Topic Publisher:</emphasis>a Topic
+        Publisher comes to life when an rpc.call or an rpc.cast
+        operation is executed; this object is instantiated and used to
+        push a message to the queuing system. Every publisher connects
+        always to the same topic-based exchange; its life-cycle is
+        limited to the message delivery.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Direct Consumer:</emphasis>a
+        Direct Consumer comes to life if (an only if) a rpc.call
+        operation is executed; this object is instantiated and used to
+        receive a response message from the queuing system; Every
+        consumer connects to a unique direct-based exchange via a
+        unique exclusive queue; its life-cycle is limited to the
+        message delivery; the exchange and queue identifiers are
+        determined by a UUID generator, and are marshaled in the
+        message sent by the Topic Publisher (only rpc.call
+        operations).</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Topic Consumer:</emphasis>a Topic
+        Consumer comes to life as soon as a Worker is instantiated and
+        exists throughout its life-cycle; this object is used to
+        receive messages from the queue and it invokes the appropriate
+        action as defined by the Worker role. A Topic Consumer
+        connects to the same topic-based exchange either via a shared
+        queue or via a unique exclusive queue. Every Worker has two
+        topic consumers, one that is addressed only during rpc.cast
+        operations (and it connects to a shared queue whose exchange
+        key is ‘topic’) and the other that is addressed only during
+        rpc.call operations (and it connects to a unique queue whose
+        exchange key is ‘topic.host’).</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Direct Publisher:</emphasis>a
+        Direct Publisher comes to life only during rpc.call operations
+        and it is instantiated to return the message required by the
+        request/response operation. The object connects to a
+        direct-based exchange whose identity is dictated by the
+        incoming message.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Topic Exchange:</emphasis>The
+        Exchange is a routing table that exists in the context of a
+        virtual host (the multi-tenancy mechanism provided by Qpid or
+        RabbitMQ); its type (such as topic vs. direct) determines the
+        routing policy; a message broker node will have only one
+        topic-based exchange for every topic in Nova.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Direct Exchange:</emphasis>this is
+        a routing table that is created during rpc.call operations;
+        there are many instances of this kind of exchange throughout
+        the life-cycle of a message broker node, one for each rpc.call
+        invoked.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Queue Element:</emphasis>A Queue
+        is a message bucket. Messages are kept in the queue until a
+        Consumer (either Topic or Direct Consumer) connects to the
+        queue and fetch it. Queues can be shared or can be exclusive.
+        Queues whose routing key is ‘topic’ are shared amongst Workers
+        of the same personality.</para>
+      </listitem>
+    </itemizedlist>
+  <figure>
+    <title>RabbitMQ</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image20.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para><guilabel>RPC Calls</guilabel></para>
+    <para>The diagram below shows the message flow during an rp.call
+      operation:</para>
+    <orderedlist>
+      <listitem>
+        <para>a Topic Publisher is instantiated to send the message
+          request to the queuing system; immediately before the
+          publishing operation, a Direct Consumer is instantiated to
+          wait for the response message.</para>
+      </listitem>
+      <listitem>
+        <para>once the message is dispatched by the exchange, it is
+          fetched by the Topic Consumer dictated by the routing key
+          (such as ‘topic.host’) and passed to the Worker in charge of
+          the task.</para>
+      </listitem>
+      <listitem>
+        <para>once the task is completed, a Direct Publisher is
+          allocated to send the response message to the queuing
+          system.</para>
+      </listitem>
+      <listitem>
+        <para>once the message is dispatched by the exchange, it is
+          fetched by the Direct Consumer dictated by the routing key
+          (such as ‘msg_id’) and passed to the Invoker.</para>
+      </listitem>
+    </orderedlist>
+  <figure>
+    <title>RabbitMQ</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image28.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para><guilabel>RPC Casts</guilabel></para>
+    <para>The diagram below the message flow during an rp.cast
+      operation:</para>
+    <orderedlist>
+      <listitem>
+        <para>A Topic Publisher is instantiated to send the message
+          request to the queuing system.</para>
+      </listitem>
+      <listitem>
+        <para>Once the message is dispatched by the exchange, it is
+          fetched by the Topic Consumer dictated by the routing key
+          (such as ‘topic’) and passed to the Worker in charge of the
+          task.</para>
+      </listitem>
+    </orderedlist>
+  <figure>
+    <title>RabbitMQ</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image20.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para><guilabel>AMQP Broker Load</guilabel></para>
+    <para>At any given time the load of a message broker node running
+      either Qpid or RabbitMQ is function of the following
+      parameters:</para>
+    <itemizedlist>
+      <listitem>
+        <para>Throughput of API calls: the number of API calls (more
+          precisely rpc.call ops) being served by the OpenStack cloud
+          dictates the number of direct-based exchanges, related
+          queues and direct consumers connected to them.</para>
+      </listitem>
+      <listitem>
+        <para>Number of Workers: there is one queue shared amongst
+          workers with the same personality; however there are as many
+          exclusive queues as the number of workers; the number of
+          workers dictates also the number of routing keys within the
+          topic-based exchange, which is shared amongst all
+          workers.</para>
+      </listitem>
+    </itemizedlist>
+    <para>The figure below shows the status of a RabbitMQ node after
+      Nova components’ bootstrap in a test environment. Exchanges and
+      queues being created by Nova components are:</para>
+    <itemizedlist>
+      <listitem>
+        <para>Exchanges</para>
+      </listitem>
+    </itemizedlist>
+    <orderedlist>
+      <listitem>
+        <para>nova (topic exchange)</para>
+      </listitem>
+    </orderedlist>
+    <itemizedlist>
+      <listitem>
+        <para>Queues</para>
+      </listitem>
+    </itemizedlist>
+    <orderedlist>
+      <listitem>
+        <para>compute.phantom (phantom is hostname)</para>
+      </listitem>
+      <listitem>
+        <para>compute</para>
+      </listitem>
+      <listitem>
+        <para>network.phantom (phantom is hostname)</para>
+      </listitem>
+      <listitem>
+        <para>network</para>
+      </listitem>
+      <listitem>
+        <para>scheduler.phantom (phantom is hostname)</para>
+      </listitem>
+      <listitem>
+        <para>scheduler</para>
+      </listitem>
+    </orderedlist>
+    <para><guilabel>RabbitMQ Gotchas</guilabel></para>
+    <para>Nova uses Kombu to connect to the RabbitMQ environment.
+      Kombu is a Python library that in turn uses AMQPLib, a library
+      that implements the standard AMQP 0.8 at the time of writing.
+      When using Kombu, Invokers and Workers need the following
+      parameters in order to instantiate a Connection object that
+      connects to the RabbitMQ server (please note that most of the
+      following material can be also found in the Kombu documentation;
+      it has been summarized and revised here for sake of
+      clarity):</para>
+    <itemizedlist>
+      <listitem>
+        <para><emphasis role="bold">Hostname:</emphasis> The hostname
+        to the AMQP server.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Userid:</emphasis> A valid
+        username used to authenticate to the server.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Password:</emphasis> The password
+        used to authenticate to the server.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Virtual_host:</emphasis> The name
+        of the virtual host to work with. This virtual host must exist
+        on the server, and the user must have access to it. Default is
+        “/”.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Port:</emphasis> The port of the
+        AMQP server. Default is 5672 (amqp).</para>
+      </listitem>
+    </itemizedlist>
+    <para>The following parameters are default:</para>
+    <itemizedlist>
+      <listitem>
+        <para><emphasis role="bold">Insist:</emphasis> insist on
+        connecting to a server. In a configuration with multiple
+        load-sharing servers, the Insist option tells the server that
+        the client is insisting on a connection to the specified
+        server. Default is False.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Connect_timeout:</emphasis> the
+        timeout in seconds before the client gives up connecting to
+        the server. The default is no timeout.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">SSL:</emphasis> use SSL to connect
+        to the server. The default is False.</para>
+      </listitem>
+    </itemizedlist>
+    <para>More precisely Consumers need the following
+      parameters:</para>
+    <itemizedlist>
+      <listitem>
+        <para><emphasis role="bold">Connection:</emphasis> the above
+        mentioned Connection object.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Queue:</emphasis>name of the
+        queue.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Exchange:</emphasis>name of the
+        exchange the queue binds to.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Routing_key:</emphasis>the
+        interpretation of the routing key depends on the value of the
+        exchange_type attribute.</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+        <para><emphasis role="bold">Direct exchange:</emphasis>if the
+        routing key property of the message and the routing_key
+        attribute of the queue are identical, then the message is
+        forwarded to the queue.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Fanout
+        exchange:</emphasis>messages are forwarded to the queues bound
+        the exchange, even if the binding does not have a key.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Topic exchange:</emphasis>if the
+        routing key property of the message matches the routing key of
+        the key according to a primitive pattern matching scheme, then
+        the message is forwarded to the queue. The message routing key
+        then consists of words separated by dots (”.”, like domain
+        names), and two special characters are available; star (“”)
+        and hash (“#”). The star matches any word, and the hash
+        matches zero or more words. For example ”.stock.#” matches the
+        routing keys “usd.stock” and “eur.stock.db” but not
+        “stock.nasdaq”.</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+        <para><emphasis role="bold">Durable:</emphasis>this flag
+        determines the durability of both exchanges and queues;
+        durable exchanges and queues remain active when a RabbitMQ
+        server restarts. Non-durable exchanges/queues (transient
+        exchanges/queues) are purged when a server restarts. It is
+        worth noting that AMQP specifies that durable queues cannot
+        bind to transient exchanges. Default is True.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Auto_delete:</emphasis>if set, the
+        exchange is deleted when all queues have finished using it.
+        Default is False.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Exclusive:</emphasis>exclusive
+        queues (such as non-shared) may only be consumed from by the
+        current connection. When exclusive is on, this also implies
+        auto_delete. Default is False.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Exchange_type:</emphasis>AMQP
+        defines several default exchange types (routing algorithms)
+        that covers most of the common messaging use cases.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold"
+        >Auto_ack:</emphasis>acknowledgement is handled automatically
+        once messages are received. By default auto_ack is set to
+        False, and the receiver is required to manually handle
+        acknowledgment.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">No_ack:</emphasis>it disable
+        acknowledgement on the server-side. This is different from
+        auto_ack in that acknowledgement is turned off altogether.
+        This functionality increases performance but at the cost of
+        reliability. Messages can get lost if a client dies before it
+        can deliver them to the application.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Auto_declare:</emphasis>if this is
+        True and the exchange name is set, the exchange will be
+        automatically declared at instantiation. Auto declare is on by
+        default. Publishers specify most the parameters of Consumers
+        (such as they do not specify a queue name), but they can also
+        specify the following:</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">Delivery_mode:</emphasis>the
+        default delivery mode used for messages. The value is an
+        integer. The following delivery modes are supported by
+        RabbitMQ:</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+        <para><emphasis role="bold">1 or “transient”:</emphasis>the
+        message is transient. Which means it is stored in memory only,
+        and is lost if the server dies or restarts.</para>
+      </listitem>
+      <listitem>
+        <para><emphasis role="bold">2 or “persistent”:</emphasis>the
+        message is persistent. Which means the message is stored both
+        in-memory, and on disk, and therefore preserved if the server
+        dies or restarts.</para>
+      </listitem>
+    </itemizedlist>
+    <para>The default value is 2 (persistent). During a send
+      operation, Publishers can override the delivery mode of messages
+      so that, for example, transient messages can be sent over a
+      durable queue.</para>
 </chapter>

doc/training-guide/module001-ch009-vm-placement.xml

@@ -5,5 +5,203 @@
  version="5.0"
   xml:id="module001-ch009-vm-placement">
   <title>VM Placement</title>
-  <para>To be Added</para>
+  <para>Compute uses the nova-scheduler service to determine how to
+    dispatch compute and volume requests. For example, the
+    nova-scheduler service determines which host a VM should launch
+    on. The term hostin the context of filters means a physical node
+    that has a nova-compute service running on it. You can configure
+    the scheduler through a variety of options.</para>
+  <figure>
+    <title>Nova</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image29.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+  <para>Just as shown by above figure, nova-scheduler interacts with
+    other components through queue and central database repo. For
+    scheduling, queue is the essential communications hub.</para>
+  <para>All compute nodes (also known as hosts in terms of OpenStack)
+    periodically publish their status, resources available and
+    hardware capabilities to nova-scheduler through the queue.
+    nova-scheduler then collects this data and uses it to make
+    decisions when a request comes in.</para>
+  <para>By default, the compute scheduler is configured as a filter
+    scheduler, as described in the next section. In the default
+    configuration, this scheduler considers hosts that meet all the
+    following criteria:</para>
+  <itemizedlist>
+    <listitem>
+      <para>Are in the requested availability zone
+        (AvailabilityZoneFilter).</para>
+    </listitem>
+    <listitem>
+      <para>Have sufficient RAM available (RamFilter).</para>
+    </listitem>
+    <listitem>
+      <para>Are capable of servicing the request
+        (ComputeFilter).</para>
+    </listitem>
+  </itemizedlist>
+  
+  
+    <para><guilabel>Filter Scheduler</guilabel></para>
+    <para>The Filter Scheduler supports filtering and weighting to
+    make informed decisions on where a new instance should be created.
+    This Scheduler supports only working with Compute Nodes.</para>
+    
+      <para><guilabel>Filtering</guilabel></para>
+  <figure>
+    <title>Filtering</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image27.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+      <para>During its work Filter Scheduler firstly makes dictionary
+        of unfiltered hosts, then filters them using filter properties
+        and finally chooses hosts for the requested number of
+        instances (each time it chooses the most weighed host and
+        appends it to the list of selected hosts).</para>
+      <para>If it turns up, that it can’t find candidates for the next
+        instance, it means that there are no more appropriate hosts
+        where the instance could be scheduled.</para>
+      <para>If we speak about filtering and weighting, their work is
+        quite flexible in the Filter Scheduler. There are a lot of
+        filtering strategies for the Scheduler to support. Also you
+        can even implement your own algorithm of filtering.</para>
+      <para>There are some standard filter classes to use
+        (nova.scheduler.filters):</para>
+      <itemizedlist>
+        <listitem>
+          <para>AllHostsFilter - frankly speaking, this filter does no
+            operation. It passes all the available hosts.</para>
+        </listitem>
+        <listitem>
+          <para>ImagePropertiesFilter - filters hosts based on
+            properties defined on the instance’s image. It passes
+            hosts that can support the specified image properties
+            contained in the instance.</para>
+        </listitem>
+        <listitem>
+          <para>AvailabilityZoneFilter - filters hosts by availability
+            zone. It passes hosts matching the availability zone
+            specified in the instance properties.</para>
+        </listitem>
+        <listitem>
+          <para>ComputeCapabilitiesFilter - checks that the
+            capabilities provided by the host compute service satisfy
+            any extra specifications associated with the instance
+            type. It passes hosts that can create the specified
+            instance type.</para>
+        </listitem>
+        <listitem>
+          <para>The extra specifications can have a scope at the
+            beginning of the key string of a key/value pair. The scope
+            format is scope:key and can be nested, i.e. key_string :=
+            scope:key_string. Example like capabilities:cpu_info:
+            features is valid scope format. A key string without any :
+            is non-scope format. Each filter defines it’s valid scope,
+            and not all filters accept non-scope format.</para>
+        </listitem>
+        <listitem>
+          <para>The extra specifications can have an operator at the
+            beginning of the value string of a key/value pair. If
+            there is no operator specified, then a default operator of
+            s== is used. Valid operators are:</para>
+        </listitem>
+      </itemizedlist>
+      <para>* = (equal to or greater than as a number; same as vcpus
+        case)* == (equal to as a number)* != (not equal to as a
+        number)* &gt;= (greater than or equal to as a number)* &lt;=
+        (less than or equal to as a number)* s== (equal to as a
+        string)* s!= (not equal to as a string)* s&gt;= (greater than
+        or equal to as a string)* s&gt; (greater than as a string)*
+        s&lt;= (less than or equal to as a string)* s&lt; (less than
+        as a string)* &lt;in&gt; (substring)* &lt;or&gt; (find one of
+        these)Examples are: "&gt;= 5", "s== 2.1.0", "&lt;in&gt; gcc",
+        and "&lt;or&gt; fpu &lt;or&gt; gpu"</para>
+      <programlisting>class RamFilter(filters.BaseHostFilter):
+  """Ram Filter with over subscription flag""" 
+  
+  def host_passes(self, host_state, filter_properties): 
+  """Only return hosts with sufficient available RAM.""" 
+
+    instance_type = filter_properties.get('instance_type') 
+    requested_ram = instance_type['memory_mb'] 
+    free_ram_mb = host_state.free_ram_mb 
+    total_usable_ram_mb = host_state.total_usable_ram_mb 
+    used_ram_mb = total_usable_ram_mb - free_ram_mb 
+    return total_usable_ram_mb * FLAGS.ram_allocation_ratio - used_ram_mb >= requested_ram</programlisting>
+      <para>Here ram_allocation_ratio means the virtual RAM to
+        physical RAM allocation ratio (it is 1.5 by default). Really,
+        nice and simple.</para>
+      <para>Next standard filter to describe is AvailabilityZoneFilter
+        and it isn’t difficult too. This filter just looks at the
+        availability zone of compute node and availability zone from
+        the properties of the request. Each compute service has its
+        own availability zone. So deployment engineers have an option
+        to run scheduler with availability zones support and can
+        configure availability zones on each compute host. This
+        classes method host_passes returns True if availability zone
+        mentioned in request is the same on the current compute
+        host.</para>
+      <para>The ImagePropertiesFilter filters hosts based on the
+        architecture, hypervisor type, and virtual machine mode
+        specified in the instance. E.g., an instance might require a
+        host that supports the arm architecture on a qemu compute
+        host. The ImagePropertiesFilter will only pass hosts that can
+        satisfy this request. These instance properties are populated
+        from properties define on the instance’s image. E.g. an image
+        can be decorated with these properties using glance
+        image-update img-uuid --property architecture=arm --property
+        hypervisor_type=qemu Only hosts that satisfy these
+        requirements will pass the ImagePropertiesFilter.</para>
+      <para>ComputeCapabilitiesFilter checks if the host satisfies any
+        extra_specs specified on the instance type. The extra_specs
+        can contain key/value pairs. The key for the filter is either
+        non-scope format (i.e. no : contained), or scope format in
+        capabilities scope (i.e. capabilities:xxx:yyy). One example of
+        capabilities scope is capabilities:cpu_info:features, which
+        will match host’s cpu features capabilities. The
+        ComputeCapabilitiesFilter will only pass hosts whose
+        capabilities satisfy the requested specifications. All hosts
+        are passed if no extra_specs are specified.</para>
+      <para>ComputeFilter is quite simple and passes any host whose
+        compute service is enabled and operational.</para>
+      <para>Now we are going to IsolatedHostsFilter. There can be some
+        special hosts reserved for specific images. These hosts are
+        called isolated. So the images to run on the isolated hosts
+        are also called isolated. This Scheduler checks if
+        image_isolated flag named in instance specifications is the
+        same that the host has.</para>
+    
+  
+  
+    <para><guilabel>Weights</guilabel></para>
+    <para>Filter Scheduler uses so-called weightsduring its
+      work.</para>
+    <para>The Filter Scheduler weights hosts based on the config
+      option scheduler_weight_classes, this defaults to
+      nova.scheduler.weights.all_weighers, which selects the only
+      weigher available – the RamWeigher. Hosts are then weighted and
+      sorted with the largest weight winning.</para>
+    <para>Filter Scheduler finds local list of acceptable hosts by
+      repeated filtering and weighing. Each time it chooses a host, it
+      virtually consumes resources on it, so subsequent selections can
+      adjust accordingly. It is useful if the customer asks for the
+      some large amount of instances, because weight is computed for
+      each instance requested.</para>
+  <figure>
+    <title>Weights</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image07.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+    <para>In the end Filter Scheduler sorts selected hosts by their
+      weight and provisions instances on them.</para>
 </chapter>

doc/training-guide/module001-ch010-vm-provisioning-indepth.xml

@@ -6,4 +6,117 @@
   xml:id="module001-ch010-vm-provisioning-indepth">
   <title>VM Provisioning Indepth</title>
   <para>More Content To be Added ...</para>
+  <para>The request flow for provisioning an Instance goes like
+    this:</para>
+  <orderedlist>
+    <listitem>
+      <para>Dashboard or CLI gets the user credentials authenticates
+        with Keystone via REST api.</para>
+    </listitem>
+  </orderedlist>
+  <para>Keystone authenticate the credentials and generate &amp; send
+    back auth-token which will be used for sending request to other
+    Components through REST-call.</para>
+  <orderedlist>
+    <listitem>
+      <para>Dashboard or CLI convert the new instance request
+        specified in ‘launch instance’ or ‘nova-boot’ form to REST
+        API request and send it to nova-api.</para>
+    </listitem>
+    <listitem>
+      <para>nova-api receive the request and sends the request for
+        validation auth-token and access permission to
+        keystone.</para>
+    </listitem>
+  </orderedlist>
+  <para>Keystone validates the token and sends updated auth headers
+    with roles and permissions.</para>
+  <orderedlist>
+    <listitem>
+      <para>nova-api interacts with nova-database.</para>
+    </listitem>
+  </orderedlist>
+  <para>Creates initial db entry for new instance.</para>
+  <orderedlist>
+    <listitem>
+      <para>nova-api sends the rpc.call request to nova-scheduler
+        excepting to get updated instance entry with host ID
+        specified.</para>
+    </listitem>
+    <listitem>
+      <para>nova-scheduler picks the request from the queue.</para>
+    </listitem>
+    <listitem>
+      <para>nova-scheduler interacts with nova-database to find an
+        appropriate host via filtering and weighing.</para>
+    </listitem>
+  </orderedlist>
+  <para>Returns the updated instance entry with appropriate host ID
+    after filtering and weighing.</para>
+  <para>nova-scheduler sends the rpc.cast request to nova-compute for
+    ‘launching instance’ on appropriate host .</para>
+  <orderedlist>
+    <listitem>
+      <para>nova-compute picks the request from the queue.</para>
+    </listitem>
+    <listitem>
+      <para>nova-compute send the rpc.call request to nova-conductor
+        to fetch the instance information such as host ID and flavor(
+        Ram , CPU ,Disk).</para>
+    </listitem>
+    <listitem>
+      <para>nova-conductor picks the request from the queue.</para>
+    </listitem>
+    <listitem>
+      <para>nova-conductor interacts with nova-database.</para>
+    </listitem>
+  </orderedlist>
+  <para>Return the instance information.</para>
+  <para>nova-compute picks the instance information from the
+    queue.</para>
+  <orderedlist>
+    <listitem>
+      <para>nova-compute does the REST call by passing auth-token to
+        glance-api to get the Image URI by Image ID from glance and
+        upload image from image storage.</para>
+    </listitem>
+    <listitem>
+      <para>glance-api validates the auth-token with keystone. </para>
+    </listitem>
+  </orderedlist>
+  <para>nova-compute get the image metadata.</para>
+  <para>nova-compute does the REST-call by passing auth-token to
+    Network API to allocate and configure the network such that
+    instance gets the IP address. </para>
+  <orderedlist>
+    <listitem>
+      <para>quantum-server validates the auth-token with
+        keystone.</para>
+    </listitem>
+  </orderedlist>
+  <para>nova-compute get the network info.</para>
+  <orderedlist>
+    <listitem>
+      <para>nova-compute does the REST call by passing auth-token to
+        Volume API to attach volumes to instance.</para>
+    </listitem>
+    <listitem>
+      <para>cinder-api validates the auth-token with keystone.</para>
+    </listitem>
+  </orderedlist>
+  <para>nova-compute gets the block storage info.</para>
+  <orderedlist>
+    <listitem>
+      <para>nova-compute generates data for hypervisor driver and
+        executes request on Hypervisor( via libvirt or api).</para>
+    </listitem>
+  </orderedlist>
+  <figure>
+    <title>Nova VM Provisioning</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="figures/image02.png"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
 </chapter>

doc/training-guide/module001-ch011-block-storage.xml

@@ -1,9 +1,251 @@
 <?xml version="1.0" encoding="utf-8"?>
 <chapter xmlns="http://docbook.org/ns/docbook"
   xmlns:xi="http://www.w3.org/2001/XInclude"
-  xmlns:xlink="http://www.w3.org/1999/xlink"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- version="5.0"
   xml:id="module001-ch011-block-storage">
   <title>OpenStack Block Storage</title>
-  <para>To be Added</para>
+  <para><emphasis role="bold">Block Storage and OpenStack
-</chapter>
+      Compute</emphasis></para>
+  <para>OpenStack provides two classes of block storage, "ephemeral"
+    storage and persistent "volumes". Ephemeral storage exists only
+    for the life of an instance, it will persist across reboots of the
+    guest operating system but when the instance is deleted so is the
+    associated storage. All instances have some ephemeral storage.
+    Volumes are persistent virtualized block devices independent of
+    any particular instance. Volumes may be attached to a single
+    instance at a time, but may be detached or reattached to a
+    different instance while retaining all data, much like a USB
+    drive.</para>
+  <para><guilabel>Ephemeral Storage</guilabel></para>
+  <para>Ephemeral storage is associated with a single unique instance.
+    Its size is defined by the flavor of the instance.</para>
+  <para>Data on ephemeral storage ceases to exist when the instance it
+    is associated with is terminated. Rebooting the VM or restarting
+    the host server, however, will not destroy ephemeral data. In the
+    typical use case an instance's root filesystem is stored on
+    ephemeral storage. This is often an unpleasant surprise for people
+    unfamiliar with the cloud model of computing.</para>
+  <para>In addition to the ephemeral root volume all flavors except
+    the smallest, m1.tiny, provide an additional ephemeral block
+    device varying from 20G for the m1.small through 160G for the
+    m1.xlarge by default - these sizes are configurable. This is
+    presented as a raw block device with no partition table or
+    filesystem. Cloud aware operating system images may discover,
+    format, and mount this device. For example the cloud-init package
+    included in Ubuntu's stock cloud images will format this space as
+    an ext3 filesystem and mount it on /mnt. It is important to note
+    this a feature of the guest operating system. OpenStack only
+    provisions the raw storage.</para>
+  <para><guilabel>Volume Storage</guilabel></para>
+  <para>Volume storage is independent of any particular instance and
+    is persistent. Volumes are user created and within quota and
+    availability limits may be of any arbitrary size.</para>
+  <para>When first created volumes are raw block devices with no
+    partition table and no filesystem. They must be attached to an
+    instance to be partitioned and/or formatted. Once this is done
+    they may be used much like an external disk drive. Volumes may
+    attached to only one instance at a time, but may be detached and
+    reattached to either the same or different instances.</para>
+  <para>It is possible to configure a volume so that it is bootable
+    and provides a persistent virtual instance similar to traditional
+    non-cloud based virtualization systems. In this use case the
+    resulting instance may still have ephemeral storage depending on
+    the flavor selected, but the root filesystem (and possibly others)
+    will be on the persistent volume and thus state will be maintained
+    even if the instance it shutdown. Details of this configuration
+    are discussed in the<link
+      xlink:href="http://docs.openstack.org/cli/quick-start/content/"
+      /><link
+      xlink:href="http://docs.openstack.org/cli/quick-start/content/"
+      >OpenStack Clients Guide</link>.</para>
+  <para>Volumes do not provide concurrent access from multiple
+    instances. For that you need either a traditional network
+    filesystem like NFS or CIFS or a cluster filesystem such as
+    GlusterFS. These may be built within an OpenStack cluster or
+    provisioned outside of it, but are not features provided by the
+    OpenStack software.</para>
+  <para>The OpenStack Block Storage service works via the interaction
+    of a series of daemon processes named cinder-* that reside
+    persistently on the host machine or machines. The binaries can all
+    be run from a single node, or spread across multiple nodes. They
+    can also be run on the same node as other OpenStack
+    services.</para>
+  <para><guilabel>The current services available in OpenStack Block
+      Storage are:</guilabel></para>
+  <itemizedlist>
+    <listitem>
+      <para><emphasis role="bold">cinder-api</emphasis> - The
+        cinder-api service is a WSGI app that authenticates and routes
+        requests throughout the Block Storage system. It supports the
+        OpenStack API's only, although there is a translation that can
+        be done via Nova's EC2 interface which calls in to the
+        cinderclient.</para>
+    </listitem>
+  </itemizedlist>
+  <itemizedlist>
+    <listitem>
+      <para><emphasis role="bold">cinder-scheduler</emphasis> - The
+        cinder-scheduler is responsible for scheduling/routing
+        requests to the appropriate volume service. As of Grizzly;
+        depending upon your configuration this may be simple
+        round-robin scheduling to the running volume services, or it
+        can be more sophisticated through the use of the Filter
+        Scheduler. The Filter Scheduler is the default in Grizzly and
+        enables filter on things like Capacity, Availability Zone,
+        Volume Types and Capabilities as well as custom
+        filters.</para>
+    </listitem>
+  </itemizedlist>
+  <itemizedlist>
+    <listitem>
+      <para><emphasis role="bold">cinder-volume</emphasis> - The
+        cinder-volume service is responsible for managing Block
+        Storage devices, specifically the back-end devices
+        themselves.</para>
+    </listitem>
+  </itemizedlist>
+  <itemizedlist>
+    <listitem>
+      <para><emphasis role="bold">cinder-backup</emphasis> - The
+        cinder-backup service provides a means to back up a Cinder
+        Volume to OpenStack Object Store (SWIFT).</para>
+    </listitem>
+  </itemizedlist>
+  <para><guilabel>Introduction to OpenStack Block
+    Storage</guilabel></para>
+  <para>OpenStack Block Storage provides persistent High Performance
+    Block Storage resources that can be consumed by OpenStack Compute
+    instances. This includes secondary attached storage similar to
+    Amazon's Elastic Block Storage (EBS). In addition images can be
+    written to a Block Storage device and specified for OpenStack
+    Compute to use a bootable persistent instance.</para>
+  <para>There are some differences from Amazon's EBS that one should
+    be aware of. OpenStack Block Storage is not a shared storage
+    solution like NFS, but currently is designed so that the device is
+    attached and in use by a single instance at a time.</para>
+  <para><guilabel>Backend Storage Devices</guilabel></para>
+  <para>OpenStack Block Storage requires some form of back-end storage
+    that the service is built on. The default implementation is to use
+    LVM on a local Volume Group named "cinder-volumes". In addition to
+    the base driver implementation, OpenStack Block Storage also
+    provides the means to add support for other storage devices to be
+    utilized such as external Raid Arrays or other Storage
+    appliances.</para>
+  <para><guilabel>Users and Tenants (Projects)</guilabel></para>
+  <para>The OpenStack Block Storage system is designed to be used by
+    many different cloud computing consumers or customers, basically
+    tenants on a shared system, using role-based access assignments.
+    Roles control the actions that a user is allowed to perform. In
+    the default configuration, most actions do not require a
+    particular role, but this is configurable by the system
+    administrator editing the appropriate policy.json file that
+    maintains the rules. A user's access to particular volumes is
+    limited by tenant, but the username and password are assigned per
+    user. Key pairs granting access to a volume are enabled per user,
+    but quotas to control resource consumption across available
+    hardware resources are per tenant.</para>
+  <para><guilabel>For tenants, quota controls are available to limit
+      the:</guilabel></para>
+  <itemizedlist>
+    <listitem>
+      <para>Number of volumes which may be created</para>
+    </listitem>
+    <listitem>
+      <para>Number of snapshots which may be created</para>
+    </listitem>
+    <listitem>
+      <para>Total number of Giga Bytes allowed per tenant (shared
+          between snapshots and volumes)</para>
+    </listitem>
+  </itemizedlist>
+  <para><guilabel>Volumes Snapshots and Backups</guilabel></para>
+  <para>This introduction provides a high level overview of the two
+    basic resources offered by the OpenStack Block Storage service.
+    The first is Volumes and the second is Snapshots which are derived
+    from Volumes.</para>
+  <para><guilabel>Volumes</guilabel></para>
+  <para>Volumes are allocated block storage resources that can be
+    attached to instances as secondary storage or they can be used as
+    the root store to boot instances. Volumes are persistent R/W Block
+    Storage devices most commonly attached to the Compute node via
+    iSCSI.</para>
+  <para><guilabel>Snapshots</guilabel></para>
+  <para>A Snapshot in OpenStack Block Storage is a read-only point in
+    time copy of a Volume. The Snapshot can be created from a Volume
+    that is currently in use (via the use of '--force True') or in an
+    available state. The Snapshot can then be used to create a new
+    volume via create from snapshot.</para>
+  <para><guilabel>Backups</guilabel></para>
+  <para>A Backup is an archived copy of a Volume currently stored in
+    Object Storage (Swift).</para>
+  <para><guilabel>Managing Volumes</guilabel></para>
+  <para>Cinder is the OpenStack service that allows you to give extra
+    block level storage to your OpenStack Compute instances. You may
+    recognize this as a similar offering from Amazon EC2 known as
+    Elastic Block Storage (EBS). The default Cinder implementation is
+    an iSCSI solution that employs the use of Logical Volume Manager
+    (LVM) for Linux. Note that a volume may only be attached to one
+    instance at a time. This is not a ‘shared storage’ solution like a
+    SAN of NFS on which multiple servers can attach to. It's also
+    important to note that Cinder also includes a number of drivers to
+    allow you to use a number of other vendor's back-end storage
+    devices in addition to or instead of the base LVM
+    implementation.</para>
+  <para>Here is brief walk-through of a simple create/attach sequence,
+    keep in mind this requires proper configuration of both OpenStack
+    Compute via cinder.conf and OpenStack Block Storage via
+    cinder.conf.</para>
+  <orderedlist>
+    <listitem>
+      <para>The volume is created via cinder create; which creates
+          an LV into the volume group (VG) "cinder-volumes"</para>
+    </listitem>
+    <listitem>
+      <para>The volume is attached to an instance via nova
+          volume-attach; which creates a unique iSCSI IQN that will be
+          exposed to the compute node</para>
+    </listitem>
+    <listitem>
+      <para>The compute node which run the concerned instance has
+          now an active ISCSI session; and a new local storage
+          (usually a /dev/sdX disk)</para>
+    </listitem>
+    <listitem>
+      <para>libvirt uses that local storage as a storage for the
+          instance; the instance get a new disk (usually a /dev/vdX
+          disk)</para>
+    </listitem>
+  </orderedlist>
+  <para><guilabel>Block Storage Capabilities</guilabel></para>
+  <itemizedlist>
+    <listitem>
+      <para>OpenStack provides persistent block level storage
+          devices for use with OpenStack compute instances.</para>
+    </listitem>
+    <listitem>
+      <para>The block storage system manages the creation, attaching
+          and detaching of the block devices to servers. Block storage
+          volumes are fully integrated into OpenStack Compute and the
+          Dashboard allowing for cloud users to manage their own
+          storage needs.</para>
+    </listitem>
+    <listitem>
+      <para>In addition to using simple Linux server storage, it has
+          unified storage support for numerous storage platforms
+          including Ceph, NetApp, Nexenta, SolidFire, and
+          Zadara.</para>
+    </listitem>
+    <listitem>
+      <para>Block storage is appropriate for performance sensitive
+          scenarios such as database storage, expandable file systems,
+          or providing a server with access to raw block level
+          storage.</para>
+    </listitem>
+    <listitem>
+      <para>Snapshot management provides powerful functionality for
+          backing up data stored on block storage volumes. Snapshots
+          can be restored or used to create a new block storage
+          volume.</para>
+    </listitem>
+  </itemizedlist>
+</chapter>

doc/training-guide/module001-ch011-vm-provisioning-indepth.xml

@@ -1,9 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<chapter xmlns="http://docbook.org/ns/docbook"
-  xmlns:xi="http://www.w3.org/2001/XInclude"
-  xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0"
-  xml:id="module001-ch010-vm-provisioning-indepth">
-  <title>VM Provisioning Indepth</title>
-  <para>More Content TO be Added ...</para>
-</chapter>

doc/training-guide/module001-intro-openstack.xml

@@ -14,4 +14,4 @@
   <xi:include href="module001-ch009-vm-placement.xml"/>
   <xi:include href="module001-ch010-vm-provisioning-indepth.xml"/>
   <xi:include href="module001-ch011-block-storage.xml"/>
-</book>
+</book>

doc/training-guide/module002-ch000-openstack-networking.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<book xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:svg="http://www.w3.org/2000/svg"
+    xmlns:html="http://www.w3.org/1999/xhtml"
+    version="5.0"
+    xml:id="module002-ch000-openstack-networking">
+    <title>Networking in OpenStack</title>
+    <xi:include href="module002-ch001-networking-in-openstack.xml"/>
+    <xi:include href="module002-ch002-openstack-networking-concepts.xml"/>
+    <xi:include href="module002-ch003-neutron-use-cases.xml"/>
+    <xi:include href="module002-ch004-security-in-neutron.xml"/>
+    <xi:include href="module002-ch005-floating-ips.xml"/>
+</book>

doc/training-guide/module002-ch001-networking-in-openstack.xml

@@ -0,0 +1,269 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module002-ch001-networking-in-openstack">
+    <title>Networking in OpenStack</title>
+    <para><guilabel>Networking in OpenStack</guilabel></para>
+        <para>OpenStack Networking provides a rich tenant-facing API
+            for defining network connectivity and addressing in the
+            cloud. The OpenStack Networking project gives operators
+            the ability to leverage different networking technologies
+            to power their cloud networking. It is a virtual network
+            service that provides a powerful API to define the network
+            connectivity and addressing used by devices from other
+            services, such as OpenStack Compute. It has a rich API
+            which consists of the following components.</para>
+        <itemizedlist>
+            <listitem>
+                <para><emphasis role="bold">Network:</emphasis> An
+                isolated L2 segment, analogous to VLAN in the physical
+                networking world.</para>
+            </listitem>
+            <listitem>
+                <para><emphasis role="bold">Subnet:</emphasis> A block
+                of v4 or v6 IP addresses and associated configuration
+                state.</para>
+            </listitem>
+            <listitem>
+                <para><emphasis role="bold">Port:</emphasis> A
+                connection point for attaching a single device, such
+                as the NIC of a virtual server, to a virtual network.
+                Also describes the associated network configuration,
+                such as the MAC and IP addresses to be used on that
+                port. </para>
+            </listitem>
+        </itemizedlist>
+        <para>You can configure rich network topologies by creating
+            and configuring networks and subnets, and then instructing
+            other OpenStack services like OpenStack Compute to attach
+            virtual devices to ports on these networks. In
+            particular, OpenStack Networking supports each tenant
+            having multiple private networks, and allows tenants to
+            choose their own IP addressing scheme, even if those IP
+            addresses overlap with those used by other tenants. This
+            enables very advanced cloud networking use cases, such as
+            building multi-tiered web applications and allowing
+            applications to be migrated to the cloud without changing
+            IP addresses.</para>
+    <para><guilabel>Plugin Architecture: Flexibility to Choose
+            Different Network Technologies</guilabel></para>
+    <para>Enhancing traditional networking solutions to provide rich
+        cloud networking is challenging. Traditional networking is not
+        designed to scale to cloud proportions or to configure
+        automatically.</para>
+    <para>The original OpenStack Compute network implementation
+        assumed a very basic model of performing all isolation through
+        Linux VLANs and IP tables. OpenStack Networking introduces the
+        concept of a plugin, which is a pluggable back-end
+        implementation of the OpenStack Networking API. A plugin can
+        use a variety of technologies to implement the logical API
+        requests. Some OpenStack Networking plugins might use basic
+        Linux VLANs and IP tables, while others might use more
+        advanced technologies, such as L2-in-L3 tunneling or OpenFlow,
+        to provide similar benefits.</para>
+    <para>The current set of plugins include:</para>
+    <itemizedlist>
+        <listitem>
+            <para><emphasis role="bold">Open vSwitch:</emphasis>
+                Documentation included in this guide.</para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Cisco:</emphasis> Documented
+                externally at: <link
+                    xlink:href="http://wiki.openstack.org/cisco-quantum"
+                    >http://wiki.openstack.org/cisco-quantum</link></para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Linux Bridge:</emphasis>
+                Documentation included in this guide and <link
+                    xlink:href="http://wiki.openstack.org/Quantum-Linux-Bridge-Plugin"
+                    >http://wiki.openstack.org/Quantum-Linux-Bridge-Plugin</link>
+            </para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Nicira NVP:</emphasis>
+                Documentation include in this guide, <link
+                    xlink:href="http://www.vmware.com/products/datacenter-virtualization/nicira.html"
+                    >NVP Product Overview </link>, and <link
+                    xlink:href="http://www.nicira.com/support">NVP
+                    Product Support</link>.</para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Ryu:</emphasis>
+                <link
+                    xlink:href="https://github.com/osrg/ryu/wiki/OpenStack"
+                    >https://github.com/osrg/ryu/wiki/OpenStack</link></para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">NEC OpenFlow:</emphasis>
+                <link
+                    xlink:href="http://wiki.openstack.org/Quantum-NEC-OpenFlow-Plugin"
+                    >http://wiki.openstack.org/Quantum-NEC-OpenFlow-Plugin</link></para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Big Switch, Floodlight REST
+                    Proxy:</emphasis>
+                <link
+                    xlink:href="http://www.openflowhub.org/display/floodlightcontroller/Quantum+REST+Proxy+Plugin"
+                    >http://www.openflowhub.org/display/floodlightcontroller/Quantum+REST+Proxy+Plugin</link></para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">PLUMgrid:</emphasis>
+                <link
+                    xlink:href="https://wiki.openstack.org/wiki/Plumgrid-quantum"
+                    >https://wiki.openstack.org/wiki/Plumgrid-quantum</link></para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Hyper-V
+                Plugin</emphasis></para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Brocade
+                Plugin</emphasis></para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Midonet
+                Plugin</emphasis></para>
+        </listitem>
+    </itemizedlist>
+    <para>Plugins can have different properties in terms of hardware
+        requirements, features, performance, scale, operator tools,
+        etc. Supporting many plugins enables the cloud administrator
+        to weigh different options and decide which networking
+        technology is right for the deployment.</para>
+    <para>Components of OpenStack Networking</para>
+    <para>To deploy OpenStack Networking, it is useful to understand
+        the different components that make up the solution and how
+        those components interact with each other and with other
+        OpenStack services.</para>
+    <para>OpenStack Networking is a standalone service, just like
+        other OpenStack services such as OpenStack Compute, OpenStack
+        Image service, OpenStack Identity service, and the OpenStack
+        Dashboard. Like those services, a deployment of OpenStack
+        Networking often involves deploying several processes on a
+        variety of hosts.</para>
+    <para>The main process of the OpenStack Networking server is
+        quantum-server, which is a Python daemon that exposes the
+        OpenStack Networking API and passes user requests to the
+        configured OpenStack Networking plugin for additional
+        processing. Typically, the plugin requires access to a
+        database for persistent storage, similar to other OpenStack
+        services.</para>
+    <para>If your deployment uses a controller host to run centralized
+        OpenStack Compute components, you can deploy the OpenStack
+        Networking server on that same host. However, OpenStack
+        Networking is entirely standalone and can be deployed on its
+        own server as well. OpenStack Networking also includes
+        additional agents that might be required depending on your
+        deployment:</para>
+    <itemizedlist>
+        <listitem>
+            <para><emphasis role="bold">plugin agent
+                    (quantum-*-agent):</emphasis>Runs on each
+                hypervisor to perform local vswitch configuration.
+                Agent to be run depends on which plugin you are using,
+                as some plugins do not require an agent.</para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">dhcp agent
+                    (quantum-dhcp-agent):</emphasis>Provides DHCP
+                services to tenant networks. This agent is the same
+                across all plugins.</para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">l3 agent
+                    (quantum-l3-agent):</emphasis>Provides L3/NAT
+                forwarding to provide external network access for VMs
+                on tenant networks. This agent is the same across all
+                plugins.</para>
+        </listitem>
+    </itemizedlist>
+    <para>These agents interact with the main quantum-server process
+        in the following ways:</para>
+    <itemizedlist>
+        <listitem>
+            <para>Through RPC. For example, rabbitmq or qpid.</para>
+        </listitem>
+        <listitem>
+            <para>Through the standard OpenStack Networking
+                API.</para>
+        </listitem>
+    </itemizedlist>
+    <para>OpenStack Networking relies on the OpenStack Identity
+        Project (Keystone) for authentication and authorization of all
+        API request.  </para>
+    <para>OpenStack Compute interacts with OpenStack Networking
+        through calls to its standard API. As part of creating a VM,
+        nova-compute communicates with the OpenStack Networking API to
+        plug each virtual NIC on the VM into a particular
+        network.</para>
+    <para>The OpenStack Dashboard (Horizon) has integration with the
+        OpenStack Networking API, allowing administrators and tenant
+        users, to create and manage network services through the
+        Horizon GUI.</para>
+    <para><emphasis role="bold">Place Services on Physical
+            Hosts</emphasis></para>
+    <para>Like other OpenStack services, OpenStack Networking provides
+        cloud administrators with significant flexibility in deciding
+        which individual services should run on which physical
+        devices. On one extreme, all service daemons can be run on a
+        single physical host for evaluation purposes. On the other,
+        each service could have its own physical hosts, and some cases
+        be replicated across multiple hosts for redundancy.</para>
+    <para>In this guide, we focus primarily on a standard architecture
+        that includes a “cloud controller” host, a “network gateway”
+        host, and a set of hypervisors for running VMs. The "cloud
+        controller" and "network gateway" can be combined in simple
+        deployments, though if you expect VMs to send significant
+        amounts of traffic to or from the Internet, a dedicated
+        network gateway host is suggested to avoid potential CPU
+        contention between packet forwarding performed by the
+        quantum-l3-agent and other OpenStack services.</para>
+    <para><emphasis role="bold">Network Connectivity for Physical
+            Hosts</emphasis></para>
+    <figure>
+        <title>Network Diagram</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image33.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+    <para>A standard OpenStack Networking setup has up to four
+        distinct physical data center networks:</para>
+    <itemizedlist>
+        <listitem>
+            <para><emphasis role="bold">Management
+                network:</emphasis>Used for internal communication
+                between OpenStack Components. The IP addresses on this
+                network should be reachable only within the data
+                center. </para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Data network:</emphasis>Used
+                for VM data communication within the cloud deployment.
+                The IP addressing requirements of this network depend
+                on the OpenStack Networking plugin in use. </para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">External
+                network:</emphasis>Used to provide VMs with Internet
+                access in some deployment scenarios. The IP addresses
+                on this network should be reachable by anyone on the
+                Internet. </para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">API network:</emphasis>Exposes
+                all OpenStack APIs, including the OpenStack Networking
+                API, to tenants. The IP addresses on this network
+                should be reachable by anyone on the Internet. This
+                may be the same network as the external network, as it
+                is possible to create a subnet for the external
+                network that uses IP allocation ranges to use only
+                less than the full range of IP addresses in an IP
+                block.</para>
+        </listitem>
+    </itemizedlist>
+</chapter>

doc/training-guide/module002-ch002-openstack-networking-concepts.xml

@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module002-ch002-openstack-networking-concepts">
+    <title>OpenStack Networking Concepts</title>
+    <para><emphasis role="bold">Network Types</emphasis></para>
+    <para>The OpenStack Networking configuration provided by the
+        Rackspace Private Cloud cookbooks allows you to choose between
+        VLAN or GRE isolated networks, both provider- and
+        tenant-specific. From the provider side, an administrator can
+        also create a flat network.</para>
+    <para>The type of network that is used for private tenant networks
+        is determined by the network_type attribute, which can be
+        edited in the Chef override_attributes. This attribute sets
+        both the default provider network type and the only type of
+        network that tenants are able to create. Administrators can
+        always create flat and VLAN networks. GRE networks of any type
+        require the network_type to be set to gre.</para>
+    <para><emphasis role="bold">Namespaces</emphasis></para>
+    <para>For each network you create, the Network node (or Controller
+        node, if combined) will have a unique network namespace
+        (netns) created by the DHCP and Metadata agents. The netns
+        hosts an interface and IP addresses for dnsmasq and the
+        quantum-ns-metadata-proxy. You can view the namespaces with
+        the ip netns [list], and can interact with the namespaces with
+        the ip netns exec &lt;namespace&gt; &lt;command&gt;
+        command.</para>
+    <para><emphasis role="bold">Metadata</emphasis></para>
+    <para>Not all networks or VMs need metadata access. Rackspace
+        recommends that you use metadata if you are using a single
+        network. If you need metadata, you may also need a default
+        route. (If you don't need a default route, no-gateway will
+        do.)</para>
+    <para>To communicate with the metadata IP address inside the
+        namespace, instances need a route for the metadata network
+        that points to the dnsmasq IP address on the same namespaced
+        interface. OpenStack Networking only injects a route when you
+        do not specify a gateway-ip in the subnet.</para>
+    <para>If you need to use a default route and provide instances
+        with access to the metadata route, create the subnet without
+        specifying a gateway IP and with a static route from 0.0.0.0/0
+        to your gateway IP address. Adjust the DHCP allocation pool so
+        that it will not assign the gateway IP. With this
+        configuration, dnsmasq will pass both routes to instances.
+        This way, metadata will be routed correctly without any
+        changes on the external gateway.</para>
+    <para><emphasis role="bold">OVS Bridges</emphasis></para>
+    <para>An OVS bridge for provider traffic is created and configured
+        on the nodes where single-network-node and single-compute are
+        applied. Bridges are created, but physical interfaces are not
+        added. An OVS bridge is not created on a Controller-only
+        node.</para>
+    <para>When creating networks, you can specify the type and
+        properties, such as Flat vs. VLAN, Shared vs. Tenant, or
+        Provider vs. Overlay. These properties identify and determine
+        the behavior and resources of instances attached to the
+        network. The cookbooks will create bridges for the
+        configuration that you specify, although they do not add
+        physical interfaces to provider bridges. For example, if you
+        specify a network type of GRE, a br-tun tunnel bridge will be
+        created to handle overlay traffic.</para>
+</chapter>

doc/training-guide/module002-ch003-neutron-use-cases.xml

@@ -0,0 +1,131 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module002-ch003-neutron-use-cases">
+    <title>Neutron Use Cases</title>
+    <para>As of now you must be wondering, how to use these awesome
+        features that OpenStack Networking has given to us. </para>
+        <para><guilabel><anchor xml:id="h.lrsgdytf1mh5"/>Use Case: Single Flat
+            Network</guilabel></para>
+        <para>In the simplest use case, a single OpenStack Networking
+            network exists. This is a "shared" network, meaning it is
+            visible to all tenants via the OpenStack Networking API.
+            Tenant VMs have a single NIC, and receive a fixed IP
+            address from the subnet(s) associated with that network.
+            This essentially maps to the FlatManager and
+            FlatDHCPManager models provided by OpenStack Compute.
+            Floating IPs are not supported.</para>
+        <para>It is common that such an OpenStack Networking network
+            is a "provider network", meaning it was created by the
+            OpenStack administrator to map directly to an existing
+            physical network in the data center. This allows the
+            provider to use a physical router on that data center
+            network as the gateway for VMs to reach the outside world.
+            For each subnet on an external network, the gateway
+            configuration on the physical router must be manually
+            configured outside of OpenStack.</para>
+    <figure>
+        <title>Single Flat Network</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image34.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+        <para><guilabel>Use Case: Multiple Flat
+        Network</guilabel></para>
+        <para>This use case is very similar to the above Single Flat
+            Network use case, except that tenants see multiple shared
+            networks via the OpenStack Networking API and can choose
+            which network (or networks) to plug into.</para>
+    <figure>
+        <title>Multiple Flat Network</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image35.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+        <para><guilabel>Use Case: Mixed Flat and Private
+            Network</guilabel></para>
+        <para>This use case is an extension of the above flat network
+            use cases, in which tenants also optionally have access to
+            private per-tenant networks. In addition to seeing one or
+            more shared networks via the OpenStack Networking API,
+            tenants can create additional networks that are only
+            visible to users of that tenant. When creating VMs, those
+            VMs can have NICs on any of the shared networks and/or any
+            of the private networks belonging to the tenant. This
+            enables the creation of "multi-tier" topologies using VMs
+            with multiple NICs. It also supports a model where a VM
+            acting as a gateway can provide services such as routing,
+            NAT, or load balancing.</para>
+    <figure>
+        <title>Mixed Flat and Private Network</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image36.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+        <para><guilabel>Use Case: Provider Router with Private
+            Networks</guilabel></para>
+        <para>This use provides each tenant with one or more private
+            networks, which connect to the outside world via an
+            OpenStack Networking router. The case where each tenant
+            gets exactly one network in this form maps to the same
+            logical topology as the VlanManager in OpenStack Compute
+            (of course, OpenStack Networking doesn't require VLANs).
+            Using the OpenStack Networking API, the tenant would only
+            see a network for each private network assigned to that
+            tenant. The router object in the API is created and owned
+            by the cloud admin.</para>
+        <para>This model supports giving VMs public addresses using
+            "floating IPs", in which the router maps public addresses
+            from the external network to fixed IPs on private
+            networks. Hosts without floating IPs can still create
+            outbound connections to the external network, as the
+            provider router performs SNAT to the router's external IP.
+            The IP address of the physical router is used as the
+            gateway_ip of the external network subnet, so the provider
+            has a default router for Internet traffic.</para>
+        <para>The router provides L3 connectivity between private
+            networks, meaning that different tenants can reach each
+            others instances unless additional filtering (e.g.,
+            security groups) is used. Because there is only a single
+            router, tenant networks cannot use overlapping IPs. Thus,
+            it is likely that the admin would create the private
+            networks on behalf of tenants.</para>
+    <figure>
+        <title>Provider Router with Private Networks</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image37.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+        <para><guilabel>Use Case: Per-tenant Routers with Private
+            Networks</guilabel></para>
+        <para>A more advanced router scenario in which each tenant
+            gets at least one router, and potentially has access to
+            the OpenStack Networking API to create additional routers.
+            The tenant can create their own networks, potentially
+            uplinking those networks to a router. This model enables
+            tenant-defined multi-tier applications, with each tier
+            being a separate network behind the router. Since there
+            are multiple routers, tenant subnets can be overlapping
+            without conflicting, since access to external networks all
+            happens via SNAT or Floating IPs. Each router uplink and
+            floating IP is allocated from the external network
+            subnet.</para>
+    <figure>
+        <title>Per-tenant Routers with Private Networks</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image38.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+</chapter>

doc/training-guide/module002-ch004-security-in-neutron.xml

@@ -0,0 +1,140 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module002-ch004-security-in-neutron">
+    <title>Security in Neutron</title>
+    <para><guilabel>Security Groups</guilabel></para>
+    <para>Security groups and security group rules allows
+        administrators and tenants the ability to specify the type
+        of traffic and direction (ingress/egress) that is allowed
+        to pass through a port. A security group is a container
+        for security group rules.</para>
+    <para>When a port is created in OpenStack Networking it is
+        associated with a security group. If a security group is
+        not specified the port will be associated with a 'default'
+        security group. By default this group will drop all
+        ingress traffic and allow all egress. Rules can be added
+        to this group in order to change the behaviour.</para>
+    <para>If one desires to use the OpenStack Compute security
+        group APIs and/or have OpenStack Compute orchestrate the
+        creation of new ports for instances on specific security
+        groups, additional configuration is needed. To enable
+        this, one must configure the following file
+        /etc/nova/nova.conf and set the config option
+        security_group_api=neutron on every node running
+        nova-compute and nova-api. After this change is made
+        restart nova-api and nova-compute in order to pick up this
+        change. After this change is made one will be able to use
+        both the OpenStack Compute and OpenStack Network security
+        group API at the same time.</para> 
+    <para><guilabel>Authentication and Authorization</guilabel></para>
+    <para>OpenStack Networking uses the OpenStack Identity service
+        (project name keystone) as the default authentication
+        service. When OpenStack Identity is enabled Users
+        submitting requests to the OpenStack Networking service
+        must provide an authentication token in X-Auth-Token
+        request header. The aforementioned token should have been
+        obtained by authenticating with the OpenStack Identity
+        endpoint. For more information concerning authentication
+        with OpenStack Identity, please refer to the OpenStack
+        Identity documentation. When OpenStack Identity is
+        enabled, it is not mandatory to specify tenant_id for
+        resources in create requests, as the tenant identifier
+        will be derived from the Authentication token. Please note
+        that the default authorization settings only allow
+        administrative users to create resources on behalf of a
+        different tenant. OpenStack Networking uses information
+        received from OpenStack Identity to authorize user
+        requests. OpenStack Networking handles two kind of
+        authorization policies:</para>
+    <itemizedlist>
+        <listitem>
+            <para><emphasis role="bold">Operation-based:</emphasis>
+                policies specify access criteria for specific
+                operations, possibly with fine-grained control over
+                specific attributes;</para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold"
+                >Resource-based:</emphasis>whether access to specific
+                resource might be granted or not according to the
+                permissions configured for the resource (currently
+                available only for the network resource). The actual
+                authorization policies enforced in OpenStack
+                Networking might vary from deployment to
+                deployment.</para>
+        </listitem>
+    </itemizedlist>
+    <para>The policy engine reads entries from the policy.json
+        file. The actual location of this file might vary from
+        distribution to distribution. Entries can be updated while
+        the system is running, and no service restart is required.
+        That is to say, every time the policy file is updated, the
+        policies will be automatically reloaded. Currently the
+        only way of updating such policies is to edit the policy
+        file. Please note that in this section we will use both
+        the terms "policy" and "rule" to refer to objects which
+        are specified in the same way in the policy file; in other
+        words, there are no syntax differences between a rule and
+        a policy. We will define a policy something which is
+        matched directly from the OpenStack Networking policy
+        engine, whereas we will define a rule as the elements of
+        such policies which are then evaluated. For instance in
+        create_subnet: [["admin_or_network_owner"]], create_subnet
+        is regarded as a policy, whereas admin_or_network_owner is
+        regarded as a rule.</para>
+    <para>Policies are triggered by the OpenStack Networking
+        policy engine whenever one of them matches an OpenStack
+        Networking API operation or a specific attribute being
+        used in a given operation. For instance the create_subnet
+        policy is triggered every time a POST /v2.0/subnets
+        request is sent to the OpenStack Networking server; on the
+        other hand create_network:shared is triggered every time
+        the shared attribute is explicitly specified (and set to a
+        value different from its default) in a POST /v2.0/networks
+        request. It is also worth mentioning that policies can be
+        also related to specific API extensions; for instance
+        extension:provider_network:set will be triggered if the
+        attributes defined by the Provider Network extensions are
+        specified in an API request.</para>
+    <para>An authorization policy can be composed by one or more
+        rules. If more rules are specified, evaluation policy will
+        be successful if any of the rules evaluates successfully;
+        if an API operation matches multiple policies, then all
+        the policies must evaluate successfully. Also,
+        authorization rules are recursive. Once a rule is matched,
+        the rule(s) can be resolved to another rule, until a
+        terminal rule is reached.</para>
+    <para>The OpenStack Networking policy engine currently defines
+        the following kinds of terminal rules:</para>
+    <itemizedlist>
+        <listitem>
+            <para><emphasis role="bold">Role-based
+                rules:</emphasis> evaluate successfully if the
+                user submitting the request has the specified role.
+                For instance "role:admin"is successful if the user
+                submitting the request is an administrator.</para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Field-based
+                rules:</emphasis> evaluate successfully if a field
+                of the resource specified in the current request
+                matches a specific value. For instance
+                "field:networks:shared=True" is successful if the
+                attribute shared of the network resource is set to
+                true.</para>
+        </listitem>
+        <listitem>
+            <para><emphasis role="bold">Generic
+                rules:</emphasis>compare an attribute in the resource
+                with an attribute extracted from the user's security
+                credentials and evaluates successfully if the
+                comparison is successful. For instance
+                "tenant_id:%(tenant_id)s" is successful if the tenant
+                identifier in the resource is equal to the tenant
+                identifier of the user submitting the request.</para>
+        </listitem>
+    </itemizedlist>
+</chapter>

doc/training-guide/module002-ch005-floating-ips.xml

@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module002-ch004-floating-ips">
+    <title>Floating IP Addresses And Security Rules</title>
+    <para>OpenStack Networking has the concept of Fixed IPs and
+        Floating IPs. Fixed IPs are assigned to an instance on
+        creation and stay the same until the instance is explicitly
+        terminated. Floating ips are ip addresses that can be
+        dynamically associated with an instance. This address can be
+        disassociated and associated with another instance at any
+        time.</para>
+        <para>Various tasks carried out by Floating IP's as of
+        now.</para>
+        <itemizedlist>
+            <listitem>
+                <para>create IP ranges under a certain group, only
+                    available for admin role.</para>
+            </listitem>
+            <listitem>
+                <para>allocate an floating IP to a certain tenant,
+                    only available for admin role.</para>
+            </listitem>
+            <listitem>
+                <para>deallocate an floating IP from a certain
+                    tenant</para>
+            </listitem>
+            <listitem>
+                <para>associate an floating IP to a given
+                    instance</para>
+            </listitem>
+            <listitem>
+                <para>disassociate an floating IP from a certain
+                    instance</para>
+            </listitem>
+        </itemizedlist>
+            <para>Just as shown by above figure, we will have
+                nova-network-api to support nova client floating
+                commands. nova-network-api will invoke quantum cli lib
+                to interactive with quantum server via API. The data
+                about floating IPs will be store in to quantum DB.
+                Quantum Agent, which is running on compute host will
+                enforce the floating IP.</para>
+            <para><guilabel>Multiple Floating
+                IP Pools</guilabel></para>
+            <para>The L3 API in OpenStack Networking supports multiple
+                floating IP pools. In OpenStack Networking, a floating
+                IP pool is represented as an external network and a
+                floating IP is allocated from a subnet associated with
+                the external network. Since each L3 agent can be
+                associated with at most one external network, we need
+                to invoke multiple L3 agent to define multiple
+                floating IP pools. 'gateway_external_network_id'in L3
+                agent configuration file indicates the external
+                network that the L3 agent handles. You can run
+                multiple L3 agent instances on one host.</para>
+            <para>In addition, when you run multiple L3 agents, make
+                sure that handle_internal_only_routersis set to
+                Trueonly for one L3 agent in an OpenStack Networking
+                deployment and set to Falsefor all other L3 agents.
+                Since the default value of this parameter is True, you
+                need to configure it carefully.</para>
+            <para>Before starting L3 agents, you need to create
+                routers and external networks, then update the
+                configuration files with UUID of external networks and
+                start L3 agents.</para>
+            <para>For the first agent, invoke it with the following
+                l3_agent.ini where handle_internal_only_routers is
+                True.</para>
+</chapter>

doc/training-guide/module003-ch000-openstack-objstore.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<book xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:svg="http://www.w3.org/2000/svg"
+    xmlns:html="http://www.w3.org/1999/xhtml"
+    version="5.0"
+    xml:id="module003-ch000-openstack-objstore">
+    <title>OpenStack Object Storage</title>
+    <xi:include href="module003-ch001-intro-objstore.xml"/>
+    <xi:include href="module003-ch002-features-benifits.xml"/>
+    <xi:include href="module003-ch003-obj-store-capabilities.xml"/>
+    <xi:include href="module003-ch004-swift-building-blocks.xml"/>
+    <xi:include href="module003-ch005-the-ring.xml"/>
+    <xi:include href="module003-ch006-more-concepts.xml"/>
+    <xi:include href="module003-ch007-swift-cluster-architecture.xml"/>
+    <xi:include href="module003-ch008-account-reaper.xml"/>
+    <xi:include href="module003-ch009-replication.xml"/>
+</book>

doc/training-guide/module003-ch001-intro-objstore.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module003-ch001-intro-objectstore">
+    <title>Introduction to Object Storage</title>
+    <para>OpenStack Object Storage (code-named Swift) is open source
+        software for creating redundant, scalable data storage using
+        clusters of standardized servers to store petabytes of
+        accessible data. It is a long-term storage system for large
+        amounts of static data that can be retrieved, leveraged, and
+        updated. Object Storage uses a distributed architecture with
+        no central point of control, providing greater scalability,
+        redundancy and permanence. Objects are written to multiple
+        hardware devices, with the OpenStack software responsible for
+        ensuring data replication and integrity across the cluster.
+        Storage clusters scale horizontally by adding new nodes.
+        Should a node fail, OpenStack works to replicate its content
+        from other active nodes. Because OpenStack uses software logic
+        to ensure data replication and distribution across different
+        devices, inexpensive commodity hard drives and servers can be
+        used in lieu of more expensive equipment.</para>
+    <para>Object Storage is ideal for cost effective, scale-out
+        storage. It provides a fully distributed, API-accessible
+        storage platform that can be integrated directly into
+        applications or used for backup, archiving and data retention.
+        Block Storage allows block devices to be exposed and connected
+        to compute instances for expanded storage, better performance
+        and integration with enterprise storage platforms, such as
+        NetApp, Nexenta and SolidFire.</para>
+</chapter>

doc/training-guide/module003-ch002-features-benifits.xml

@@ -0,0 +1,204 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module003-ch002-features-benefits">
+    <title>Features and Benifits</title>
+    <para>
+        <informaltable class="c19">
+            <tbody>
+                <tr>
+                    <th rowspan="1" colspan="1">Features</th>
+                    <th rowspan="1" colspan="1">Benefits</th>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Leverages commodity
+                        hardware</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >No
+                        lock-in, lower
+                        price/GB</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >HDD/node failure agnostic</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Self
+                        healingReliability, data redundancy protecting
+                        from
+                        failures</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Unlimited storage</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Huge
+                        &amp; flat namespace, highly scalable
+                        read/write accessAbility to serve content
+                        directly from storage
+                        system</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Multi-dimensional scalability</emphasis>
+                        (scale out architecture)Scale vertically and
+                        horizontally-distributed storage</td>
+                    <td rowspan="1" colspan="1"
+                        >Backup
+                        and archive large amounts of data with linear
+                        performance</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Account/Container/Object
+                            structure</emphasis>No nesting, not a
+                        traditional file system</td>
+                    <td rowspan="1" colspan="1"
+                        >Optimized
+                        for scaleScales to multiple petabytes,
+                        billions of
+                        objects</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Built-in replication3x+ data
+                            redundancy</emphasis> compared to 2x on
+                        RAID</td>
+                    <td rowspan="1" colspan="1"
+                        >Configurable
+                        number of accounts, container and object
+                        copies for high
+                        availability</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Easily add capacity</emphasis> unlike
+                        RAID resize</td>
+                    <td rowspan="1" colspan="1"
+                        >Elastic
+                        data scaling with
+                        ease</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >No central database</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Higher
+                        performance, no
+                        bottlenecks</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >RAID not required</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Handle
+                        lots of small, random reads and writes
+                        efficiently</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Built-in management
+                        utilities</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Account
+                        Management: Create, add, verify, delete
+                        usersContainer Management: Upload, download,
+                        verifyMonitoring: Capacity, host, network, log
+                        trawling, cluster
+                        health</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Drive auditing</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Detect
+                        drive failures preempting data
+                        corruption</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Expiring objects</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Users
+                        can set an expiration time or a TTL on an
+                        object to control
+                        access</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Direct object access</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Enable
+                        direct browser access to content, such as for
+                        a control
+                        panel</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Realtime visibility into client
+                            requests</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Know
+                        what users are
+                        requesting</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Supports S3 API</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Utilize
+                        tools that were designed for the popular S3
+                        API</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Restrict containers per
+                            account</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Limit
+                        access to control usage by
+                        user</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Support for NetApp, Nexenta,
+                            SolidFire</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Unified
+                        support for block volumes using a variety of
+                        storage
+                        systems</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Snapshot and backup API for block
+                            volumes</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Data
+                        protection and recovery for VM
+                        data</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Standalone volume API
+                            available</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Separate
+                        endpoint and API for integration with other
+                        compute
+                        systems</td>
+                </tr>
+                <tr>
+                    <td rowspan="1" colspan="1"><emphasis role="bold"
+                            >Integration with Compute</emphasis></td>
+                    <td rowspan="1" colspan="1"
+                        >Fully
+                        integrated to Compute for attaching block
+                        volumes and reporting on usage</td>
+                </tr>
+            </tbody>
+        </informaltable>
+    </para>
+</chapter>

doc/training-guide/module003-ch003-obj-store-capabilities.xml

@@ -0,0 +1,100 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module003-ch003-obj-store-capabilities">
+    <title>Object Storage Capabilities</title>
+    <itemizedlist>
+        <listitem>
+            <para>OpenStack provides redundant, scalable object
+                storage using clusters of standardized servers capable
+                of storing petabytes of data</para>
+        </listitem>
+        <listitem>
+            <para>Object Storage is not a traditional file system, but
+                rather a distributed storage system for static data
+                such as virtual machine images, photo storage, email
+                storage, backups and archives. Having no central
+                "brain" or master point of control provides greater
+                scalability, redundancy and durability.</para>
+        </listitem>
+        <listitem>
+            <para>Objects and files are written to multiple disk
+                drives spread throughout servers in the data center,
+                with the OpenStack software responsible for ensuring
+                data replication and integrity across the
+                cluster.</para>
+        </listitem>
+        <listitem>
+            <para>Storage clusters scale horizontally simply by adding
+                new servers. Should a server or hard drive fail,
+                OpenStack replicates its content from other active
+                nodes to new locations in the cluster. Because
+                OpenStack uses software logic to ensure data
+                replication and distribution across different devices,
+                inexpensive commodity hard drives and servers can be
+                used in lieu of more expensive equipment.</para>
+        </listitem>
+    </itemizedlist>
+    <para><guilabel>Swift Characteristics</guilabel></para>
+    <para>The key characteristics of Swift include:</para>
+    <itemizedlist>
+        <listitem>
+            <para>All objects stored in Swift have a URL</para>
+        </listitem>
+        <listitem>
+            <para>All objects stored are replicated 3x in
+                as-unique-as-possible zones, which can be defined as a
+                group of drives, a node, a rack etc.</para>
+        </listitem>
+        <listitem>
+            <para>All objects have their own metadata</para>
+        </listitem>
+        <listitem>
+            <para>Developers interact with the object storage system
+                through a RESTful HTTP API</para>
+        </listitem>
+        <listitem>
+            <para>Object data can be located anywhere in the
+                cluster</para>
+        </listitem>
+        <listitem>
+            <para>The cluster scales by adding additional nodes --
+                without sacrificing performance, which allows a more
+                cost-effective linear storage expansion vs. fork-lift
+                upgrades</para>
+        </listitem>
+        <listitem>
+            <para>Data doesn’t have to be migrated to an entirely new
+                storage system</para>
+        </listitem>
+        <listitem>
+            <para>New nodes can be added to the cluster without
+                downtime</para>
+        </listitem>
+        <listitem>
+            <para>Failed nodes and disks can be swapped out with no
+                downtime</para>
+        </listitem>
+        <listitem>
+            <para>Runs on industry-standard hardware, such as Dell,
+                HP, Supermicro etc.</para>
+        </listitem>
+    </itemizedlist>
+    <figure>
+        <title>Object Storage(Swift)</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image39.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+    <para>Developers can either write directly to the Swift API or use
+        one of the many client libraries that exist for all popular
+        programming languages, such as Java, Python, Ruby and C#.
+        Amazon S3 and RackSpace Cloud Files users should feel very
+        familiar with Swift. For users who have not used an object
+        storage system before, it will require a different approach
+        and mindset than using a traditional filesystem.</para>
+</chapter>

doc/training-guide/module003-ch004-swift-building-blocks.xml

@@ -0,0 +1,295 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module003-ch004-swift-building-blocks">
+    <title>Building Blocks of Swift</title>
+        <para>The components that enable Swift to deliver high
+            availability, high durability and high concurrency
+            are:</para>
+        <itemizedlist>
+            <listitem>
+                <para><emphasis role="bold">Proxy
+                Servers:</emphasis>Handles all incoming API
+                requests.</para>
+            </listitem>
+            <listitem>
+                <para><emphasis role="bold">Rings:</emphasis>Maps
+                logical names of data to locations on particular
+                disks.</para>
+            </listitem>
+            <listitem>
+                <para><emphasis role="bold">Zones:</emphasis>Each Zone
+                isolates data from other Zones. A failure in one Zone
+                doesn’t impact the rest of the cluster because data is
+                replicated across the Zones.</para>
+            </listitem>
+            <listitem>
+                <para><emphasis role="bold">Accounts &amp;
+                    Containers:</emphasis>Each Account and Container
+                are individual databases that are distributed across
+                the cluster. An Account database contains the list of
+                Containers in that Account. A Container database
+                contains the list of Objects in that Container</para>
+            </listitem>
+            <listitem>
+                <para><emphasis role="bold">Objects:</emphasis>The
+                data itself.</para>
+            </listitem>
+            <listitem>
+                <para><emphasis role="bold">Partitions:</emphasis>A
+                Partition stores Objects, Account databases and
+                Container databases. It’s an intermediate 'bucket'
+                that helps manage locations where data lives in the
+                cluster.</para>
+            </listitem>
+        </itemizedlist>
+    <figure>
+        <title>Building Blocks</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image40.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+        <para><guilabel>Proxy Servers</guilabel></para>
+        <para>The Proxy Servers are the public face of Swift and
+            handle all incoming API requests. Once a Proxy Server
+            receive a request, it will determine the storage node
+            based on the URL of the object, e.g.
+            https://swift.example.com/v1/account/container/object. The
+            Proxy Servers also coordinates responses, handles failures
+            and coordinates timestamps.</para>
+        <para>Proxy servers use a shared-nothing architecture and can
+            be scaled as needed based on projected workloads. A
+            minimum of two Proxy Servers should be deployed for
+            redundancy. Should one proxy server fail, the others will
+            take over.</para>
+    <para><guilabel>The Ring</guilabel></para>
+    <para>A ring represents a mapping between the names of entities
+        stored on disk and their physical location. There are separate
+        rings for accounts, containers, and objects. When other
+        components need to perform any operation on an object,
+        container, or account, they need to interact with the
+        appropriate ring to determine its location in the
+        cluster.</para>
+    <para>The Ring maintains this mapping using zones, devices,
+        partitions, and replicas. Each partition in the ring is
+        replicated, by default, 3 times across the cluster, and the
+        locations for a partition are stored in the mapping maintained
+        by the ring. The ring is also responsible for determining
+        which devices are used for hand off in failure
+        scenarios.</para>
+        <para>Data can be isolated with the concept of zones in the
+            ring. Each replica of a partition is guaranteed to reside
+            in a different zone. A zone could represent a drive, a
+            server, a cabinet, a switch, or even a data center.</para>
+        <para>The partitions of the ring are equally divided among all
+            the devices in the OpenStack Object Storage installation.
+            When partitions need to be moved around (for example if a
+            device is added to the cluster), the ring ensures that a
+            minimum number of partitions are moved at a time, and only
+            one replica of a partition is moved at a time.</para>
+        <para>Weights can be used to balance the distribution of
+            partitions on drives across the cluster. This can be
+            useful, for example, when different sized drives are used
+            in a cluster.</para>
+        <para>The ring is used by the Proxy server and several
+            background processes (like replication).</para>
+        <para>The Ring maps Partitions to physical locations on disk.
+            When other components need to perform any operation on an
+            object, container, or account, they need to interact with
+            the Ring to determine its location in the cluster.</para>
+        <para>The Ring maintains this mapping using zones, devices,
+            partitions, and replicas. Each partition in the Ring is
+            replicated three times by default across the cluster, and
+            the locations for a partition are stored in the mapping
+            maintained by the Ring. The Ring is also responsible for
+            determining which devices are used for handoff should a
+            failure occur.</para>
+    <figure>
+        <title>The Lord of the <emphasis role="bold"
+            >Ring</emphasis>s</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image41.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+        <para>The Ring maps partitions to physical locations on
+            disk.</para>
+        <para>The rings determine where data should reside in the
+            cluster. There is a separate ring for account databases,
+            container databases, and individual objects but each ring
+            works in the same way. These rings are externally managed,
+            in that the server processes themselves do not modify the
+            rings, they are instead given new rings modified by other
+            tools.</para>
+        <para>The ring uses a configurable number of bits from a
+            path’s MD5 hash as a partition index that designates a
+            device. The number of bits kept from the hash is known as
+            the partition power, and 2 to the partition power
+            indicates the partition count. Partitioning the full MD5
+            hash ring allows other parts of the cluster to work in
+            batches of items at once which ends up either more
+            efficient or at least less complex than working with each
+            item separately or the entire cluster all at once.</para>
+        <para>Another configurable value is the replica count, which
+        indicates how many of the partition-&gt;device assignments
+        comprise a single ring. For a given partition number, each
+        replica’s device will not be in the same zone as any other
+        replica's device. Zones can be used to group devices based on
+        physical locations, power separations, network separations, or
+        any other attribute that would lessen multiple replicas being
+        unavailable at the same time.</para>
+        <para><guilabel>Zones: Failure Boundaries</guilabel></para>
+            <para>Swift allows zones to be configured to isolate
+                failure boundaries. Each replica of the data resides
+                in a separate zone, if possible. At the smallest
+                level, a zone could be a single drive or a grouping of
+                a few drives. If there were five object storage
+                servers, then each server would represent its own
+                zone. Larger deployments would have an entire rack (or
+                multiple racks) of object servers, each representing a
+                zone. The goal of zones is to allow the cluster to
+                tolerate significant outages of storage servers
+                without losing all replicas of the data.</para>
+            <para>As we learned earlier, everything in Swift is
+                stored, by default, three times. Swift will place each
+                replica "as-uniquely-as-possible" to ensure both high
+                availability and high durability. This means that when
+                chosing a replica location, Swift will choose a server
+                in an unused zone before an unused server in a zone
+                that already has a replica of the data.</para>
+    <figure>
+        <title>image33.png</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image42.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+            <para>When a disk fails, replica data is automatically
+                distributed to the other zones to ensure there are
+                three copies of the data</para>
+            <para><guilabel>Accounts &amp;
+                Containers</guilabel></para>
+            <para>Each account and container is an individual SQLite
+                database that is distributed across the cluster. An
+                account database contains the list of containers in
+                that account. A container database contains the list
+                of objects in that container.</para>
+    <figure>
+        <title>Accounts and Containers</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image43.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+            <para>To keep track of object data location, each account
+                in the system has a database that references all its
+                containers, and each container database references
+                each object</para>
+            <para><guilabel>Partitions</guilabel></para>
+            <para>A Partition is a collection of stored data,
+                including Account databases, Container databases, and
+                objects. Partitions are core to the replication
+                system.</para>
+            <para>Think of a Partition as a bin moving throughout a
+                fulfillment center warehouse. Individual orders get
+                thrown into the bin. The system treats that bin as a
+                cohesive entity as it moves throughout the system. A
+                bin full of things is easier to deal with than lots of
+                little things. It makes for fewer moving parts
+                throughout the system.</para>
+            <para>The system replicators and object uploads/downloads
+                operate on Partitions. As the system scales up,
+                behavior continues to be predictable as the number of
+                Partitions is a fixed number.</para>
+            <para>The implementation of a Partition is conceptually
+                simple -- a partition is just a directory sitting on a
+                disk with a corresponding hash table of what it
+                contains.</para>
+    <figure>
+        <title>Partitions</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image44.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+            <para>*Swift partitions contain all data in the
+                system.</para>
+            <para><guilabel>Replication</guilabel></para>
+            <para>In order to ensure that there are three copies of
+                the data everywhere, replicators continuously examine
+                each Partition. For each local Partition, the
+                replicator compares it against the replicated copies
+                in the other Zones to see if there are any
+                differences.</para>
+            <para>How does the replicator know if replication needs to
+                take place? It does this by examining hashes. A hash
+                file is created for each Partition, which contains
+                hashes of each directory in the Partition. Each of the
+                three hash files is compared. For a given Partition,
+                the hash files for each of the Partition's copies are
+                compared. If the hashes are different, then it is time
+                to replicate and the directory that needs to be
+                replicated is copied over.</para>
+            <para>This is where the Partitions come in handy. With
+                fewer "things" in the system, larger chunks of data
+                are transferred around (rather than lots of little TCP
+                connections, which is inefficient) and there are a
+                consistent number of hashes to compare.</para>
+            <para>The cluster has eventually consistent behavior where
+                the newest data wins.</para>
+    <figure>
+        <title>Replication</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image45.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+            <para>*If a zone goes down, one of the nodes containing a
+                replica notices and proactively copies data to a
+                handoff location.</para>
+    <para>To describe how these pieces all come together, let's walk
+        through a few scenarios and introduce the components.</para>
+    <para><guilabel>Bird-eye View</guilabel></para>
+    <para><emphasis role="bold">Upload</emphasis></para>
+    
+        <para>A client uses the REST API to make a HTTP request to PUT
+            an object into an existing Container. The cluster receives
+            the request. First, the system must figure out where the
+            data is going to go. To do this, the Account name,
+            Container name and Object name are all used to determine
+            the Partition where this object should live.</para>
+        <para>Then a lookup in the Ring figures out which storage
+            nodes contain the Partitions in question.</para>
+        <para>The data then is sent to each storage node where it is
+            placed in the appropriate Partition. A quorum is required
+            -- at least two of the three writes must be successful
+            before the client is notified that the upload was
+            successful.</para>
+        <para>Next, the Container database is updated asynchronously
+            to reflect that there is a new object in it.</para>
+    <figure>
+        <title>When End-User uses Swift</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image46.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+    <para><emphasis role="bold">Download</emphasis></para>    
+        <para>A request comes in for an Account/Container/object.
+            Using the same consistent hashing, the Partition name is
+            generated. A lookup in the Ring reveals which storage
+            nodes contain that Partition. A request is made to one of
+            the storage nodes to fetch the object and if that fails,
+            requests are made to the other nodes.</para>
+    
+</chapter>

doc/training-guide/module003-ch005-the-ring.xml

@@ -0,0 +1,146 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module003-ch005-the-ring">
+    <title>Ring Builder</title>
+    <para>The rings are built and managed manually by a utility called
+        the ring-builder. The ring-builder assigns partitions to
+        devices and writes an optimized Python structure to a gzipped,
+        serialized file on disk for shipping out to the servers. The
+        server processes just check the modification time of the file
+        occasionally and reload their in-memory copies of the ring
+        structure as needed. Because of how the ring-builder manages
+        changes to the ring, using a slightly older ring usually just
+        means one of the three replicas for a subset of the partitions
+        will be incorrect, which can be easily worked around.</para>
+    <para>The ring-builder also keeps its own builder file with the
+        ring information and additional data required to build future
+        rings. It is very important to keep multiple backup copies of
+        these builder files. One option is to copy the builder files
+        out to every server while copying the ring files themselves.
+        Another is to upload the builder files into the cluster
+        itself. Complete loss of a builder file will mean creating a
+        new ring from scratch, nearly all partitions will end up
+        assigned to different devices, and therefore nearly all data
+        stored will have to be replicated to new locations. So,
+        recovery from a builder file loss is possible, but data will
+        definitely be unreachable for an extended time.</para>
+        <para><guilabel>Ring Data Structure</guilabel></para>
+        <para>The ring data structure consists of three top level
+            fields: a list of devices in the cluster, a list of lists
+            of device ids indicating partition to device assignments,
+            and an integer indicating the number of bits to shift an
+            MD5 hash to calculate the partition for the hash.</para>
+            <para><guilabel>Partition Assignment
+        List</guilabel></para>
+            <para>This is a list of array(‘H’) of devices ids. The
+                outermost list contains an array(‘H’) for each
+                replica. Each array(‘H’) has a length equal to the
+                partition count for the ring. Each integer in the
+                array(‘H’) is an index into the above list of devices.
+                The partition list is known internally to the Ring
+                class as _replica2part2dev_id.</para>
+            <para>So, to create a list of device dictionaries assigned
+                to a partition, the Python code would look like:
+                devices = [self.devs[part2dev_id[partition]] for
+                part2dev_id in self._replica2part2dev_id]</para>
+            <para>That code is a little simplistic, as it does not
+                account for the removal of duplicate devices. If a
+                ring has more replicas than devices, then a partition
+                will have more than one replica on one device; that’s
+                simply the pigeonhole principle at work.</para>
+            <para>array(‘H’) is used for memory conservation as there
+                may be millions of partitions.</para>
+            <para><guilabel>Fractional Replicas</guilabel></para>
+            <para>A ring is not restricted to having an integer number
+                of replicas. In order to support the gradual changing
+                of replica counts, the ring is able to have a real
+                number of replicas.</para>
+            <para>When the number of replicas is not an integer, then
+                the last element of _replica2part2dev_id will have a
+                length that is less than the partition count for the
+                ring. This means that some partitions will have more
+                replicas than others. For example, if a ring has 3.25
+                replicas, then 25% of its partitions will have four
+                replicas, while the remaining 75% will have just
+                three.</para>
+            <para><guilabel>Partition Shift Value</guilabel></para>
+            <para>The partition shift value is known internally to the
+                Ring class as _part_shift. This value used to shift an
+                MD5 hash to calculate the partition on which the data
+                for that hash should reside. Only the top four bytes
+                of the hash is used in this process. For example, to
+                compute the partition for the path
+                /account/container/object the Python code might look
+                like: partition = unpack_from('&gt;I',
+                md5('/account/container/object').digest())[0] &gt;&gt;
+                self._part_shift</para>
+            <para>For a ring generated with part_power P, the
+                partition shift value is 32 - P.</para>
+        <para><guilabel>Building the Ring</guilabel></para>
+        <para>The initial building of the ring first calculates the
+            number of partitions that should ideally be assigned to
+            each device based the device’s weight. For example, given
+            a partition power of 20, the ring will have 1,048,576
+            partitions. If there are 1,000 devices of equal weight
+            they will each desire 1,048.576 partitions. The devices
+            are then sorted by the number of partitions they desire
+            and kept in order throughout the initialization
+            process.</para>
+        <para>Note: each device is also assigned a random tiebreaker
+            value that is used when two devices desire the same number
+            of partitions. This tiebreaker is not stored on disk
+            anywhere, and so two different rings created with the same
+            parameters will have different partition assignments. For
+            repeatable partition assignments, RingBuilder.rebalance()
+            takes an optional seed value that will be used to seed
+            Python’s pseudo-random number generator.</para>
+        <para>Then, the ring builder assigns each replica of each
+            partition to the device that desires the most partitions
+            at that point while keeping it as far away as possible
+            from other replicas. The ring builder prefers to assign a
+            replica to a device in a regions that has no replicas
+            already; should there be no such region available, the
+            ring builder will try to find a device in a different
+            zone; if not possible, it will look on a different server;
+            failing that, it will just look for a device that has no
+            replicas; finally, if all other options are exhausted, the
+            ring builder will assign the replica to the device that
+            has the fewest replicas already assigned. Note that
+            assignment of multiple replicas to one device will only
+            happen if the ring has fewer devices than it has
+            replicas.</para>
+        <para>When building a new ring based on an old ring, the
+            desired number of partitions each device wants is
+            recalculated. Next the partitions to be reassigned are
+            gathered up. Any removed devices have all their assigned
+            partitions unassigned and added to the gathered list. Any
+            partition replicas that (due to the addition of new
+            devices) can be spread out for better durability are
+            unassigned and added to the gathered list. Any devices
+            that have more partitions than they now desire have random
+            partitions unassigned from them and added to the gathered
+            list. Lastly, the gathered partitions are then reassigned
+            to devices using a similar method as in the initial
+            assignment described above.</para>
+        <para>Whenever a partition has a replica reassigned, the time
+            of the reassignment is recorded. This is taken into
+            account when gathering partitions to reassign so that no
+            partition is moved twice in a configurable amount of time.
+            This configurable amount of time is known internally to
+            the RingBuilder class as min_part_hours. This restriction
+            is ignored for replicas of partitions on devices that have
+            been removed, as removing a device only happens on device
+            failure and there’s no choice but to make a
+            reassignment.</para>
+        <para>The above processes don’t always perfectly rebalance a
+            ring due to the random nature of gathering partitions for
+            reassignment. To help reach a more balanced ring, the
+            rebalance process is repeated until near perfect (less 1%
+            off) or when the balance doesn’t improve by at least 1%
+            (indicating we probably can’t get perfect balance due to
+            wildly imbalanced zones or too many partitions recently
+            moved).</para>
+</chapter>

doc/training-guide/module003-ch006-more-concepts.xml

@@ -0,0 +1,220 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module003-ch006-more-concepts">
+    <title>A Bit More On Swift</title>
+        <para><guilabel>Containers and Objects</guilabel></para>
+        <para>A container is a storage compartment for your data and
+            provides a way for you to organize your data. You can
+            think of a container as a folder in Windows or a
+            directory in UNIX. The primary difference between a
+            container and these other file system concepts is that
+            containers cannot be nested. You can, however, create an
+            unlimited number of containers within your account. Data
+            must be stored in a container so you must have at least
+            one container defined in your account prior to uploading
+            data.</para>
+        <para>The only restrictions on container names is that they
+            cannot contain a forward slash (/) or an ascii null (%00)
+            and must be less than 257 bytes in length. Please note
+            that the length restriction applies to the name after it
+            has been URL encoded. For example, a container name of
+            Course Docs would be URL encoded as Course%20Docs and
+            therefore be 13 bytes in length rather than the expected
+            11.</para>
+        <para>An object is the basic storage entity and any optional
+            metadata that represents the files you store in the
+            OpenStack Object Storage system. When you upload data to
+            OpenStack Object Storage, the data is stored as-is (no
+            compression or encryption) and consists of a location
+            (container), the object's name, and any metadata
+            consisting of key/value pairs. For instance, you may chose
+            to store a backup of your digital photos and organize them
+            into albums. In this case, each object could be tagged
+            with metadata such as Album : Caribbean Cruise or Album :
+            Aspen Ski Trip.</para>
+        <para>The only restriction on object names is that they must
+            be less than 1024 bytes in length after URL encoding. For
+            example, an object name of C++final(v2).txt should be URL
+            encoded as C%2B%2Bfinal%28v2%29.txt and therefore be 24
+            bytes in length rather than the expected 16.</para>
+        <para>The maximum allowable size for a storage object upon
+            upload is 5 gigabytes (GB) and the minimum is zero bytes.
+            You can use the built-in large object support and the
+            swift utility to retrieve objects larger than 5 GB.</para>
+        <para>For metadata, you should not exceed 90 individual
+            key/value pairs for any one object and the total byte
+            length of all key/value pairs should not exceed 4KB (4096
+            bytes).</para>
+        <para><guilabel>Language-Specific API
+        Bindings</guilabel></para>
+        <para>A set of supported API bindings in several popular
+            languages are available from the Rackspace Cloud Files
+            product, which uses OpenStack Object Storage code for its
+            implementation. These bindings provide a layer of
+            abstraction on top of the base REST API, allowing
+            programmers to work with a container and object model
+            instead of working directly with HTTP requests and
+            responses. These bindings are free (as in beer and as in
+            speech) to download, use, and modify. They are all
+            licensed under the MIT License as described in the COPYING
+            file packaged with each binding. If you do make any
+            improvements to an API, you are encouraged (but not
+            required) to submit those changes back to us.</para>
+        <para>The API bindings for Rackspace Cloud Files are hosted
+                at<link xlink:href="http://github.com/rackspace"
+                ></link><link
+                xlink:href="http://github.com/rackspace"
+                >http://github.com/rackspace</link>. Feel free to
+            coordinate your changes through github or, if you prefer,
+            send your changes to cloudfiles@rackspacecloud.com. Just
+            make sure to indicate which language and version you
+            modified and send a unified diff.</para>
+        <para>Each binding includes its own documentation (either
+            HTML, PDF, or CHM). They also include code snippets and
+            examples to help you get started. The currently supported
+            API binding for OpenStack Object Storage are:</para>
+        <itemizedlist>
+            <listitem>
+                <para>PHP (requires 5.x and the modules: cURL,
+                    FileInfo, mbstring)</para>
+            </listitem>
+            <listitem>
+                <para>Python (requires 2.4 or newer)</para>
+            </listitem>
+            <listitem>
+                <para>Java (requires JRE v1.5 or newer)</para>
+            </listitem>
+            <listitem>
+                <para>C#/.NET (requires .NET Framework v3.5)</para>
+            </listitem>
+            <listitem>
+                <para>Ruby (requires 1.8 or newer and mime-tools
+                    module)</para>
+            </listitem>
+        </itemizedlist>
+        <para>There are no other supported language-specific bindings
+            at this time. You are welcome to create your own language
+            API bindings and we can help answer any questions during
+            development, host your code if you like, and give you full
+            credit for your work.</para>
+            <para><guilabel>Proxy Server</guilabel></para>
+            <para>The Proxy Server is responsible for tying together
+                the rest of the OpenStack Object Storage architecture.
+                For each request, it will look up the location of the
+                account, container, or object in the ring (see below)
+                and route the request accordingly. The public API is
+                also exposed through the Proxy Server.</para>
+            <para>A large number of failures are also handled in the
+                Proxy Server. For example, if a server is unavailable
+                for an object PUT, it will ask the ring for a hand-off
+                server and route there instead.</para>
+            <para>When objects are streamed to or from an object
+                server, they are streamed directly through the proxy
+                server to or from the user – the proxy server does not
+                spool them.</para>
+            <para>You can use a proxy server with account management
+                enabled by configuring it in the proxy server
+                configuration file.</para>
+            <para><guilabel>Object Server</guilabel></para>
+            <para>The Object Server is a very simple blob storage
+                server that can store, retrieve and delete objects
+                stored on local devices. Objects are stored as binary
+                files on the filesystem with metadata stored in the
+                file’s extended attributes (xattrs). This requires
+                that the underlying filesystem choice for object
+                servers support xattrs on files. Some filesystems,
+                like ext3, have xattrs turned off by default.</para>
+            <para>Each object is stored using a path derived from the
+                object name’s hash and the operation’s timestamp. Last
+                write always wins, and ensures that the latest object
+                version will be served. A deletion is also treated as
+                a version of the file (a 0 byte file ending with
+                “.ts”, which stands for tombstone). This ensures that
+                deleted files are replicated correctly and older
+                versions don’t magically reappear due to failure
+                scenarios.</para>
+            <para><guilabel>Container Server</guilabel></para>
+            <para>The Container Server’s primary job is to handle
+                listings of objects. It does not’t know where those
+                objects are, just what objects are in a specific
+                container. The listings are stored as sqlite database
+                files, and replicated across the cluster similar to
+                how objects are. Statistics are also tracked that
+                include the total number of objects, and total storage
+                usage for that container.</para>
+            <para><guilabel>Account Server</guilabel></para>
+            <para>The Account Server is very similar to the Container
+                Server, excepting that it is responsible for listings
+                of containers rather than objects.</para>
+            <para><guilabel>Replication</guilabel></para>
+            <para>Replication is designed to keep the system in a
+                consistent state in the face of temporary error
+                conditions like network outages or drive
+                failures.</para>
+            <para>The replication processes compare local data with
+                each remote copy to ensure they all contain the latest
+                version. Object replication uses a hash list to
+                quickly compare subsections of each partition, and
+                container and account replication use a combination of
+                hashes and shared high water marks.</para>
+            <para>Replication updates are push based. For object
+                replication, updating is just a matter of rsyncing
+                files to the peer. Account and container replication
+                push missing records over HTTP or rsync whole database
+                files.</para>
+            <para>The replicator also ensures that data is removed
+                from the system. When an item (object, container, or
+                account) is deleted, a tombstone is set as the latest
+                version of the item. The replicator will see the
+                tombstone and ensure that the item is removed from the
+                entire system.</para>
+            <para>To separate the cluster-internal replication traffic
+                from client traffic, separate replication servers can
+                be used. These replication servers are based on the
+                standard storage servers, but they listen on the
+                replication IP and only respond to REPLICATE requests.
+                Storage servers can serve REPLICATE requests, so an
+                operator can transition to using a separate
+                replication network with no cluster downtime.</para>
+            <para>Replication IP and port information is stored in the
+                ring on a per-node basis. These parameters will be
+                used if they are present, but they are not required.
+                If this information does not exist or is empty for a
+                particular node, the node's standard IP and port will
+                be used for replication.</para>
+            <para><guilabel>Updaters</guilabel></para>
+            <para>There are times when container or account data can
+                not be immediately updated. This usually occurs during
+                failure scenarios or periods of high load. If an
+                update fails, the update is queued locally on the file
+                system, and the updater will process the failed
+                updates. This is where an eventual consistency window
+                will most likely come in to play. For example, suppose
+                a container server is under load and a new object is
+                put in to the system. The object will be immediately
+                available for reads as soon as the proxy server
+                responds to the client with success. However, the
+                container server did not update the object listing,
+                and so the update would be queued for a later update.
+                Container listings, therefore, may not immediately
+                contain the object.</para>
+            <para>In practice, the consistency window is only as large
+                as the frequency at which the updater runs and may not
+                even be noticed as the proxy server will route listing
+                requests to the first container server which responds.
+                The server under load may not be the one that serves
+                subsequent listing requests – one of the other two
+                replicas may handle the listing.</para>
+            <para><guilabel>Auditors</guilabel></para>
+            <para>Auditors crawl the local server checking the
+                integrity of the objects, containers, and accounts. If
+                corruption is found (in the case of bit rot, for
+                example), the file is quarantined, and replication
+                will replace the bad file from another replica. If
+                other errors are found they are logged (for example,
+                an object’s listing can’t be found on any container
+                server it should be).</para>
+</chapter>

doc/training-guide/module003-ch007-swift-cluster-architecture.xml

@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module003-ch007-cluster-architecture">
+    <title>Cluster Arch</title>
+        <para><guilabel>Access Tier</guilabel></para>
+    <figure>
+        <title>Swift Cluster Architecture</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image47.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+        <para>Large-scale deployments segment off an "Access Tier".
+            This tier is the “Grand Central” of the Object Storage
+            system. It fields incoming API requests from clients and
+            moves data in and out of the system. This tier is composed
+            of front-end load balancers, ssl- terminators,
+            authentication services, and it runs the (distributed)
+            brain of the object storage system — the proxy server
+            processes.</para>
+        <para>Having the access servers in their own tier enables
+            read/write access to be scaled out independently of
+            storage capacity. For example, if the cluster is on the
+            public Internet and requires ssl-termination and has high
+            demand for data access, many access servers can be
+            provisioned. However, if the cluster is on a private
+            network and it is being used primarily for archival
+            purposes, fewer access servers are needed.</para>
+        <para>As this is an HTTP addressable storage service, a load
+            balancer can be incorporated into the access tier.</para>
+        <para>Typically, this tier comprises a collection of 1U
+            servers. These machines use a moderate amount of RAM and
+            are network I/O intensive. As these systems field each
+            incoming API request, it is wise to provision them with
+            two high-throughput (10GbE) interfaces. One interface is
+            used for 'front-end' incoming requests and the other for
+            'back-end' access to the object storage nodes to put and
+            fetch data.</para>
+            <para><guilabel>Factors to Consider</guilabel></para>
+            <para>For most publicly facing deployments as well as
+                private deployments available across a wide-reaching
+                corporate network, SSL will be used to encrypt traffic
+                to the client. SSL adds significant processing load to
+                establish sessions between clients; more capacity in
+                the access layer will need to be provisioned. SSL may
+                not be required for private deployments on trusted
+                networks.</para>
+        <para><guilabel>Storage Nodes</guilabel></para>
+    <figure>
+        <title>Object Storage (Swift)</title>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/image48.png"/>
+            </imageobject>
+        </mediaobject>
+    </figure>
+        <para>The next component is the storage servers themselves.
+            Generally, most configurations should have each of the
+            five Zones with an equal amount of storage capacity.
+            Storage nodes use a reasonable amount of memory and CPU.
+            Metadata needs to be readily available to quickly return
+            objects. The object stores run services not only to field
+            incoming requests from the Access Tier, but to also run
+            replicators, auditors, and reapers. Object stores can be
+            provisioned with single gigabit or 10 gigabit network
+            interface depending on expected workload and desired
+            performance.</para>
+        <para>Currently 2TB or 3TB SATA disks deliver good
+            price/performance value. Desktop-grade drives can be used
+            where there are responsive remote hands in the datacenter,
+            and enterprise-grade drives can be used where this is not
+            the case.</para>
+            <para><guilabel>Factors to Consider</guilabel></para>
+            <para>Desired I/O performance for single-threaded requests
+                should be kept in mind. This system does not use RAID,
+                so each request for an object is handled by a single
+                disk. Disk performance impacts single-threaded
+                response rates.</para>
+            <para>To achieve apparent higher throughput, the object
+                storage system is designed with concurrent
+                uploads/downloads in mind. The network I/O capacity
+                (1GbE, bonded 1GbE pair, or 10GbE) should match your
+                desired concurrent throughput needs for reads and
+                writes.</para>
+</chapter>

doc/training-guide/module003-ch008-account-reaper.xml

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module003-ch008-account-reaper">
+    <title>Account Reaper</title>
+    <para>The Account Reaper removes data from deleted accounts in the
+        background.</para>
+    <para>An account is marked for deletion by a reseller issuing a
+        DELETE request on the account’s storage URL. This simply puts
+        the value DELETED into the status column of the account_stat
+        table in the account database (and replicas), indicating the
+        data for the account should be deleted later.</para>
+    <para>There is normally no set retention time and no undelete; it
+        is assumed the reseller will implement such features and only
+        call DELETE on the account once it is truly desired the
+        account’s data be removed. However, in order to protect the
+        Swift cluster accounts from an improper or mistaken delete
+        request, you can set a delay_reaping value in the
+        [account-reaper] section of the account-server.conf to delay
+        the actual deletion of data. At this time, there is no utility
+        to undelete an account; one would have to update the account
+        database replicas directly, setting the status column to an
+        empty string and updating the put_timestamp to be greater than
+        the delete_timestamp. (On the TODO list is writing a utility
+        to perform this task, preferably through a ReST call.)</para>
+    <para>The account reaper runs on each account server and scans the
+        server occasionally for account databases marked for deletion.
+        It will only trigger on accounts that server is the primary
+        node for, so that multiple account servers aren’t all trying
+        to do the same work at the same time. Using multiple servers
+        to delete one account might improve deletion speed, but
+        requires coordination so they aren’t duplicating effort. Speed
+        really isn’t as much of a concern with data deletion and large
+        accounts aren’t deleted that often.</para>
+    <para>The deletion process for an account itself is pretty
+        straightforward. For each container in the account, each
+        object is deleted and then the container is deleted. Any
+        deletion requests that fail won’t stop the overall process,
+        but will cause the overall process to fail eventually (for
+        example, if an object delete times out, the container won’t be
+        able to be deleted later and therefore the account won’t be
+        deleted either). The overall process continues even on a
+        failure so that it doesn’t get hung up reclaiming cluster
+        space because of one troublesome spot. The account reaper will
+        keep trying to delete an account until it eventually becomes
+        empty, at which point the database reclaim process within the
+        db_replicator will eventually remove the database
+        files.</para>
+    <para>Sometimes a persistent error state can prevent some object
+        or container from being deleted. If this happens, you will see
+        a message such as “Account &lt;name&gt; has not been reaped
+        since &lt;date&gt;” in the log. You can control when this is
+        logged with the reap_warn_after value in the [account-reaper]
+        section of the account-server.conf file. By default this is 30
+        days.</para>
+</chapter>

doc/training-guide/module003-ch009-replication.xml

@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module003-ch009-replication">
+    <title>Replication</title>
+    <para>Because each replica in swift functions independently, and
+        clients generally require only a simple majority of nodes
+        responding to consider an operation successful, transient
+        failures like network partitions can quickly cause replicas to
+        diverge. These differences are eventually reconciled by
+        asynchronous, peer-to-peer replicator processes. The
+        replicator processes traverse their local filesystems,
+        concurrently performing operations in a manner that balances
+        load across physical disks.</para>
+    <para>Replication uses a push model, with records and files
+        generally only being copied from local to remote replicas.
+        This is important because data on the node may not belong
+        there (as in the case of handoffs and ring changes), and a
+        replicator can’t know what data exists elsewhere in the
+        cluster that it should pull in. It’s the duty of any node that
+        contains data to ensure that data gets to where it belongs.
+        Replica placement is handled by the ring.</para>
+    <para>Every deleted record or file in the system is marked by a
+        tombstone, so that deletions can be replicated alongside
+        creations. The replication process cleans up tombstones after
+        a time period known as the consistency window. The consistency
+        window encompasses replication duration and how long transient
+        failure can remove a node from the cluster. Tombstone cleanup
+        must be tied to replication to reach replica
+        convergence.</para>
+    <para>If a replicator detects that a remote drive has failed, the
+        replicator uses the get_more_nodes interface for the ring to
+        choose an alternate node with which to synchronize. The
+        replicator can maintain desired levels of replication in the
+        face of disk failures, though some replicas may not be in an
+        immediately usable location. Note that the replicator doesn’t
+        maintain desired levels of replication when other failures,
+        such as entire node failures, occur because most failure are
+        transient.</para>
+    <para>Replication is an area of active development, and likely
+        rife with potential improvements to speed and
+        correctness.</para>
+    <para>There are two major classes of replicator - the db
+        replicator, which replicates accounts and containers, and the
+        object replicator, which replicates object data.</para>
+    <para><guilabel>DB Replication</guilabel></para>
+        <para>The first step performed by db replication is a low-cost
+            hash comparison to determine whether two replicas already
+            match. Under normal operation, this check is able to
+            verify that most databases in the system are already
+            synchronized very quickly. If the hashes differ, the
+            replicator brings the databases in sync by sharing records
+            added since the last sync point.</para>
+        <para>This sync point is a high water mark noting the last
+            record at which two databases were known to be in sync,
+            and is stored in each database as a tuple of the remote
+            database id and record id. Database ids are unique amongst
+            all replicas of the database, and record ids are
+            monotonically increasing integers. After all new records
+            have been pushed to the remote database, the entire sync
+            table of the local database is pushed, so the remote
+            database can guarantee that it is in sync with everything
+            with which the local database has previously
+            synchronized.</para>
+        <para>If a replica is found to be missing entirely, the whole
+            local database file is transmitted to the peer using
+            rsync(1) and vested with a new unique id.</para>
+        <para>In practice, DB replication can process hundreds of
+            databases per concurrency setting per second (up to the
+            number of available CPUs or disks) and is bound by the
+            number of DB transactions that must be performed.</para>
+        <para><guilabel>Object Replication</guilabel></para>
+        <para>The initial implementation of object replication simply
+            performed an rsync to push data from a local partition to
+            all remote servers it was expected to exist on. While this
+            performed adequately at small scale, replication times
+            skyrocketed once directory structures could no longer be
+            held in RAM. We now use a modification of this scheme in
+            which a hash of the contents for each suffix directory is
+            saved to a per-partition hashes file. The hash for a
+            suffix directory is invalidated when the contents of that
+            suffix directory are modified.</para>
+        <para>The object replication process reads in these hash
+            files, calculating any invalidated hashes. It then
+            transmits the hashes to each remote server that should
+            hold the partition, and only suffix directories with
+            differing hashes on the remote server are rsynced. After
+            pushing files to the remote server, the replication
+            process notifies it to recalculate hashes for the rsynced
+            suffix directories.</para>
+        <para>Performance of object replication is generally bound by
+            the number of uncached directories it has to traverse,
+            usually as a result of invalidated suffix directory
+            hashes. Using write volume and partition counts from our
+            running systems, it was designed so that around 2% of the
+            hash space on a normal node will be invalidated per day,
+            which has experimentally given us acceptable replication
+            speeds.</para>
+</chapter>

doc/training-guide/st-training-guides.xml

@@ -73,4 +73,8 @@
     <xi:include href="bk002-operator-training-guide.xml"/>
     <xi:include href="bk003-developer-training-guide.xml"/>
     <xi:include href="bk004-architect-training-guide.xml"/>
+    <xi:include href="module001-intro-openstack.xml"/>
+    <xi:include href="module002-ch000-openstack-networking.xml"/>
+    <xi:include href="module003-ch000-openstack-objstore.xml"/>
+    <xi:include href="lab000-openstack-training-labs.xml"/>
    </set>