Add a section on co-locating services

fixes bug 988053

As in the bug request, people are often interested in running
services from different OpenStack projects on one piece of kit.

This patch adds a new section in common on co-locating services,
explaining the catches and things to look out for.
It's then linked from the compute install guide's architecture
section, and the install guide's assumption section.

Change-Id: I42a2843cb69fffd523a18143dc41e5275d9e5215

doc/src/docbkx/common/colocating-services.xml

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section 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="co-locating-services">
+    <?dbhtml stop-chunking?>
+    <title>Co-locating services</title>
+    <para>While in a best-practice deployment, each OpenStack project's services
+    would live on a different machine, this is not always practical.
+    For example, in small deployments there might be too few machines
+    available, or a limited number of public IP addresses. Components from
+    different OpenStack projects are not necessarily engineered to be able to be
+    co-located, however many users report success with a variety of
+    deployment scenarios.
+    </para>
+    <para>
+    The following is a series of pointers to be used when co-location
+    of services from different OpenStack projects on the same machine
+     is a must:
+    <itemizedlist>
+    <listitem><para>Ensure dependencies aren't in conflict. The OpenStack 
+    Continuous Integration team does attempt to ensure there is no
+    conflict - so if you see issues during package installation,
+    consider filing a bug.</para></listitem>
+    <listitem><para>Monitor your systems and ensure they are not overloaded.
+    Some parts of OpenStack use a lot of CPU time (eg Swift Proxy
+    Servers), while others are IO focused (eg Swift Object Server).
+    Try to balance these so they complement each other.
+    </para></listitem>
+    <listitem><para>Beware of security. Different parts of OpenStack assume
+     different security models. For example, Swift assumes the storage
+    nodes will be on a private network and does not provide additonal
+    security between nodes in the cluster.</para></listitem>
+    <listitem><para>Ensure the ports you are running the services on don't
+    conflict. Most ports used by OpenStack are configurable.</para></listitem>
+    </itemizedlist>
+    </para>
+</section>
+

doc/src/docbkx/openstack-compute-admin/bk-compute-adminguide.xml

@@ -188,4 +188,4 @@
     <xi:include href="computetutorials.xml"/>
     <xi:include href="../common/support.xml"/>
     <xi:include href="../common/support-compute.xml"/>
-</book>
+   </book>

doc/src/docbkx/openstack-compute-admin/computeinstall.xml

@@ -80,6 +80,8 @@
           <imagedata fileref="figures/NOVA_compute_nodes.png" scale="40"/>
         </imageobject>
       </inlinemediaobject></para>
+
+    <xi:include href="../common/colocating-services.xml"/>
   </section>
 
   <section xml:id="service-architecture">

doc/src/docbkx/openstack-install/ch_assumptions.xml

@@ -89,4 +89,5 @@
         service running in a multi-node install, though if high
         availability for networks is required, there are additional
         options. </para>
+    <xi:include href="../common/colocating-services.xml"/>
 </chapter>