[Docs] Simplify overview page

This modifies the overview section to be one page instead of
4 long sections. We just refer to the architecture reference
for details about the architecture.

Change-Id: I1f5da9acaa677b2cd752cda30c33eba846a96eb4

deploy-guide/source/app-aboutosa.rst

@@ -1,3 +1,5 @@
+.. _app-aboutosa:
+
 =======================
 About OpenStack-Ansible
 =======================
@@ -52,47 +54,3 @@ instead of unique protocols that require remote daemons or agents.
 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>`_.
-
-This guide refers to the following types of hosts:
-
-* `Deployment host`, which runs the Ansible playbooks
-* `Target hosts`, where Ansible installs OpenStack services and infrastructure
-  components
-
-Linux containers (LXC)
-~~~~~~~~~~~~~~~~~~~~~~
-
-Containers provide operating-system level virtualization by enhancing
-the concept of ``chroot`` environments. Containers 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
-layer built around a set of rules.
-
-The LXC project implements operating-system-level
-virtualization on Linux by using kernel namespaces, and it includes the
-following features:
-
-* Resource isolation including CPU, memory, block I/O, and network, by
-  using ``cgroups``
-* Selective connectivity to physical and virtual network devices on the
-  underlying physical host
-* Support for a variety of backing stores, including Logical Volume Manager
-  (LVM)
-* Built on a foundation of stable Linux technologies with an active
-  development and support community
-
-Installation workflow
-~~~~~~~~~~~~~~~~~~~~~
-
-The following diagram shows the general workflow of an OpenStack-Ansible
-installation.
-
-.. figure:: figures/installation-workflow-overview.png
-   :width: 100%
-
-#. :ref:`deployment-host`
-#. :ref:`target-hosts`
-#. :ref:`configure`
-#. :ref:`run-playbooks`
-#. :ref:`verify-operation`

deploy-guide/source/app.rst

@@ -6,3 +6,4 @@ Appendices
    :maxdepth: 2
 
    app-resources.rst
+   app-aboutosa.rst

deploy-guide/source/overview-network-arch.rst

@@ -1,87 +0,0 @@
-.. _network-architecture:
-
-====================
-Network architecture
-====================
-
-Although Ansible automates most deployment operations, networking on target
-hosts requires manual configuration because it varies from one use case to
-another. This section describes the network configuration that must be
-implemented on all target hosts.
-
-For more information about how networking works, see the
-:dev_docs:`OpenStack-Ansible Reference Architecture, section Container
-Networking <reference/architecture/index.html>`.
-
-Host network bridges
-~~~~~~~~~~~~~~~~~~~~
-
-OpenStack-Ansible uses bridges to connect physical and logical network
-interfaces on the host to virtual network interfaces within containers.
-Target hosts are configured with the following network bridges.
-
-
-*  LXC internal: ``lxcbr0``
-
-   The ``lxcbr0`` bridge is **required**, but OpenStack-Ansible configures it
-   automatically. It provides external (typically Internet) connectivity to
-   containers.
-
-   This bridge does not directly attach to any physical or logical
-   interfaces on the host because iptables handles connectivity. It
-   attaches to ``eth0`` in each container.
-
-   The container network that the bridge attaches to is configurable in the
-   ``openstack_user_config.yml`` file in the ``provider_networks``
-   dictionary.
-
-*  Container management: ``br-mgmt``
-
-   The ``br-mgmt`` bridge is **required**. It provides management of and
-   communication between the infrastructure and OpenStack services.
-
-   The bridge attaches to a physical or logical interface, typically a
-   ``bond0`` VLAN subinterface. It also attaches to ``eth1`` in each container.
-
-   The container network interface that the bridge attaches to is configurable
-   in the ``openstack_user_config.yml`` file.
-
-*  Storage:``br-storage``
-
-   The ``br-storage`` bridge is **optional**, but recommended for production
-   environments. It provides segregated access to Block Storage devices
-   between OpenStack services and Block Storage devices.
-
-   The bridge attaches to a physical or logical interface, typically a
-   ``bond0`` VLAN subinterface. It also attaches to ``eth2`` in each
-   associated container.
-
-   The container network interface that the bridge attaches to is configurable
-   in the ``openstack_user_config.yml`` file.
-
-*  OpenStack Networking tunnel: ``br-vxlan``
-
-   The ``br-vxlan`` bridge is **required** if the environment is configured to
-   allow projects to create virtual networks. It provides the interface for
-   virtual (VXLAN) tunnel networks.
-
-   The bridge attaches to a physical or logical interface, typically a
-   ``bond1`` VLAN subinterface. It also attaches to ``eth10`` in each
-   associated container.
-
-   The container network interface it attaches to is configurable in
-   the ``openstack_user_config.yml`` file.
-
-*  OpenStack Networking provider: ``br-vlan``
-
-   The ``br-vlan`` bridge is **required**. It provides infrastructure for VLAN
-   tagged or flat (no VLAN tag) networks.
-
-   The bridge attaches to a physical or logical interface, typically ``bond1``.
-   It attaches to ``eth11`` for VLAN type networks in each associated
-   container. It is not assigned an IP address because it handles only
-   layer 2 connectivity.
-
-   The container network interface that the bridge attaches to is configurable
-   in the ``openstack_user_config.yml`` file.
-

deploy-guide/source/overview-requirements.rst

@@ -1,10 +1,3 @@
-=============================================
-Installation requirements and recommendations
-=============================================
-
-This section describes software requirements, hardware recommendations, and
-network recommendations for running OpenStack in a production environment.
-
 Software requirements
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -54,60 +47,79 @@ CPU recommendations
 .. _hardware-assisted virtualization extensions: https://en.wikipedia.org/wiki/Hardware-assisted_virtualization
 .. _Hyper-threading: https://en.wikipedia.org/wiki/Hyper-threading
 
-Disk recommendations
+Storage/disk recommendations
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Different hosts have different disk space requirements based on the
 services running on each host:
 
 Deployment hosts
-  A minimum of ``10 GB`` of disk space is sufficient for holding the
+----------------
-  OpenStack-Ansible repository content and additional required software.
+
+A minimum of ``10 GB`` of disk space is sufficient for holding the
+OpenStack-Ansible repository content and additional required software.
 
 Compute hosts
-  Disk space requirements depend on the total number of instances
+-------------
-  running on each host and the amount of disk space allocated to each instance.
 
-  * Compute hosts must have a minimum of ``1 TB`` of disk space available.
+Disk space requirements depend on the total number of instances
+running on each host and the amount of disk space allocated to each instance.
 
-  * Consider disks that provide higher I/O throughput with lower latency,
+.. tip ::
-    such as SSD drives in a RAID array.
+
+   Consider disks that provide higher I/O 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.
 
-  * Storage hosts must have a minimum of ``1 TB`` of disk space.
+Hosts running the Block Storage (cinder) service often consume the most disk
+space in OpenStack environments.
 
-  * As with Compute hosts, choose disks that provide the highest
+Storage hosts must have a minimum of ``1 TB`` of disk space.
-    I/O throughput with the lowest latency.
 
-Infrastructure (control plane) hosts
+.. tip ::
-  The OpenStack control plane contains storage-intensive services, such as the
-  Image service (glance), and MariaDB. These hosts must have a minimum of
-  ``100 GB`` of disk space.
 
-Logging hosts
+   As with Compute hosts, choose disks that provide the highest
-  An OpenStack-Ansible deployment generates a significant amount of log
+   I/O throughput with the lowest latency.
-  information. Logs come from a variety of sources, including services running
-  in containers, the containers themselves, and the physical hosts. Logging
-  hosts need sufficient disk space to hold live and rotated (historical) log
-  files. In addition, the storage performance must be able to keep pace with
-  the log traffic coming from various hosts and containers within the OpenStack
-  environment. Reserve a minimum of ``50 GB`` of disk space for storing logs on
-  the logging hosts.
 
 Hosts that provide Block Storage volumes must have Logical Volume
 Manager (LVM) support. Ensure that hosts have a ``cinder-volume`` volume
 group that OpenStack-Ansible can configure for use with Block Storage.
 
-Each infrastructure (control plane) host runs services inside LXC containers.
+Infrastructure (control plane) hosts
+------------------------------------
+
+The OpenStack control plane contains storage-intensive services, such as the
+Image service (glance), and MariaDB. These hosts must have a minimum of
+``100 GB`` of disk space.
+
+Each infrastructure (control plane) host runs services inside machine containers.
 The container file systems are deployed by default on the root file system of
 each control plane host. You have the option to deploy those container file
 systems into logical volumes by creating a volume group called lxc.
 OpenStack-Ansible creates a 5 GB logical volume for the file system of each
 container running on the host.
 
+.. tip ::
+
+   Other technologies leveraging copy-on-write can be used to reduce
+   the disk space requirements on machine containers.
+
+
+Logging hosts
+-------------
+
+An OpenStack-Ansible deployment generates a significant amount of log
+information. Logs come from a variety of sources, including services running
+in containers, the containers themselves, and the physical hosts. Logging
+hosts need sufficient disk space to hold live and rotated (historical) log
+files. In addition, the storage performance must be able to keep pace with
+the log traffic coming from various hosts and containers within the OpenStack
+environment. Reserve a minimum of ``50 GB`` of disk space for storing logs on
+the logging hosts.
+
+
 Network recommendations
 ~~~~~~~~~~~~~~~~~~~~~~~
 

deploy-guide/source/overview.rst

@@ -2,10 +2,32 @@
 Overview
 ========
 
-.. toctree::
+.. note::
 
-   overview-osa.rst
+   For essential background reading to help understand the service and storage
-   overview-requirements.rst
+   architecture, please read
-   overview-service-architecture.rst
+   `OpenStack-Ansible Architecture in its reference guide
-   overview-network-arch.rst
+   <https://docs.openstack.org/openstack-ansible/latest/reference/architecture/index.html>`_
-   overview-storage-arch.rst
+   If you'd like to understand when OpenStack-Ansible would be a good fit for your
+   organisation, please read the appendix
+   ":ref:`app-aboutosa`".
+
+This guide refers to the following types of hosts:
+
+* `Deployment host`, which runs the Ansible playbooks
+* `Target hosts`, where Ansible installs OpenStack services and infrastructure
+  components
+
+Installation workflow
+=====================
+
+The following diagram shows the general workflow of an OpenStack-Ansible
+installation.
+
+.. figure:: figures/installation-workflow-overview.png
+   :width: 100%
+
+Installation requirements and recommendations
+=============================================
+
+.. include:: overview-requirements.rst

deploy-guide/source/targethosts-networkconfig.rst

@@ -29,3 +29,77 @@ Networking <reference/architecture/index.html>`.
 
 For use case examples, refer to
 :dev_docs:`User Guides <user/index.html>`.
+
+
+
+Host network bridges
+~~~~~~~~~~~~~~~~~~~~
+
+OpenStack-Ansible uses bridges to connect physical and logical network
+interfaces on the host to virtual network interfaces within containers.
+Target hosts are configured with the following network bridges.
+
+
+*  LXC internal: ``lxcbr0``
+
+   The ``lxcbr0`` bridge is **required**, but OpenStack-Ansible configures it
+   automatically. It provides external (typically Internet) connectivity to
+   containers.
+
+   This bridge does not directly attach to any physical or logical
+   interfaces on the host because iptables handles connectivity. It
+   attaches to ``eth0`` in each container.
+
+   The container network that the bridge attaches to is configurable in the
+   ``openstack_user_config.yml`` file in the ``provider_networks``
+   dictionary.
+
+*  Container management: ``br-mgmt``
+
+   The ``br-mgmt`` bridge is **required**. It provides management of and
+   communication between the infrastructure and OpenStack services.
+
+   The bridge attaches to a physical or logical interface, typically a
+   ``bond0`` VLAN subinterface. It also attaches to ``eth1`` in each container.
+
+   The container network interface that the bridge attaches to is configurable
+   in the ``openstack_user_config.yml`` file.
+
+*  Storage:``br-storage``
+
+   The ``br-storage`` bridge is **optional**, but recommended for production
+   environments. It provides segregated access to Block Storage devices
+   between OpenStack services and Block Storage devices.
+
+   The bridge attaches to a physical or logical interface, typically a
+   ``bond0`` VLAN subinterface. It also attaches to ``eth2`` in each
+   associated container.
+
+   The container network interface that the bridge attaches to is configurable
+   in the ``openstack_user_config.yml`` file.
+
+*  OpenStack Networking tunnel: ``br-vxlan``
+
+   The ``br-vxlan`` bridge is **required** if the environment is configured to
+   allow projects to create virtual networks. It provides the interface for
+   virtual (VXLAN) tunnel networks.
+
+   The bridge attaches to a physical or logical interface, typically a
+   ``bond1`` VLAN subinterface. It also attaches to ``eth10`` in each
+   associated container.
+
+   The container network interface it attaches to is configurable in
+   the ``openstack_user_config.yml`` file.
+
+*  OpenStack Networking provider: ``br-vlan``
+
+   The ``br-vlan`` bridge is **required**. It provides infrastructure for VLAN
+   tagged or flat (no VLAN tag) networks.
+
+   The bridge attaches to a physical or logical interface, typically ``bond1``.
+   It attaches to ``eth11`` for VLAN type networks in each associated
+   container. It is not assigned an IP address because it handles only
+   layer 2 connectivity.
+
+   The container network interface that the bridge attaches to is configurable
+   in the ``openstack_user_config.yml`` file.

doc/source/reference/architecture/container-networking.rst

@@ -1,6 +1,5 @@
 .. _container-networking:
 
-====================
 Container networking
 ====================
 

doc/source/reference/architecture/index.rst

@@ -11,5 +11,8 @@ was architected in this way.
 .. toctree::
    :maxdepth: 1
 
+   service-arch.rst
+   storage-arch.rst
    security.rst
    container-networking.rst
+

doc/source/reference/architecture/service-arch.rst

@@ -1,14 +1,12 @@
-.. _service-architecture:
-
-====================
 Service architecture
 ====================
 
 Introduction
 ~~~~~~~~~~~~
+
 OpenStack-Ansible has a flexible deployment configuration model that
-can deploy all services in separate LXC containers or on designated hosts
+can deploy all services in separate machine containers or on designated hosts
-without using LXC containers, and all network traffic either on a single
+without using containers, and all network traffic either on a single
 network interface or on many network interfaces.
 
 This flexibility enables deployers to choose how to deploy OpenStack in the
@@ -90,33 +88,6 @@ OpenStack-Ansible deploys the following infrastructure components:
 OpenStack services
 ~~~~~~~~~~~~~~~~~~
 
-OSA is able to deploy the following OpenStack services:
+OSA is able to deploy a multitude of services.
-
+Have a look at the role maturity matrix to know the status of the
-* Bare Metal (`ironic`_)
+service you want to deploy.
-* Block Storage (`cinder`_)
-* Compute (`nova`_)
-* Container Infrastructure Management (`magnum`_)
-* Dashboard (`horizon`_)
-* Data Processing (`sahara`_)
-* Identity (`keystone`_)
-* Image (`glance`_)
-* Networking (`neutron`_)
-* Object Storage (`swift`_)
-* Orchestration (`heat`_)
-* Telemetry (`aodh`_, `ceilometer`_, `gnocchi`_)
-
-.. _ironic: http://docs.openstack.org/developer/ironic
-.. _cinder: http://docs.openstack.org/developer/cinder
-.. _nova: http://docs.openstack.org/developer/nova
-.. _magnum: http://docs.openstack.org/developer/magnum
-.. _horizon: http://docs.openstack.org/developer/horizon
-.. _sahara: http://docs.openstack.org/developer/sahara
-.. _keystone: http://docs.openstack.org/developer/keystone
-.. _glance: http://docs.openstack.org/developer/glance
-.. _neutron: http://docs.openstack.org/developer/neutron
-.. _swift: http://docs.openstack.org/developer/swift
-.. _heat: http://docs.openstack.org/developer/heat
-.. _aodh: http://docs.openstack.org/developer/aodh
-.. _ceilometer: http://docs.openstack.org/developer/ceilometer
-.. _gnocchi: http://docs.openstack.org/developer/gnocchi
-

doc/source/reference/architecture/storage-arch.rst

@@ -1,4 +1,3 @@
-====================
 Storage architecture
 ====================
 
@@ -164,4 +163,3 @@ the storage device, the Compute host, the hypervisor, and the instance.
    +----+---------------------------------------------------------------------+
    | 3  | The hypervisor presents the disk as a device to the instance.       |
    +----+---------------------------------------------------------------------+
-