From 2703e4b84072f2822b26749a0142ad4e4bddbb4c Mon Sep 17 00:00:00 2001 From: Alexandra Date: Thu, 28 Apr 2016 14:55:48 +1000 Subject: [PATCH] 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 --- .../install-guide/targethosts-network.rst | 87 ++++++++++--------- .../targethosts-networkexample.rst | 3 +- .../targethosts-networkrefarch.rst | 3 +- .../install-guide/targethosts-prepare.rst | 45 +++++----- doc/source/install-guide/targethosts.rst | 21 ++--- 5 files changed, 81 insertions(+), 78 deletions(-) diff --git a/doc/source/install-guide/targethosts-network.rst b/doc/source/install-guide/targethosts-network.rst index 195f3119e9..c4ffb98732 100644 --- a/doc/source/install-guide/targethosts-network.rst +++ b/doc/source/install-guide/targethosts-network.rst @@ -1,19 +1,23 @@ `Home `_ OpenStack-Ansible Installation Guide +======================= Configuring the network ------------------------ +======================= -This documentation section describes a recommended reference architecture. -Some components are mandatory, such as the bridges described below. Other -components aren't required but are strongly recommended, such as the bonded -network interfaces. Deployers are strongly urged to follow the reference -design as closely as possible for production deployments. +This section describes the recommended network architecture. +Some components are mandatory, such as the bridges described below. We +recommend other components such as a bonded network interface but this +is not a requirement. + +.. 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 -run the OpenStack infrastructure. Configure a static IP address on the +The ``bond0`` interface carries traffic from the containers +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. -Don't configure a static IP on this interface since this bond will be used by -neutron to handle VLAN and VXLAN networks for virtual machines. +The ``bond1`` interface carries traffic from your virtual machines. +Do not configure a static IP on this interface, since neutron uses this +bond to handle VLAN and VXLAN networks for virtual machines. -Additional bridge networks are required for OpenStack-Ansible and those bridges -will be connected to these two bonded network interfaces. See the following -section for the bridge configuration. +Additional bridge networks are required for OpenStack-Ansible. These bridges +connect the two bonded network interfaces. Adding bridges ~~~~~~~~~~~~~~ -The combination of containers and flexible deployment options requires -implementation of advanced Linux networking features such as bridges and +The combination of containers and flexible deployment options require +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 - bridge configuration will be needed. More details are available here: + - This interface supports flat networks with additional + 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 -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 -information (IP addresses and DNS servers) to the instances, but also how +``br-vlan`` and ``br-vxlan``. OpenStack Networking (neutron) is +configured to use a DHCP agent, L3 agent, and Linux Bridge agent within a +``networking-agents`` container. The image shows how DHCP agents provide +information (IP addresses and DNS servers) to the instances, and how routing works on the image: .. image:: figures/networking-neutronagents.png diff --git a/doc/source/install-guide/targethosts-networkexample.rst b/doc/source/install-guide/targethosts-networkexample.rst index e60d4c8482..2ce0d94243 100644 --- a/doc/source/install-guide/targethosts-networkexample.rst +++ b/doc/source/install-guide/targethosts-networkexample.rst @@ -1,7 +1,8 @@ `Home `_ 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, diff --git a/doc/source/install-guide/targethosts-networkrefarch.rst b/doc/source/install-guide/targethosts-networkrefarch.rst index 09ed0fb93d..151966cbeb 100644 --- a/doc/source/install-guide/targethosts-networkrefarch.rst +++ b/doc/source/install-guide/targethosts-networkrefarch.rst @@ -1,7 +1,8 @@ `Home `_ OpenStack-Ansible Installation Guide +====================== Reference architecture ----------------------- +====================== After establishing initial host management network connectivity using the ``bond0`` interface, modify the ``/etc/network/interfaces`` file as diff --git a/doc/source/install-guide/targethosts-prepare.rst b/doc/source/install-guide/targethosts-prepare.rst index 47c3d88cbe..19e3de9a66 100644 --- a/doc/source/install-guide/targethosts-prepare.rst +++ b/doc/source/install-guide/targethosts-prepare.rst @@ -1,38 +1,34 @@ `Home `_ OpenStack-Ansible Installation Guide +========================== Preparing the target hosts --------------------------- +========================== -All target hosts will need a properly configured operating system as well as -some additional configurations that are noted in the following sections. +The following section describes the installation and configuration of +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 -to access the Internet or suitable local repositories. +system on the target host. Configure at least one network interface +to access the internet or suitable local repositories. -On target hosts without local (console) access, We recommend -adding the Secure Shell (SSH) server packages to the installation. +We recommend adding the Secure Shell (SSH) server packages to the +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 - later. +#. Ensure the kernel version is ``3.13.0-34-generic`` or later. -#. Install additional software packages if not already installed during - operating system installation: +#. Install additional software packages: .. 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 -and target hosts. +Ansible uses SSH for connectivity between the deployment 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 -run the OpenStack infrastructure can optionally use LVM for their data storage. +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. -.. 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 - systems. If the lxc volume group does not exist, containers will be - automatically installed into the file system under */var/lib/lxc* by +#. Optionally, create an LVM volume group named ``lxc`` for container file + systems. If the ``lxc`` volume group does not exist, containers are + 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) diff --git a/doc/source/install-guide/targethosts.rst b/doc/source/install-guide/targethosts.rst index ec7fc6a82a..ccc055cefd 100644 --- a/doc/source/install-guide/targethosts.rst +++ b/doc/source/install-guide/targethosts.rst @@ -1,7 +1,8 @@ `Home `_ 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 -hosts that will contain the OpenStack environment and supporting -infrastructure. 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. +- 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 --------------