Last edits for O'Reilly before turning over to production 3/3/14

Change-Id: Ifeb2b9cf7ed330642aa942ba66e010810a42b18e

doc/openstack-ops/app_roadmaps.xml

@@ -328,7 +328,7 @@ the Icehouse release and perhaps further afield.</para>
         committee and technical leads of the projects.</para>
     </section>
         <section xml:id="aspects-to-watch">
-                <title>Aspects to watch</title>
+                <title>Aspects to Watch</title>
                 <para>You want to keep an eye on these areas improving within
                         OpenStack. The best ways to "watch" roadmaps for each
                         project is to look at the blueprints that are being
@@ -336,7 +336,7 @@ the Icehouse release and perhaps further afield.</para>
                         learn from PTL webinars that follow the OpenStack
                         Summits twice a year.</para>
                 <section xml:id="roadmap-driver-improvements">
-                        <title>Driver quality improvements</title>
+                        <title>Driver Quality Improvements</title>
                         <para>A major quality push has occurred across drivers
                                 and plugins in Block Storage, Compute and
                                 Networking. Particularly, developers of Compute
@@ -431,11 +431,12 @@ the Icehouse release and perhaps further afield.</para>
         </section>
         <section xml:id="roadmap-nova-v3-api">
                 <title>Compute V3 API</title>
-                <para>The 3rd version of the Compute API will be released in
+                <para>The 3rd version of the Compute API was broadly
-                experimental status with Icehouse. Though the V2 API will
+                discussed and worked on during the Havana and Icehouse
-                remain for two-to-three releases, this is the best time to
+                release cycles. Current discussions indicate that the V2 API will
-                evaluate the new API and provide comments while it can be more
+                remain for many releases, but this is a great time to
-                easily changed. Of particular note is the decision that the V3
+                evaluate the Compute API and provide comments while it
+                is being defined. Of particular note is the decision that the V3
                 API will not support XML messages - being JSON only. This was
                 based on the poor testing of existing XML responses in the V2
                 API, and lack of effort to continue to develop and maintain an
@@ -447,17 +448,17 @@ the Icehouse release and perhaps further afield.</para>
         <para>Continues to improve and you may consider using it for greenfield
                 deployments.</para>
         </section>
-        <section xml:id="roadmap-savana">
+        <section xml:id="roadmap-savanna">
-        <title>Hadoop-as-a-Service (Savana)</title>
+        <title>Hadoop-as-a-Service (Savanna for now with a rename coming)</title>
                 <para>A much-requested answer to Big Data problems, a dedicated
                         team has been making solid progress on a
                         Hadoop-as-a-Service project.</para>
         </section>
         <section xml:id="roadmap-baremetal">
-        <title>Bare-metal deployment (Ironic)</title>
+        <title>Bare-metal Deployment (Ironic)</title>
         <para>Though Bare-metal deployment has been widely lauded, and
-        development continues, the project to replace Compute's bare-metal
+        development continues, the project to replace the Compute bare-metal
-        driver will likely not graduate in Icehouse. A particular blueprint to
+        driver will not graduate in Icehouse. A particular blueprint to
         follow is <link xlink:href="https://blueprints.launchpad.net/ironic/+spec/migration-from-nova">
         Migration path from Nova's BM driver</link>, which tracks the ability
         to move to the new project from an existing bare metal deployment.</para>
@@ -475,7 +476,7 @@ the Icehouse release and perhaps further afield.</para>
         <section xml:id="roadmap-marconi">
         <title>Messaging as a Service (Marconi)</title>
                 <para>A service to provide queues of messages and notifications
-                        has entered 'incubation', meaning if the next two
+                        has entered 'incubation', meaning if the upcoming
                         development cycles are successful, it will be released
                         in Juno.</para>
         </section>
@@ -496,7 +497,7 @@ the Icehouse release and perhaps further afield.</para>
                 control for volumes.</para>
         </section>
         <section xml:id="roadmap-python-sdk">
-        <title>Toward a 'proper' Python SDK</title>
+        <title>Toward a 'Proper' Python SDK</title>
         <para>Though many successfully use the various python-*client code as
         an effective SDK for interacting with OpenStack, consistency between
         the projects and documentation availability waxes and wanes. To combat

doc/openstack-ops/ch_arch_cloud_controller.xml

@@ -295,7 +295,7 @@
     <section xml:id="message_queue">
         <title>Message Queue</title>
         <para>Most OpenStack services communicate with each other using the
-            Message Queue. As an example, Compute communicates to block storage
+            Message Queue. For example, Compute communicates to block storage
             services and networking services through the message queue. Also,
             you can optionally enable notifications for any service. RabbitMQ,
             Qpid, and 0mq are all popular choices for a message queue service.
@@ -434,18 +434,18 @@
             supports:</para>
         <itemizedlist role="compact">
             <listitem>
-                <para>OpenStack Object Storage. Allows you to store
+                <para>OpenStack Object Storage: Allows you to store
                     images as objects.</para>
             </listitem>
             <listitem>
-                <para>File system. Uses any traditional file system to
+                <para>File system: Uses any traditional file system to
                     store the images as files.</para>
             </listitem>
             <listitem>
-                <para>S3. Allows you to fetch images from Amazon S3.</para>
+                <para>S3: Allows you to fetch images from Amazon S3.</para>
             </listitem>
             <listitem>
-                <para>HTTP. Allows you to fetch images from a web
+                <para>HTTP: Allows you to fetch images from a web
                     server. You cannot write images by using this
                     mode.</para>
             </listitem>

doc/openstack-ops/ch_arch_compute_nodes.xml

@@ -18,7 +18,7 @@
         Compute cloud, providing the processing, memory, network and
         storage resources to run instances.</para>
     <section xml:id="cpu_choice">
-        <title>CPU Choice</title>
+        <title>Choosing a CPU</title>
         <para>The type of CPU in your compute node is a very important
             choice. First, ensure the CPU supports virtualization by
             way of <emphasis>VT-x</emphasis> for Intel chips and
@@ -54,7 +54,7 @@
     </section>
     <?hard-pagebreak?>
     <section xml:id="hypervisor_choice">
-        <title>Hypervisor Choice</title>
+        <title>Choosing a Hypervisor</title>
         <para>A hypervisor provides software to manage virtual machine access to
             the underlying hardware. The hypervisor creates, manages, and
             monitors virtual machines. OpenStack Compute supports many
@@ -96,7 +96,6 @@
                 single hypervisor at a time.</para>
         </note>
     </section>
-
     <section xml:id="instance_storage">
         <title>Instance Storage Solutions</title>
         <para>As part of the procurement for a compute cluster, you
@@ -223,7 +222,6 @@
                 </listitem>
             </itemizedlist>
         </section>
-
         <section xml:id="on_compute_node_storage_nonshared">
             <title>On Compute Node Storage – Non-shared File System</title>
             <para>In this option, each compute node is specified with enough

doc/openstack-ops/ch_arch_examples.xml

@@ -26,8 +26,8 @@
     documenting, as well as to provide the scope for this guide. Both of the
     offered architecture examples are currently running in production and
     serving users.</para>
-    <para>As always, refer to the Glossary if you are unclear about any of the
+    <tip><para>As always, refer to the Glossary if you are unclear about any of the
-    terminology mentioned in these architectures.</para>
+    terminology mentioned in these architectures.</para></tip>
     <xi:include href="section_arch_example-nova.xml"/>
     <xi:include href="section_arch_example-neutron.xml"/>
     <section xml:id="example_archs_conclusion">

doc/openstack-ops/ch_arch_scaling.xml

@@ -197,7 +197,10 @@
     <?hard-pagebreak?>
     <section xml:id="segregate_cloud">
         <title>Segregating Your Cloud</title>
-        <para>Use one of the following OpenStack methods to segregate
+        <para>When you want to offer users different regions to provide legal
+            considerations for data storage, redundancy across earthquake fault
+            lines, or for low-latency API calls, you segregate your cloud.
+            Use one of the following OpenStack methods to segregate
             your cloud: <emphasis>cells</emphasis>,
                 <emphasis>regions</emphasis>,
                 <emphasis>zones</emphasis> and <emphasis>host
@@ -431,26 +434,26 @@
                         each resources. It is left up to you to avoid
                         putting a host in multiple aggregates that define
                         different values for the same resource.</para>
-                    <para>This is the first half of the equation. To get
+                    <para>This is the first half of the equation. To
-                        instance types that are guaranteed a particular ratio
+                        get instance types that are guaranteed a
-                        you must set the <parameter>extra_specs</parameter> in
+                        particular ratio you must set the <parameter>extra_specs</parameter>
-                        the instance type to the key value pair you want to
+                        in the instance type to the key value pair you want to match in the aggregate.
-                        match in the aggregate. For example if you define extra
+                        For example if you define extra specs
-                        specs <parameter>cpu_allocation_ratio</parameter> to
+                        <parameter>cpu_allocation_ratio</parameter> to
-                        '1.0' then instances of that type will only run in
+                        '1.0' then instances of that type will only
-                        aggregates where the metadata key
+                        run in aggregates where the metadata key
-                            <parameter>cpu_allocation_ratio</parameter> is also
+                        <parameter>cpu_allocation_ratio</parameter>
-                        defined as '1.0'. In practice it is better to define an
+                        is also defined as '1.0'. In practice it is
-                        additional key value pair in the aggregate metadata to
+                        better to define an additional key value pair
-                        match on rather than match directly on
+                        in the aggregate metadata to match on rather
-                            <parameter>cpu_allocation_ratio</parameter> or
+                        than match directly on <parameter>cpu_allocation_ratio</parameter>
-                            <parameter>core_allocation_ratio</parameter>. This
+                        or <parameter>core_allocation_ratio</parameter>.
-                        allows better abstraction. For example, defining a key
+                        This allows better abstraction. For example by
-                            <parameter>overcommit</parameter> and setting value
+                        defining a key <parameter>overcommit</parameter>
-                        of 'high', 'medium', and 'low' you could then tune the
+                        and setting value of 'high', 'medium', or 'low'
-                        numeric allocation ratios in the aggregates without also
+                        you could then tune the numeric allocation
-                        needing to change all instance types relating to
+                        ratios in the aggregates without also needing
-                        them.</para>
+                        to change all instance types relating to them.</para>
                 </listitem>
             </itemizedlist>
             <note><para>Previously, all services had an availability zone. Currently,

doc/openstack-ops/ch_ops_network_troubleshooting.xml

@@ -832,7 +832,7 @@ bytes</userinput></screen>
  174.143.194.225 (47)</computeroutput></screen>
     </section>
     <section xml:id="trouble_shooting_ovs">
-      <title>Trouble shooting Open vSwitch</title>
+      <title>Troubleshooting Open vSwitch</title>
       <para>Open vSwitch as used in the OpenStack Networking Service examples
             above is full-featured multilayer virtual switch licensed under the
             open source Apache 2.0 license. Full documentation can be found at

doc/openstack-ops/ch_ops_projects_users.xml

@@ -157,7 +157,7 @@
         <tbody>
           <tr>
             <td>
-              <para>Fixed Ips</para>
+              <para>Fixed IPs</para>
             </td>
             <td>
               <para>Number of fixed IP addresses allowed per tenant. This number

doc/openstack-ops/ch_ops_user_facing.xml

@@ -601,7 +601,7 @@ Optional snapshot description. (Default=None)</computeroutput></screen>
 | tenant_id              | 98333a1a28e746fa8c629c83a818ad57                    /
 | updated                | 2013-03-01T19:28:26Z                                \
 | user_id                | a1ef823458d24a68955fec6f3d390019                    /
-+------------------------+-----------------------------------------------------\</computeroutput>
++------------------------+----------------------------------------------------\</computeroutput>
             </screen>
             <para>In this case looking at the "fault" message shows
                 NoValidHost indicating the scheduler was unable to

doc/openstack-ops/part_architecture.xml

@@ -20,6 +20,32 @@
         needs, and this part of the book aims to shine light on many of the
         decisions you will need to make during the process.
       </para>
+      <para>To design, deploy, and configure OpenStack, administrators
+        must understand the logical architecture. A diagram can help
+        you envision all the integrated services within
+        OpenStack and how they interact with each other.</para>
+      <para>OpenStack modules are one of the following types:</para>
+      <itemizedlist role="compact">
+        <listitem>
+          <para>Daemon. Runs as a background process. On Linux platforms, a daemon is
+            usually installed as a service.</para>
+        </listitem>
+        <listitem>
+          <para>Script. Installs a virtual environment and runs tests.</para>
+        </listitem>
+        <listitem>
+          <para>Command-line interface (CLI). Enables users to submit API
+            calls to OpenStack services through commands.</para>
+        </listitem>
+      </itemizedlist>
+      <para>As shown, end users can interact through the dashboard,
+        CLIs, and APIs. All services authenticate through a common
+        Identity Service and individual services interact with each
+        other through public APIs, except where privileged
+        administrator commands are necessary. The diagram shows the
+        most common, but not the only, logical architecture for an
+        OpenStack cloud.</para>
+      <!-- O'Reilly production to insert image here -->
     </partintro>
     <xi:include href="ch_arch_examples.xml"/>
     <xi:include href="ch_arch_provision.xml"/>

doc/openstack-ops/preface_ops.xml

@@ -18,7 +18,7 @@
     <section xml:id="introduction-to-openstack">
         <title>Introduction to OpenStack</title>
         <para>OpenStack believes in open source, open design, open development, all in an open
-            community encouraging participation by anyone. The long-term vision for OpenStack
+            community which encourages participation by anyone. The long-term vision for OpenStack
             is to produce a ubiquitous open source cloud computing platform that meets the needs of public and
             private cloud providers regardless of size. OpenStack services control large pools of
             compute, storage, and networking resources throughout a data center.</para>
@@ -34,7 +34,7 @@
             computing platform for both public and private clouds. By focusing on ease of
             implementation, massive scalability, a variety of rich features and tremendous
             extensibility, the project aims to deliver a practical and reliable cloud solution for
-            all types of organisations.</para>
+            all types of organisations.</para></section>
         <section xml:id="preface_getting_started"><title>Getting Started with OpenStack</title>
         <para>As an open source project, one of the unique aspects about OpenStack is that there are
             many different levels you can begin to engage with it &mdash; you don't have to do everything
@@ -94,7 +94,6 @@
         number of options might be bewildering at first.</para>
                 </section>
         </section>
-            </section>
     <section xml:id="who-this-book-is-for">
         <title>Who This Book Is For</title>
         <para>This book is for those of you starting to run OpenStack clouds as
@@ -429,7 +428,6 @@
             </listitem>
         </itemizedlist>
     </section>
-
     <section xml:id="how-to-contribute-to-ops-guide">
         <title>How to Contribute to This Book</title>
         <para>The genesis of this book was an in-person event, but now that the
@@ -457,5 +455,4 @@
             if you know how to fix it. Also, a member of the OpenStack
             doc-core team can triage the doc bug.</para>
     </section>
-
 </preface>