Docs: Target hosts section - cleanup

As per discussion in the OSA docs summit session, clean up
of installation guide. This fixes typos, minor RST mark up
changes, and passive voice.

Change-Id: I8d341c306e3435b072224c41298beca1080abb2b

doc/source/install-guide/targethosts-network.rst

@@ -1,19 +1,23 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
+=======================
 Configuring the network
------------------------
+=======================
 
-This documentation section describes a recommended reference architecture.
+This section describes the recommended network architecture.
-Some components are mandatory, such as the bridges described below. Other
+Some components are mandatory, such as the bridges described below. We
-components aren't required but are strongly recommended, such as the bonded
+recommend other components such as a bonded network interface but this
-network interfaces. Deployers are strongly urged to follow the reference
+is not a requirement.
-design as closely as possible for production deployments.
+
+.. important::
+   
+   Follow the reference design as closely as possible for production deployments.
 
 Although Ansible automates most deployment operations, networking on
-target hosts requires manual configuration because it can vary
+target hosts requires manual configuration as it varies
 dramatically per environment. For demonstration purposes, these
 instructions use a reference architecture with example network interface
-names, networks, and IP addresses. Modify these values as needed for the
+names, networks, and IP addresses. Modify these values as needed for your
 particular environment.
 
 Bonded network interfaces
@@ -22,40 +26,39 @@ Bonded network interfaces
 The reference architecture includes bonded network interfaces, which
 use multiple physical network interfaces for better redundancy and throughput.
 Avoid using two ports on the same multi-port network card for the same bonded
-interface since a network card failure would affect both physical network
+interface since a network card failure affects both physical network
 interfaces used by the bond.
 
-The ``bond0`` interface will carry the traffic from the containers that
+The ``bond0`` interface carries traffic from the containers
-run the OpenStack infrastructure. Configure a static IP address on the
+running your OpenStack infrastructure. Configure a static IP address on the
 ``bond0`` interface from your management network.
 
-The ``bond1`` interface will carry the traffic from your virtual machines.
+The ``bond1`` interface carries traffic from your virtual machines.
-Don't configure a static IP on this interface since this bond will be used by
+Do not configure a static IP on this interface, since neutron uses this
-neutron to handle VLAN and VXLAN networks for virtual machines.
+bond to handle VLAN and VXLAN networks for virtual machines.
 
-Additional bridge networks are required for OpenStack-Ansible and those bridges
+Additional bridge networks are required for OpenStack-Ansible. These bridges
-will be connected to these two bonded network interfaces. See the following
+connect the two bonded network interfaces.
-section for the bridge configuration.
 
 Adding bridges
 ~~~~~~~~~~~~~~
 
-The combination of containers and flexible deployment options requires
+The combination of containers and flexible deployment options require
-implementation of advanced Linux networking features such as bridges and
+implementation of advanced Linux networking features, such as bridges and
 namespaces.
 
-*Bridges* provide layer 2 connectivity (similar to switches) among
+Bridges provide layer 2 connectivity (similar to switches) among
 physical, logical, and virtual network interfaces within a host. After
-creating a bridge, the network interfaces are virtually "plugged in" to
+creating a bridge, the network interfaces are virtually plugged in to
 it.
 
 OpenStack-Ansible uses bridges to connect physical and logical network
 interfaces on the host to virtual network interfaces within containers.
 
-*Namespaces* provide logically separate layer 3 environments (similar to
+Namespaces provide logically separate layer 3 environments (similar to
 routers) within a host. Namespaces use virtual interfaces to connect
 with other namespaces, including the host namespace. These interfaces,
-often called ``veth`` pairs, are virtually "plugged in" between
+often called ``veth`` pairs, are virtually plugged in between
 namespaces similar to patch cables connecting physical devices such as
 switches and routers.
 
@@ -72,7 +75,7 @@ Target hosts can contain the following network bridges:
 
 -  LXC internal ``lxcbr0``:
 
-   -  This bridge is **required**, but LXC will configure it automatically.
+   -  This bridge is **required**, but LXC configures it automatically.
 
    -  Provides external (typically internet) connectivity to containers.
 
@@ -89,32 +92,32 @@ Target hosts can contain the following network bridges:
    -  Provides management of and communication among infrastructure and
       OpenStack services.
 
-   -  Manually created and attaches to a physical or logical interface,
+   -  Manually creates and attaches to a physical or logical interface,
       typically a ``bond0`` VLAN subinterface. Also attaches to ``eth1``
-      in each container. As mentioned earlier, the container network interface
+      in each container. The container network interface
       is configurable in ``openstack_user_config.yml``.
 
 -  Storage ``br-storage``:
 
    -  This bridge is *optional*, but recommended.
 
-   -  Provides segregated access to block storage devices between
+   -  Provides segregated access to Block Storage devices between
       Compute and Block Storage hosts.
 
-   -  Manually created and attaches to a physical or logical interface,
+   -  Manually creates and attaches to a physical or logical interface,
       typically a ``bond0`` VLAN subinterface. Also attaches to ``eth2``
-      in each associated container. As mentioned earlier, the container network
+      in each associated container. The container network
       interface is configurable in ``openstack_user_config.yml``.
 
--  OpenStack Networking tunnel/overlay ``br-vxlan``:
+-  OpenStack Networking tunnel ``br-vxlan``:
 
    -  This bridge is **required**.
 
-   -  Provides infrastructure for VXLAN tunnel/overlay networks.
+   -  Provides infrastructure for VXLAN tunnel networks.
 
-   -  Manually created and attaches to a physical or logical interface,
+   -  Manually creates and attaches to a physical or logical interface,
       typically a ``bond1`` VLAN subinterface. Also attaches to
-      ``eth10`` in each associated container. As mentioned earlier, the
+      ``eth10`` in each associated container. The
       container network interface is configurable in
       ``openstack_user_config.yml``.
 
@@ -124,15 +127,15 @@ Target hosts can contain the following network bridges:
 
    -  Provides infrastructure for VLAN networks.
 
-   -  Manually created and attaches to a physical or logical interface,
+   -  Manually creates and attaches to a physical or logical interface,
       typically ``bond1``. Attaches to ``eth11`` for vlan type networks
       in each associated container. It does not contain an IP address because
-      it only handles layer 2 connectivity.  As mentioned earlier, the
+      it only handles layer 2 connectivity. The
       container network interface is configurable in
       ``openstack_user_config.yml``.
 
-   -  This interface can support flat networks as well, though additional
+   -  This interface supports flat networks with additional
-      bridge configuration will be needed. More details are available here:
+      bridge configuration. More details are available here:
       :ref:`network_configuration`.
 
 
@@ -145,16 +148,16 @@ to provide network connectivity to the OpenStack deployment:
 .. image:: figures/networkarch-container-external.png
 
 OpenStack-Ansible deploys the compute service on the physical host rather than
-in a container. The following image shows how the bridges are used for
+in a container. The following image shows how to use bridges for
 network connectivity:
 
 .. image:: figures/networkarch-bare-external.png
 
 The following image shows how the neutron agents work with the bridges
-``br-vlan`` and ``br-vxlan``. As a reminder, OpenStack Networking (neutron) is
+``br-vlan`` and ``br-vxlan``. OpenStack Networking (neutron) is
-configured to use a DHCP agent, L3 agent and Linux Bridge agent within a
+configured to use a DHCP agent, L3 agent, and Linux Bridge agent within a
-``networking-agents`` container. You can see how the DHCP agents can provide
+``networking-agents`` container. The image shows how DHCP agents provide
-information (IP addresses and DNS servers) to the instances, but also how
+information (IP addresses and DNS servers) to the instances, and how
 routing works on the image:
 
 .. image:: figures/networking-neutronagents.png

doc/source/install-guide/targethosts-networkexample.rst

@@ -1,7 +1,8 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
+========================================
 Configuring the network on a target host
-----------------------------------------
+========================================
 
 This example uses the following parameters to configure networking on a
 single target host. See `Figure 3.2, "Target hosts for infrastructure,

doc/source/install-guide/targethosts-networkrefarch.rst

@@ -1,7 +1,8 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
+======================
 Reference architecture
-----------------------
+======================
 
 After establishing initial host management network connectivity using
 the ``bond0`` interface, modify the ``/etc/network/interfaces`` file as

doc/source/install-guide/targethosts-prepare.rst

@@ -1,38 +1,34 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
+==========================
 Preparing the target hosts
---------------------------
+==========================
 
-All target hosts will need a properly configured operating system as well as
+The following section describes the installation and configuration of
-some additional configurations that are noted in the following sections.
+operating systems for the target hosts. 
 
 Installing the operating system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Install the Ubuntu Server 14.04 (Trusty Tahr) LTS 64-bit operating
-system on the target host with at least one network interface configured
+system on the target host. Configure at least one network interface
-to access the Internet or suitable local repositories.
+to access the internet or suitable local repositories. 
 
-On target hosts without local (console) access, We recommend
+We recommend adding the Secure Shell (SSH) server packages to the
-adding the Secure Shell (SSH) server packages to the installation.
+installation on target hosts without local (console) access.
 
 Configuring the operating system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Upgrade system packages, check the kernel version, install additional
-software packages, and configure NTP.
-
 #. Upgrade system packages and kernel:
 
    .. code-block:: shell-session
 
        # apt-get dist-upgrade
 
-#. Check the kernel version. It should be ``3.13.0-34-generic`` or
+#. Ensure the kernel version is ``3.13.0-34-generic`` or later.
-   later.
 
-#. Install additional software packages if not already installed during
+#. Install additional software packages:
-   operating system installation:
 
    .. code-block:: shell-session
 
@@ -54,14 +50,13 @@ software packages, and configure NTP.
 Deploying SSH keys
 ~~~~~~~~~~~~~~~~~~
 
-Ansible uses Secure Shell (SSH) for connectivity between the deployment
+Ansible uses SSH for connectivity between the deployment and target hosts.
-and target hosts.
 
 #. Copy the contents of the public key file on the deployment host to
    the ``/root/.ssh/authorized_keys`` file on each target host.
 
 #. Test public key authentication from the deployment host to each
-   target host. SSH should provide a shell without asking for a
+   target host. SSH provides a shell without asking for a
    password.
 
 For more information on how to generate an SSH keypair as well as best
@@ -74,15 +69,17 @@ Configuring LVM
 
 `Logical Volume Manager (LVM)`_ allows a single device to be split into multiple
 logical volumes which appear as a physical storage device to the operating
-system. The Block Storage (cinder) service as well as the LXC containers that
+system. The Block Storage (cinder) service, as well as the LXC containers that
-run the OpenStack infrastructure can optionally use LVM for their data storage.
+run the OpenStack infrastructure, can optionally use LVM for their data storage.
 
-.. note:: OpenStack-Ansible automatically configures LVM on the nodes, and
+.. note::
+
+   OpenStack-Ansible automatically configures LVM on the nodes, and
    overrides any existing LVM configuration. If you had a customized LVM
    configuration, edit the generated configuration file as needed.
 
 #. To use the optional Block Storage (cinder) service, create an LVM
-   volume group named *cinder-volumes* on the Block Storage host. A
+   volume group named ``cinder-volumes`` on the Block Storage host. A
    metadata size of 2048 must be specified during physical volume
    creation. For example:
 
@@ -91,9 +88,9 @@ run the OpenStack infrastructure can optionally use LVM for their data storage.
        # pvcreate --metadatasize 2048 physical_volume_device_path
        # vgcreate cinder-volumes physical_volume_device_path
 
-#. Optionally, create an LVM volume group named *lxc* for container file
+#. Optionally, create an LVM volume group named ``lxc`` for container file
-   systems. If the lxc volume group does not exist, containers will be
+   systems. If the ``lxc`` volume group does not exist, containers are
-   automatically installed into the file system under */var/lib/lxc* by
+   automatically installed into the file system under ``/var/lib/lxc`` by
    default.
 
 .. _Logical Volume Manager (LVM): https://en.wikipedia.org/wiki/Logical_Volume_Manager_(Linux)

doc/source/install-guide/targethosts.rst

@@ -1,7 +1,8 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
+=======================
 Chapter 3. Target hosts
------------------------
+=======================
 
 .. toctree::
 
@@ -15,21 +16,21 @@ Chapter 3. Target hosts
 
 .. image:: figures/workflow-targethosts.png
 
-The OSA installation process recommends at least five target
+We recommend at least five target hosts to contain the
-hosts that will contain the OpenStack environment and supporting
+OpenStack environment and supporting infrastructure for the OSA
-infrastructure. On each target host, perform the following tasks:
+installation process. On each target host, perform the following tasks:
 
--  Naming target hosts.
+-  Naming target hosts
 
--  Install the operating system.
+-  Install the operating system
 
--  Generate and set up security measures.
+-  Generate and set up security measures
 
--  Update the operating system and install additional software packages.
+-  Update the operating system and install additional software packages
 
--  Create LVM volume groups.
+-  Create LVM volume groups
 
--  Configure networking devices.
+-  Configure networking devices
 
 --------------