Merge "Docs: Overview section - cleanup"

doc/source/install-guide/overview-hostlayout.rst

@@ -1,9 +1,10 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
+===========
 Host layout
------------
+===========
 
-The recommended layout contains a minimum of five hosts (or servers).
+We recommend a layout that contains a minimum of five hosts (or servers):
 
 -  Three control plane infrastructure hosts
 
@@ -11,22 +12,21 @@ The recommended layout contains a minimum of five hosts (or servers).
 
 -  One compute host
 
-To use the optional Block Storage (cinder) service, a sixth host is
+If using the optional Block Storage (cinder) service, we recommend
-recommended. Block Storage hosts require an LVM volume group named
+the use of a sixth host. Block Storage hosts require an LVM volume group named
-*cinder-volumes*. See `the section called "Installation
+``cinder-volumes``. See `the section called "Installation
 requirements" <overview-requirements.html>`_ and `the section
 called "Configuring LVM" <targethosts-configlvm.html>`_ for more information.
 
-The hosts are called *target hosts* because Ansible deploys the OSA
+The hosts are called target hosts because Ansible deploys the OSA
-environment within these hosts. The OSA environment also recommends a
+environment within these hosts. We recommend a
-*deployment host* from which Ansible orchestrates the deployment
+deployment host from which Ansible orchestrates the deployment
 process. One of the target hosts can function as the deployment host.
 
-At least one load balancer **must** be used to manage the traffic among
+Use at least one load balancer to manage the traffic among
-the target hosts. This can be any type of load balancer (hardware, haproxy,
+the target hosts. You can use any type of load balancer such as a hardware
-etc). While OpenStack-Ansible has playbooks and roles for deploying haproxy,
+appliance or HAProxy. We recommend using physical load balancers for
-we recommend for deployers to use physical load balancers when moving to
+production environments.
-production.
 
 Infrastructure Control Plane target hosts contain the following
 services:

doc/source/install-guide/overview-osa.rst

@@ -1,21 +1,21 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
+=======================
 About OpenStack-Ansible
------------------------
+=======================
 
-OpenStack-Ansible uses the Ansible IT automation framework to
+OpenStack-Ansible (OSA) uses the Ansible IT automation framework to
 deploy an OpenStack environment on Ubuntu Linux. OpenStack components are
 installed into Linux Containers (LXC) for isolation and ease of
 maintenance.
 
 This documentation is intended for deployers of the OpenStack-Ansible
 deployment system who are interested in installing an OpenStack environment.
-The document is for informational purposes only and is provided "AS IS."
 
 Third-party trademarks and tradenames appearing in this document are the
 property of their respective owners. Such third-party trademarks have
 been printed in caps or initial caps and are used for referential
-purposes only. We do not intend our use or display of other companies"
+purposes only. We do not intend our use or display of other companies'
 tradenames, trademarks, or service marks to imply a relationship with,
 or endorsement or sponsorship of us by, these other companies.
 
@@ -28,18 +28,18 @@ provides an automation platform to simplify system and application
 deployment. Ansible manages systems using Secure Shell (SSH)
 instead of unique protocols that require remote daemons or agents.
 
-Ansible uses *playbooks* written in the YAML language for orchestration.
+Ansible uses playbooks written in the YAML language for orchestration.
 For more information, see `Ansible - Intro to
 Playbooks <http://docs.ansible.com/playbooks_intro.html>`_.
 
 In this guide, we refer to the host running Ansible playbooks as
-the *deployment host* and the hosts on which Ansible installs OSA as the
+the deployment host and the hosts on which Ansible installs OSA as the
-*target hosts*.
+target hosts.
 
 A recommended minimal layout for deployments involves five target
 hosts in total: three infrastructure hosts, one compute host, and one
 logging host. All hosts will need at least one networking interface, but
-multiple bonded interfaces are recommended. More information on setting up
+we recommend multiple bonded interfaces. More information on setting up
 target hosts can be found in `the section called "Host layout"`_.
 
 For more information on physical, logical, and virtual network
@@ -54,7 +54,7 @@ Linux Containers (LXC)
 ~~~~~~~~~~~~~~~~~~~~~~
 
 Containers provide operating-system level virtualization by enhancing
-the concept of **chroot** environments, which isolate resources and file
+the concept of ``chroot`` environments, which isolate resources and file
 systems for a particular group of processes without the overhead and
 complexity of virtual machines. They access the same kernel, devices,
 and file systems on the underlying host and provide a thin operational
@@ -65,7 +65,7 @@ virtualization on Linux using kernel namespaces and includes the
 following features:
 
 -  Resource isolation including CPU, memory, block I/O, and network
-   using *cgroups*.
+   using ``cgroups``.
 
 -  Selective connectivity to physical and virtual network devices on the
    underlying physical host.

doc/source/install-guide/overview-requirements.rst

@@ -1,19 +1,22 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
+=========================
 Installation requirements
--------------------------
+=========================
 
-The minimum software requirements for OpenStack-Ansible are well defined, but
+.. note::
-hardware requirements will vary based on the size of the OpenStack deployment.
+
+   These are the minimum requirements for OpenStack-Ansible. Larger
+   deployments require additional resources.
 
 CPU requirements
 ~~~~~~~~~~~~~~~~
 
-Compute hosts should have multi-core processors that have `hardware-assisted
+Compute hosts have multi-core processors that have `hardware-assisted
 virtualization extensions`_ available. These extensions provide a significant
 performance boost and improve security in virtualized environments.
 
-Infrastructure hosts should have multi-core processors for the best
+Infrastructure hosts have multi-core processors for best
 performance. Some services, such as MySQL, greatly benefit from additional CPU
 cores and other technologies, such as `Hyper-threading`_.
 
@@ -23,7 +26,7 @@ cores and other technologies, such as `Hyper-threading`_.
 Disk requirements
 ~~~~~~~~~~~~~~~~~
 
-Different hosts will have different disk space requirements based on the
+Different hosts have different disk space requirements based on the
 services running on each host:
 
 Deployment hosts
@@ -31,23 +34,23 @@ Deployment hosts
   repository content and additional required software.
 
 Compute hosts
-  Disk space requirements will vary depending on the total number of instances
+  Disk space requirements vary depending on the total number of instances
   running on each host and the amount of disk space allocated to each instance.
-  Compute hosts should have at least 100GB of disk space available at an
+  Compute hosts have at least 100GB of disk space available at an
-  absolute minimum. Deployers should consider disks that provide higher
+  absolute minimum. Consider disks that provide higher
   throughput with lower latency, such as SSD drives in a RAID array.
 
 Storage hosts
   Hosts running the Block Storage (cinder) service often consume the most disk
-  space in OpenStack environments. As with compute hosts, deployers should
+  space in OpenStack environments. As with compute hosts,
   choose disks that provide the highest I/O throughput with the lowest latency
-  for storage hosts. Storage hosts should contain 1TB of disk space at a
+  for storage hosts. Storage hosts contain 1TB of disk space at a
   minimum.
 
 Infrastructure hosts
   The OpenStack control plane contains storage-intensive services, such as
   the Image (glance) service as well as MariaDB. These control plane hosts
-  should have 100GB of disk space available at a minimum.
+  have 100GB of disk space available at a minimum.
 
 Logging hosts
   An OpenStack-Ansible deployment generates a significant amount of logging.
@@ -56,48 +59,50 @@ Logging hosts
   need additional disk space to hold live and rotated (historical) log files.
   In addition, the storage performance must be enough to keep pace with the
   log traffic coming from various hosts and containers within the OpenStack
-  environment. Deployers should reserve at least 50GB of disk space for storing
+  environment. Reserve a minimum of 50GB of disk space for storing
-  logs on the logging hosts, but this minimum will grow as additional hosts are
+  logs on the logging hosts. 
-  deployed.
 
-Hosts that provide Block Storage (cinder) volumes should have logical volume
+   
-manager (LVM) support. Those hosts must have a *cinder-volumes* volume group
+Hosts that provide Block Storage (cinder) volumes must have logical volume
+manager (LVM) support. Ensure those hosts have a ``cinder-volumes`` volume group
 that OpenStack-Ansible can configure for use with cinder.
 
-Each control plane host will run services inside LXC containers. By default,
+Each control plane host runs services inside LXC containers. The container
-the container filesystems are deployed onto the root filesystem of each control
+filesystems are deployed by default onto the root filesystem of each control
-plane hosts. Deployers have the option to deploy those container filesystems
+plane hosts. You have the option to deploy those container filesystems
-into logical volumes by creating a volume group called *lxc*. OpenStack-Ansible
+into logical volumes by creating a volume group called ``lxc``. OpenStack-Ansible
-will create a 5GB logical volume for the filesystem of each container running
+creates a 5GB logical volume for the filesystem of each container running
 on the host.
 
 Network requirements
 ~~~~~~~~~~~~~~~~~~~~
 
-It is possible to deploy an OpenStack environment with only one physical
+.. note::
-network interface. This works for small environments but it will cause problems
+
-when the environment grows.
+   You can deploy an OpenStack environment with only one physical
+   network interface. This works for small environments, but it can cause
+   problems when your environment grows.
 
 For the best performance, reliability and scalability, deployers should
 consider a network configuration that contains the following features:
 
 * Bonded network interfaces: Increases performance and/or reliability
-  (dependent on bonding architecture)
+  (dependent on bonding architecture).
 
 * VLAN offloading: Increases performance by adding and removing VLAN tags in
-  hardware, rather than in the server's main CPU
+  hardware, rather than in the server's main CPU.
 
 * Gigabit or 10 Gigabit Ethernet: Supports higher network speeds, which can
   also improve storage performance when using the Block Storage (cinder)
-  service
+  service.
 
 * Jumbo frames: Increases network performance by allowing more data to be sent
-  in each packet
+  in each packet.
 
 Software requirements
 ~~~~~~~~~~~~~~~~~~~~~
 
-All hosts within an OpenStack-Ansible environment must meet the following
+Ensure all hosts within an OpenStack-Ansible environment meet the following
 minimum requirements:
 
 * Ubuntu 14.04 LTS (Trusty Tahr)

doc/source/install-guide/overview-security.rst

@@ -1,14 +1,15 @@
 `Home <index.html>`__ OpenStack-Ansible Installation Guide
 
+========
 Security
---------
+========
 
 The OpenStack-Ansible project provides several security features for
-OpenStack deployments.  This section of documentation covers some of those
+OpenStack deployments. This section of documentation covers those
 features and how they can benefit deployers of various sizes.
 
-Security requirements will always differ between deployers.  For deployers
+Security requirements always differ between deployers. If you require
-that need additional security measures in place, please refer to the official
+additional security measures, refer to the official
 `OpenStack Security Guide`_ for additional resources.
 
 AppArmor
@@ -16,14 +17,14 @@ AppArmor
 
 The Linux kernel offers multiple `security modules`_ (LSMs) that that set
 `mandatory access controls`_ (MAC) on Linux systems.  The OpenStack-Ansible
-project configures `AppArmor`_, a Linux security module, to provide additional
+project configures `AppArmor`_. AppArmor is a Linux security module that
-security on LXC container hosts.  AppArmor allows administrators to set
+provides additional security on LXC container hosts. AppArmor allows
-specific limits and policies around what resources a particular application
+administrators to set specific limits and policies around what resources a
-can access.  Any activity outside the allowed policies is denied at the kernel
+particular application can access. Any activity outside the allowed policies
-level.
+is denied at the kernel level.
 
-In OpenStack-Ansible, AppArmor profiles are applied that limit the actions
+AppArmor profiles that are applied in OpenStack-Ansible limit the actions
-that each LXC container may take on a system.  This is done within the
+that each LXC container may take on a system. This is done within the
 `lxc_hosts role`_.
 
 .. _security modules: https://en.wikipedia.org/wiki/Linux_Security_Modules
@@ -34,9 +35,9 @@ that each LXC container may take on a system.  This is done within the
 Encrypted communication
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Data is encrypted while in transit between some OpenStack services in
+While in transit, data is encrypted between some OpenStack services in
-OpenStack-Ansible deployments.  Not all communication between all services is
+OpenStack-Ansible deployments. Not all communication between all services is
-currently encrypted.  For more details on what traffic is encrypted, and how
+encrypted. For more details on what traffic is encrypted, and how
 to configure SSL certificates, refer to the documentation section titled
 `Securing services with SSL certificates`_.
 
@@ -46,7 +47,7 @@ Host security hardening
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 Deployers can apply security hardening to OpenStack infrastructure and compute
-hosts using the openstack-ansible-security role. The purpose of the role is to
+hosts using the ``openstack-ansible-security`` role. The purpose of the role is to
 apply as many security configurations as possible without disrupting the
 operation of an OpenStack deployment.
 
@@ -61,9 +62,9 @@ limit the damage that could be caused if an attacker gained access to a set of
 credentials.
 
 OpenStack-Ansible configures unique username and password combinations for
-each service that talks to RabbitMQ and Galera/MariaDB.  Each service that
+each service that talks to RabbitMQ and Galera/MariaDB. Each service that
 connects to RabbitMQ uses a separate virtual host for publishing and consuming
-messages.  The MariaDB users for each service are only granted access to the
+messages. The MariaDB users for each service are only granted access to the
 database(s) that they need to query.
 
 .. _principle of least privilege: https://en.wikipedia.org/wiki/Principle_of_least_privilege
@@ -74,8 +75,12 @@ Securing network access to OpenStack services
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 OpenStack environments expose many service ports and API endpoints to the
-network. **Deployers must limit access to these resources and expose them only
+network. 
-to trusted users and networks.**
+
+.. note::
+   
+   Deployers must limit access to these resources and expose them only
+   to trusted users and networks.
 
 The resources within an OpenStack environment can be divided into two groups:
 
@@ -98,13 +103,12 @@ The resources within an OpenStack environment can be divided into two groups:
    * MariaDB
    * RabbitMQ
 
-Users must be able to access certain public API endpoints, such as the Nova or
+To manage instances, you are able to access certain public API endpoints, such as
-Neutron API, to manage instances. Deployers should configure firewalls to allow
+the Nova or Neutron API. Configure firewalls to limit network access to
-access to these services, but that access should be limited to the fewest
+these services.
-networks possible.
 
-Other services, such as MariaDB and RabbitMQ, **must be segmented away from
+Other services, such as MariaDB and RabbitMQ, must be segmented away from
-direct user access**. Deployers must configure a firewall to only allow
+direct user access. You must configure a firewall to only allow
 connectivity to these services within the OpenStack environment itself. This
 reduces an attacker's ability to query or manipulate data in OpenStack's
 critical database and queuing services, especially if one of these services has

doc/source/install-guide/overview-workflow.rst

@@ -1,7 +1,8 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
+=====================
 Installation workflow
----------------------
+=====================
 
 This diagram shows the general workflow associated with an
 OpenStack-Ansible (OSA) installation.
@@ -23,7 +24,7 @@ OpenStack-Ansible (OSA) installation.
 Network ranges
 ~~~~~~~~~~~~~~
 
-For consistency, the following IP addresses and hostnames will be
+For consistency, the following IP addresses and hostnames are
 referred to in this installation workflow.
 
 +-----------------------+-----------------+

doc/source/install-guide/overview.rst

@@ -1,7 +1,8 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
+===================
 Chapter 1. Overview
--------------------
+===================
 
 .. toctree::