[docs] Revise deployment host and target hosts chapter

1. Reorganise content
2. Update workflow diagrams

Change-Id: I65e3aee5fa9d53b3c0e6f2c1d026554989c1d4b4
Implements: blueprint osa-install-guide-overhaul

doc/source/install-guide-revised-draft/deploymenthost.rst

@@ -1,19 +1,21 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
-Chapter 2. Deployment host
+===============
-==========================
+Deployment host
+===============
 
-**Figure 2.1. Installation work flow**
+.. figure:: figures/installation-workflow-deploymenthost.png
+   :width: 100%
 
-.. image:: figures/workflow-deploymenthost.png
+   **Installation workflow**
 
-The OSA installation process recommends one deployment host. The
+When installing OpenStack in a production environment, we recommend using a
-deployment host contains Ansible and orchestrates the OpenStack-Ansible
+separate deployment host which contains Ansible and orchestrates the
-installation on the target hosts. We recommend using separate deployment and
+OpenStack-Ansible installation on the target hosts. In a test environment, we
-target hosts. You could alternatively use one of the target hosts, preferably
+prescribe using one of the infrastructure target hosts as the deployment host.
-one of the infrastructure variants, as the deployment host. To use a
+
-deployment host as a target host, follow the steps in `Chapter 3, Target
+To use a target host as a deployment host, follow the steps in `Chapter 3,
-hosts <targethosts.html>`_ on the deployment host.
+Target hosts <targethosts.html>`_ on the deployment host.
 
 Installing the operating system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

@@ -9,9 +9,9 @@ OpenStack-Ansible (OSA) installation.
 
 
 .. figure:: figures/installation-workflow-overview.png
-   :scale: 100
+   :width: 100%
 
-   Installation workflow
+   **Installation workflow**
 
 #. :doc:`Prepare deployment host <deploymenthost>`
 #. :doc:`Prepare target hosts <targethosts>`

doc/source/install-guide-revised-draft/overview.rst

@@ -1,8 +1,8 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
-=====================
+========
-Chapter 1. Overview
+Overview
-=====================
+========
 
 .. toctree::
 
@@ -14,7 +14,6 @@ Chapter 1. Overview
    overview-security.rst
    overview-workflow.rst
 
-
 --------------
 
 .. include:: navigation.txt

doc/source/install-guide-revised-draft/targethosts-networkconfig.rst

@@ -1,19 +1,143 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
-=================
+=====================
-Configuring hosts
+Network configuration
-=================
+=====================
+
+Production environment
+~~~~~~~~~~~~~~~~~~~~~~
+
+This example allows you to use your own parameters for the deployment.
+
+If you followed the previously proposed design, the following table shows
+bridges that are to be configured on hosts.
+
++-------------+-----------------------+-------------------------------------+
+| Bridge name | Best configured on    | With a static IP                    |
++=============+=======================+=====================================+
+| br-mgmt     | On every node         | Always                              |
++-------------+-----------------------+-------------------------------------+
+|             | On every storage node | When component is deployed on metal |
++ br-storage  +-----------------------+-------------------------------------+
+|             | On every compute node | Always                              |
++-------------+-----------------------+-------------------------------------+
+|             | On every network node | When component is deployed on metal |
++ br-vxlan    +-----------------------+-------------------------------------+
+|             | On every compute node | Always                              |
++-------------+-----------------------+-------------------------------------+
+|             | On every network node | Never                               |
++ br-vlan     +-----------------------+-------------------------------------+
+|             | On every compute node | Never                               |
++-------------+-----------------------+-------------------------------------+
+
+Example for 3 controller nodes and 2 compute nodes
+--------------------------------------------------
+
+- VLANs:
+
+  -  Host management: Untagged/Native
+  -  Container management: 10
+  -  Tunnels: 30
+  -  Storage: 20
+
+- Networks:
+
+  -  Host management: 10.240.0.0/22
+  -  Container management: 172.29.236.0/22
+  -  Tunnel: 172.29.240.0/22
+  -  Storage: 172.29.244.0/22
+
+- Addresses for the controller nodes:
+
+  -  Host management: 10.240.0.11 - 10.240.0.13
+  -  Host management gateway: 10.240.0.1
+  -  DNS servers: 69.20.0.164 69.20.0.196
+  -  Container management: 172.29.236.11 - 172.29.236.13
+  -  Tunnel: no IP (because IP exist in the containers, when the components
+     aren't deployed directly on metal)
+  -  Storage: no IP (because IP exist in the containers, when the components
+     aren't deployed directly on metal)
+
+- Addresses for the compute nodes:
+
+  -  Host management: 10.240.0.21 - 10.240.0.22
+  -  Host management gateway: 10.240.0.1
+  -  DNS servers: 69.20.0.164 69.20.0.196
+  -  Container management: 172.29.236.21 - 172.29.236.22
+  -  Tunnel: 172.29.240.21 - 172.29.240.22
+  -  Storage: 172.29.244.21 - 172.29.244.22
 
 
-With the information available on the design guide page, you are now
+.. TODO Update this section. Should this information be moved to the overview
-able to make the decisions to build your own OpenStack. There
+   chapter / network architecture section?
-are two examples given here: reference architecture (recommended) and
-single host architecture (simple).
 
-.. toctree::
+Modifying the network interfaces file
+-------------------------------------
 
-   targethosts-networkrefarch.rst
+After establishing initial host management network connectivity using
-   targethosts-networkexample.rst
+the ``bond0`` interface, modify the ``/etc/network/interfaces`` file.
+An example is provided below based on the production environment described
+in :ref:`host-layout`.
+
+.. TODO include example file
+
+Test environment
+~~~~~~~~~~~~~~~~
+
+This example uses the following parameters to configure networking on a
+single target host. See `Figure 3.2`_ for a visual representation of these
+parameters in the architecture.
+
+-  VLANs:
+
+   -  Host management: Untagged/Native
+
+   -  Container management: 10
+
+   -  Tunnels: 30
+
+   -  Storage: 20
+
+   Networks:
+
+   -  Host management: 10.240.0.0/22
+
+   -  Container management: 172.29.236.0/22
+
+   -  Tunnel: 172.29.240.0/22
+
+   -  Storage: 172.29.244.0/22
+
+   Addresses:
+
+   -  Host management: 10.240.0.11
+
+   -  Host management gateway: 10.240.0.1
+
+   -  DNS servers: 69.20.0.164 69.20.0.196
+
+   -  Container management: 172.29.236.11
+
+   -  Tunnel: 172.29.240.11
+
+   -  Storage: 172.29.244.11
+
+.. _Figure 3.2: targethosts-networkexample.html#fig_hosts-target-network-containerexample
+
+**Figure 3.2. Target host for infrastructure, networking, compute, and
+storage services**
+
+.. image:: figures/networkarch-container-external-example.png
+
+Modifying the network interfaces file
+-------------------------------------
+
+After establishing initial host management network connectivity using
+the ``bond0`` interface, modify the ``/etc/network/interfaces`` file.
+An example is provided below based on the test environment described
+in :ref:`host-layout`.
+
+.. TODO include example file
 
 
 --------------

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

@@ -1,183 +0,0 @@
-`Home <index.html>`_ OpenStack-Ansible Installation Guide
-
-=========================================
-Simple architecture: A single target host
-=========================================
-
-Overview
-~~~~~~~~
-
-This example uses the following parameters to configure networking on a
-single target host. See `Figure 3.2`_ for a visual representation of these
-parameters in the architecture.
-
--  VLANs:
-
-   -  Host management: Untagged/Native
-
-   -  Container management: 10
-
-   -  Tunnels: 30
-
-   -  Storage: 20
-
-   Networks:
-
-   -  Host management: 10.240.0.0/22
-
-   -  Container management: 172.29.236.0/22
-
-   -  Tunnel: 172.29.240.0/22
-
-   -  Storage: 172.29.244.0/22
-
-   Addresses:
-
-   -  Host management: 10.240.0.11
-
-   -  Host management gateway: 10.240.0.1
-
-   -  DNS servers: 69.20.0.164 69.20.0.196
-
-   -  Container management: 172.29.236.11
-
-   -  Tunnel: 172.29.240.11
-
-   -  Storage: 172.29.244.11
-
-.. _Figure 3.2: targethosts-networkexample.html#fig_hosts-target-network-containerexample
-
-**Figure 3.2. Target host for infrastructure, networking, compute, and
-storage services**
-
-.. image:: figures/networkarch-container-external-example.png
-
-Modifying the network interfaces file
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-After establishing the initial host management network connectivity using
-the ``bond0`` interface, modify the ``/etc/network/interfaces`` file as
-described in this procedure.
-
-Contents of the ``/etc/network/interfaces`` file:
-
-#. Physical interfaces:
-
-    .. code-block:: yaml
-
-        # Physical interface 1
-        auto eth0
-        iface eth0 inet manual
-            bond-master bond0
-            bond-primary eth0
-
-        # Physical interface 2
-        auto eth1
-        iface eth1 inet manual
-            bond-master bond1
-            bond-primary eth1
-
-        # Physical interface 3
-        auto eth2
-        iface eth2 inet manual
-            bond-master bond0
-
-        # Physical interface 4
-        auto eth3
-        iface eth3 inet manual
-            bond-master bond1
-
-#. Bonding interfaces:
-
-    .. code-block:: yaml
-
-        # Bond interface 0 (physical interfaces 1 and 3)
-        auto bond0
-        iface bond0 inet static
-            bond-slaves eth0 eth2
-            bond-mode active-backup
-            bond-miimon 100
-            bond-downdelay 200
-            bond-updelay 200
-            address 10.240.0.11
-            netmask 255.255.252.0
-            gateway 10.240.0.1
-            dns-nameservers 69.20.0.164 69.20.0.196
-
-        # Bond interface 1 (physical interfaces 2 and 4)
-        auto bond1
-        iface bond1 inet manual
-            bond-slaves eth1 eth3
-            bond-mode active-backup
-            bond-miimon 100
-            bond-downdelay 250
-            bond-updelay 250
-
-#. Logical (VLAN) interfaces:
-
-    .. code-block:: yaml
-
-        # Container management VLAN interface
-        iface bond0.10 inet manual
-            vlan-raw-device bond0
-
-        # OpenStack Networking VXLAN (tunnel/overlay) VLAN interface
-        iface bond1.30 inet manual
-            vlan-raw-device bond1
-
-        # Storage network VLAN interface (optional)
-        iface bond0.20 inet manual
-            vlan-raw-device bond0
-
-
-#. Bridge devices:
-
-    .. code-block:: yaml
-
-        # Container management bridge
-        auto br-mgmt
-        iface br-mgmt inet static
-            bridge_stp off
-            bridge_waitport 0
-            bridge_fd 0
-            # Bridge port references tagged interface
-            bridge_ports bond0.10
-            address 172.29.236.11
-            netmask 255.255.252.0
-            dns-nameservers 69.20.0.164 69.20.0.196
-
-        # OpenStack Networking VXLAN (tunnel/overlay) bridge
-        auto br-vxlan
-        iface br-vxlan inet static
-            bridge_stp off
-            bridge_waitport 0
-            bridge_fd 0
-            # Bridge port references tagged interface
-            bridge_ports bond1.30
-            address 172.29.240.11
-            netmask 255.255.252.0
-
-        # OpenStack Networking VLAN bridge
-        auto br-vlan
-        iface br-vlan inet manual
-            bridge_stp off
-            bridge_waitport 0
-            bridge_fd 0
-            # Bridge port references untagged interface
-            bridge_ports bond1
-
-        # Storage bridge
-        auto br-storage
-        iface br-storage inet static
-            bridge_stp off
-            bridge_waitport 0
-            bridge_fd 0
-            # Bridge port reference tagged interface
-            bridge_ports bond0.20
-            address 172.29.244.11
-            netmask 255.255.252.0
-
-
---------------
-
-.. include:: navigation.txt

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

@@ -1,207 +0,0 @@
-`Home <index.html>`_ OpenStack-Ansible Installation Guide
-
-======================
-Reference architecture
-======================
-
-Overview
-~~~~~~~~
-
-This example allows you to use your own parameters for the deployment.
-
-The following is a table of the bridges that are be configured on hosts, if
-you followed the previously proposed design.
-
-+-------------+-----------------------+-------------------------------------+
-| Bridge name | Best configured on    | With a static IP                    |
-+=============+=======================+=====================================+
-| br-mgmt     | On every node         | Always                              |
-+-------------+-----------------------+-------------------------------------+
-|             | On every storage node | When component is deployed on metal |
-+ br-storage  +-----------------------+-------------------------------------+
-|             | On every compute node | Always                              |
-+-------------+-----------------------+-------------------------------------+
-|             | On every network node | When component is deployed on metal |
-+ br-vxlan    +-----------------------+-------------------------------------+
-|             | On every compute node | Always                              |
-+-------------+-----------------------+-------------------------------------+
-|             | On every network node | Never                               |
-+ br-vlan     +-----------------------+-------------------------------------+
-|             | On every compute node | Never                               |
-+-------------+-----------------------+-------------------------------------+
-
-Modifying the network interfaces file
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-After establishing initial host management network connectivity using
-the ``bond0`` interface, modify the ``/etc/network/interfaces`` file as
-described in the following procedure.
-
-**Procedure 4.1. Modifying the network interfaces file**
-
-#. Physical interfaces:
-
-   .. code-block:: yaml
-
-       # Physical interface 1
-       auto eth0
-       iface eth0 inet manual
-           bond-master bond0
-           bond-primary eth0
-
-       # Physical interface 2
-       auto eth1
-       iface eth1 inet manual
-           bond-master bond1
-           bond-primary eth1
-
-       # Physical interface 3
-       auto eth2
-       iface eth2 inet manual
-           bond-master bond0
-
-       # Physical interface 4
-       auto eth3
-       iface eth3 inet manual
-           bond-master bond1
-
-#. Bonding interfaces:
-
-   .. code-block:: yaml
-
-       # Bond interface 0 (physical interfaces 1 and 3)
-       auto bond0
-       iface bond0 inet static
-           bond-slaves eth0 eth2
-           bond-mode active-backup
-           bond-miimon 100
-           bond-downdelay 200
-           bond-updelay 200
-           address HOST_IP_ADDRESS
-           netmask HOST_NETMASK
-           gateway HOST_GATEWAY
-           dns-nameservers HOST_DNS_SERVERS
-
-       # Bond interface 1 (physical interfaces 2 and 4)
-       auto bond1
-       iface bond1 inet manual
-           bond-slaves eth1 eth3
-           bond-mode active-backup
-           bond-miimon 100
-           bond-downdelay 250
-           bond-updelay 250
-
-   If not already complete, replace ``HOST_IP_ADDRESS``,
-   ``HOST_NETMASK``, ``HOST_GATEWAY``, and ``HOST_DNS_SERVERS``
-   with the appropriate configuration for the host management network.
-
-#. Logical (VLAN) interfaces:
-
-   .. code-block:: yaml
-
-       # Container management VLAN interface
-       iface bond0.CONTAINER_MGMT_VLAN_ID inet manual
-           vlan-raw-device bond0
-
-       # OpenStack Networking VXLAN (tunnel/overlay) VLAN interface
-       iface bond1.TUNNEL_VLAN_ID inet manual
-           vlan-raw-device bond1
-
-       # Storage network VLAN interface (optional)
-       iface bond0.STORAGE_VLAN_ID inet manual
-           vlan-raw-device bond0
-
-   Replace ``*_VLAN_ID`` with the appropriate configuration for the
-   environment.
-
-#. Bridge devices:
-
-   .. code-block:: yaml
-
-       # Container management bridge
-       auto br-mgmt
-       iface br-mgmt inet static
-           bridge_stp off
-           bridge_waitport 0
-           bridge_fd 0
-           # Bridge port references tagged interface
-           bridge_ports bond0.CONTAINER_MGMT_VLAN_ID
-           address CONTAINER_MGMT_BRIDGE_IP_ADDRESS
-           netmask CONTAINER_MGMT_BRIDGE_NETMASK
-           dns-nameservers CONTAINER_MGMT_BRIDGE_DNS_SERVERS
-
-       # OpenStack Networking VXLAN (tunnel/overlay) bridge
-       auto br-vxlan
-       iface br-vxlan inet static
-           bridge_stp off
-           bridge_waitport 0
-           bridge_fd 0
-           # Bridge port references tagged interface
-           bridge_ports bond1.TUNNEL_VLAN_ID
-           address TUNNEL_BRIDGE_IP_ADDRESS
-           netmask TUNNEL_BRIDGE_NETMASK
-
-       # OpenStack Networking VLAN bridge
-       auto br-vlan
-       iface br-vlan inet manual
-           bridge_stp off
-           bridge_waitport 0
-           bridge_fd 0
-           # Bridge port references untagged interface
-           bridge_ports bond1
-
-       # Storage bridge (optional)
-       auto br-storage
-       iface br-storage inet static
-           bridge_stp off
-           bridge_waitport 0
-           bridge_fd 0
-           # Bridge port reference tagged interface
-           bridge_ports bond0.STORAGE_VLAN_ID
-           address STORAGE_BRIDGE_IP_ADDRESS
-           netmask STORAGE_BRIDGE_NETMASK
-
-   Replace ``*_VLAN_ID``, ``*_BRIDGE_IP_ADDRESS``, and
-   ``*_BRIDGE_NETMASK``, ``*_BRIDGE_DNS_SERVERS`` with the
-   appropriate configuration for the environment.
-
-Example for 3 controller nodes and 2 compute nodes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-- VLANs:
-
-  -  Host management: Untagged/Native
-  -  Container management: 10
-  -  Tunnels: 30
-  -  Storage: 20
-
-- Networks:
-
-  -  Host management: 10.240.0.0/22
-  -  Container management: 172.29.236.0/22
-  -  Tunnel: 172.29.240.0/22
-  -  Storage: 172.29.244.0/22
-
-- Addresses for the controller nodes:
-
-  -  Host management: 10.240.0.11 - 10.240.0.13
-  -  Host management gateway: 10.240.0.1
-  -  DNS servers: 69.20.0.164 69.20.0.196
-  -  Container management: 172.29.236.11 - 172.29.236.13
-  -  Tunnel: no IP (because IP exist in the containers, when the components
-     aren't deployed directly on metal)
-  -  Storage: no IP (because IP exist in the containers, when the components
-     aren't deployed directly on metal)
-
-- Addresses for the compute nodes:
-
-  -  Host management: 10.240.0.21 - 10.240.0.22
-  -  Host management gateway: 10.240.0.1
-  -  DNS servers: 69.20.0.164 69.20.0.196
-  -  Container management: 172.29.236.21 - 172.29.236.22
-  -  Tunnel: 172.29.240.21 - 172.29.240.22
-  -  Storage: 172.29.244.21 - 172.29.244.22
-
---------------
-
-.. include:: navigation.txt

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

@@ -79,6 +79,8 @@ practices, refer to `GitHub's documentation on generating SSH keys`_.
 Configuring LVM
 ~~~~~~~~~~~~~~~
 
+.. TODO Change title to Configuring Storage and add content
+
 `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

doc/source/install-guide-revised-draft/targethosts.rst

@@ -4,18 +4,18 @@
 Target hosts
 ============
 
+.. figure:: figures/installation-workflow-targethosts.png
+   :width: 100%
+
+   **Installation workflow**
+
 .. toctree::
 
    targethosts-prepare.rst
    targethosts-networkconfig.rst
 
-**Figure 3.1. Installation workflow**
 
-.. image:: figures/workflow-targethosts.png
+On each target host, perform the following tasks:
-
-We recommend at least five target hosts to contain the
-OpenStack environment and supporting infrastructure for the OSA
-installation process. On each target host, perform the following tasks:
 
 -  Naming target hosts