[DOCS] Update to installation guide

Adds new appendix for role docs

Implements: blueprint osa-install-guide-overhaul

Change-Id: Ideebdf6ecd4c843116ee229c07d13f97a680fd7f
Closes-bug: 1624242
Closes-bug: 1620234

doc/source/install-guide/app-advanced-config-options.rst

@@ -9,3 +9,4 @@ Appendix E: Advanced configuration
    app-advanced-config-security
    app-advanced-config-sslcertificates
    app-advanced-config-affinity
+   app-advanced-role-docs

doc/source/install-guide/app-advanced-role-docs.rst

@@ -0,0 +1,92 @@
+.. _role-docs:
+
+==============================
+Advanced service configuration
+==============================
+
+OpenStack-Ansible has many options which can be used for the advanced
+configuration of services. Each role's documentation provides more
+insight into the options available and what they are used for.
+
+The following options are not necessary to set - they are entirely optional.
+
+Infrastructure service roles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- `galera_server <http://docs.openstack.org/developer/openstack-ansible-galera_server>`_
+
+- `haproxy_server <http://docs.openstack.org/developer/openstack-ansible-haproxy_server>`_
+
+- `memcached_server <http://docs.openstack.org/developer/openstack-ansible-memcached_server>`_
+
+- `rabbitmq_server <http://docs.openstack.org/developer/openstack-ansible-rabbitmq_server>`_
+
+- `repo_build <http://docs.openstack.org/developer/openstack-ansible-repo_build>`_
+
+- `repo_server <http://docs.openstack.org/developer/openstack-ansible-repo_server>`_
+
+- `rsyslog_server <http://docs.openstack.org/developer/openstack-ansible-rsyslog_server>`_
+
+
+OpenStack service roles
+~~~~~~~~~~~~~~~~~~~~~~~
+
+-  `os_aodh <http://docs.openstack.org/developer/openstack-ansible-os_aodh>`_
+
+-  `os_ceilometer <http://docs.openstack.org/developer/openstack-ansible-os_ceilometer>`_
+
+-  `os_cinder <http://docs.openstack.org/developer/openstack-ansible-os_cinder>`_
+
+-  `os_glance <http://docs.openstack.org/developer/openstack-ansible-os_glance>`_
+
+-  `os_gnocchi <http://docs.openstack.org/developer/openstack-ansible-os_gnocchi>`_
+
+-  `os_heat <http://docs.openstack.org/developer/openstack-ansible-os_heat>`_
+
+-  `os_horizon <http://docs.openstack.org/developer/openstack-ansible-os_horizon>`_
+
+-  `os_ironic <http://docs.openstack.org/developer/openstack-ansible-os_ironic>`_
+
+-  `os_keystone <http://docs.openstack.org/developer/openstack-ansible-os_keystone>`_
+
+-  `os_magnum <http://docs.openstack.org/developer/openstack-ansible-os_magnum>`_
+
+-  `os_neutron <http://docs.openstack.org/developer/openstack-ansible-os_neutron>`_
+
+-  `os_nova <http://docs.openstack.org/developer/openstack-ansible-os_nova>`_
+
+-  `os_rally <http://docs.openstack.org/developer/openstack-ansible-os_rally>`_
+
+-  `os_sahara <http://docs.openstack.org/developer/openstack-ansible-os_sahara>`_
+
+-  `os_swift <http://docs.openstack.org/developer/openstack-ansible-os_swift>`_
+
+-  `os_tempest <http://docs.openstack.org/developer/openstack-ansible-os_tempest>`_
+
+
+Other roles
+~~~~~~~~~~~
+
+- `ansible-plugins <http://docs.openstack.org/developer/openstack-ansible-plugins>`_
+
+- `apt_package_pinning <http://docs.openstack.org/developer/openstack-ansible-apt_package_pinning/>`_
+
+- `ceph_client <http://docs.openstack.org/developer/openstack-ansible-ceph_client>`_
+
+- `galera_client <http://docs.openstack.org/developer/openstack-ansible-galera_client>`_
+
+- `lxc_container_create <http://docs.openstack.org/developer/openstack-ansible-lxc_container_create>`_
+
+- `lxc_hosts <http://docs.openstack.org/developer/openstack-ansible-lxc_hosts>`_
+
+- `pip_install <http://docs.openstack.org/developer/openstack-ansible-pip_install/>`_
+
+- `openstack_openrc <http://docs.openstack.org/developer/openstack-ansible-openstack_openrc>`_
+
+- `openstack_hosts <http://docs.openstack.org/developer/openstack-ansible-openstack_hosts>`_
+
+- `rsyslog_client <http://docs.openstack.org/developer/openstack-ansible-rsyslog_client>`_
+
+
+
+

doc/source/install-guide/configure.rst

@@ -26,29 +26,26 @@ tasks include:
 
 Initial environment configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 OpenStack-Ansible depends on various files that are used to build an inventory
-for Ansible. Start by getting those files into the correct places:
+for Ansible. The following configuration is to be done on the deployment host.
+Start by getting those files into the correct places:
 
 #. Copy the contents of the
    ``/opt/openstack-ansible/etc/openstack_deploy`` directory to the
    ``/etc/openstack_deploy`` directory.
 
-.. note::
-
-    As of |current_release_formal_name|, the ``env.d`` directory has been
-    moved from this source directory to ``playbooks/inventory/``.
-
 #. Change to the ``/etc/openstack_deploy`` directory.
 
 #. Copy the ``openstack_user_config.yml.example`` file to
    ``/etc/openstack_deploy/openstack_user_config.yml``.
 
-You can review the ``openstack_user_config.yml`` file and make changes
-to the deployment of your OpenStack environment.
+#. Review the ``openstack_user_config.yml`` file and make changes
+   to the deployment of your OpenStack environment.
 
-.. note::
+   .. note::
 
-   The file is heavily commented with details about the various options.
+      The file is heavily commented with details about the various options.
 
 Configuration in ``openstack_user_config.yml`` defines which hosts
 will run the containers and services deployed by OpenStack-Ansible. For

doc/source/install-guide/deploymenthost.rst

@@ -30,7 +30,22 @@ access the internet or suitable local repositories.
 Configuring the operating system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Install additional software packages and configure NTP.
+Install additional software packages and configure NTP. Before you begin,
+we recommend upgrading your system packages and kernel:
+
+#. Update package source lists:
+
+   .. code-block:: shell-session
+
+       # apt-get update
+
+#. Upgrade system packages and kernel:
+
+   .. code-block:: shell-session
+
+      # apt-get dist-upgrade
+
+Reboot before you continue.
 
 #. Install additional software packages if not already installed
    during operating system installation:
@@ -46,9 +61,10 @@ Configuring the network
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 Ansible deployments fail if the deployment server is unable to SSH to the
-containers. Configure the deployment host to be on the same network designated
-for container management. This configuration reduces the rate of failure due
-to connectivity issues.
+containers. Configure the deployment host (where Ansible is executed) to be on
+the same L2 network as the network designated for container management. By
+default, this is ``br-mgmt``. This configuration reduces the rate of failure
+due to connectivity issues.
 
 The following network information is used as an example:
 

doc/source/install-guide/installation.rst

@@ -158,7 +158,8 @@ Verifying OpenStack operation
 .. TODO Add procedures to test different layers of the OpenStack environment
 
 The utility container provides a CLI environment for additional
-configuration and testing.
+configuration and testing. The following instructions are to be done on an
+infra host.
 
 #. Determine the utility container name:
 

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

@@ -80,6 +80,8 @@ An example is provided on this `Link to Production Environment`_ based
 on the production environment described in `host layout for production
 environment`_.
 
+Reboot your servers after modifying the network interfaces file.
+
 .. _host layout for production environment: overview-host-layout.html#production-environment
 .. _Link to Production Environment: app-targethosts-networkexample.html#production-environment
 

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

@@ -36,6 +36,8 @@ Configuring the operating system
 
        # apt-get dist-upgrade
 
+Reboot before you continue.
+
 #. Ensure the kernel version is ``3.13.0-34-generic`` or later.
 
    .. code-block:: shell-session
@@ -75,7 +77,9 @@ Ansible uses SSH for connectivity between the deployment and target hosts.
    the ``/root/.ssh/authorized_keys`` file on each target host.
 
 #. Test public key authentication from the deployment host to each
-   target host. SSH provides a shell without asking for a
+   target host by sshing to the target host from the deployment host.
+   If you are able to connect and get the shell without authenticating, it
+   is working. SSH provides a shell without asking for a
    password.
 
 For more information on how to generate an SSH keypair as well as best
@@ -83,7 +87,7 @@ practices, refer to `GitHub's documentation on generating SSH keys`_.
 
 .. _GitHub's documentation on generating SSH keys: https://help.github.com/articles/generating-ssh-keys/
 
-.. warning::
+.. important::
 
    OpenStack-Ansible deployments expect the presence of a
    ``/root/.ssh/id_rsa.pub`` file on the deployment host.