Merge "Improve Quick Start documentation"

3 files changed, 448 insertions, 355 deletions

diff --git a/doc/index.rst b/doc/index.rst
index eee8c7f86..10ba75e06 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -55,6 +55,7 @@ Kolla Overview
    advanced-configuration
    operating-kolla
    security
+   troubleshooting
 
 Kolla Services
 ==============
diff --git a/doc/quickstart.rst b/doc/quickstart.rst
index b6e036d6b..6ae0af4de 100644
--- a/doc/quickstart.rst
+++ b/doc/quickstart.rst
@@ -4,96 +4,90 @@
 Quick Start
 ===========
 
-This guide provides a step by step procedure to deploy Kolla on bare metal or a
-virtual machine.
+This guide provides step by step instructions to deploy OpenStack using Kolla
+and Kolla-Ansible on bare metal servers or virtual machines.
 
 Host machine requirements
 =========================
 
-The recommended deployment target requirements:
+The host machine must satisfy the following minimum requirements:
 
-- 2 (or more) network interfaces.
-- At least 8GB main memory.
-- At least 40GB disk space.
+- 2 network interfaces
+- 8GB main memory
+- 40GB disk space
 
-.. note:: Some commands below may require root permissions (e.g. pip, apt-get).
+.. note::
 
-Recommended Environment
+    Root access to the deployment host machine is required.
+
+Recommended environment
 =======================
 
-If developing or evaluating Kolla, the community strongly recommends using bare
-metal or a virtual machine. Follow the instructions in this document to get
-started with deploying OpenStack on bare metal or a virtual machine with Kolla.
-There are other deployment environments referenced below in
-`Additional Environments`_.
+This guide recommends using a bare metal server or a virtual machine. Follow
+the instructions in this document to get started with deploying OpenStack on
+bare metal or a virtual machine with Kolla.
 
-Automatic host bootstrap
-========================
+If developing Kolla on a system that provides VirtualBox or Libvirt in addition
+to Vagrant, use the Vagrant virtual environment documented in
+:doc:`vagrant-dev-env`.
 
-.. note:: New in Newton
+Prerequisites
+=============
 
-To quickly prepare hosts for Kolla, playbook ``bootstrap-servers`` can be used.
-This is an Ansible playbook which works on Ubuntu 14.04, 16.04 and CentOS 7
-hosts to install and prepare cluster for Kolla installation.
+Verify the state of network interfaces. If using a VM spawned on
+OpenStack as the host machine, the state of the second interface will be DOWN
+on booting the VM.
+
+::
 
-.. note:: Installation of dependencies for deployment node and configuration
-   of Kolla interfaces is still required prior to running this command. More
-   information about Kolla interface configuration in
-   :ref:`interface-configuration`.
+    ip addr show
 
-Command to run the playbook:
+Bring up the second network interface if it is down.
 
 ::
 
-    kolla-ansible -i <<inventory file>> bootstrap-servers
+    ip link set ens4 up
+
+Verify if the second interface has an IP address.
 
-To learn more about the inventory file, follow :ref:`edit-inventory`.
+::
 
+    ip addr show
 
-Install Dependencies
+Install dependencies
 ====================
 
-Kolla is tested on CentOS, Oracle Linux, RHEL and Ubuntu as both container OS
+Kolla builds images which are used by Kolla-Ansible to deploy OpenStack. The
+deployment is tested on CentOS, Oracle Linux and Ubuntu as both container OS
 platforms and bare metal deployment targets.
 
-Fedora: Kolla will not run on Fedora 22 and later as a bare metal deployment
-target. These distributions compress kernel modules with the .xz compressed
-format. The guestfs system in the CentOS family of containers cannot read
-these images because a dependent package supermin in CentOS needs to be updated
-to add .xz compressed format support.
-
 Ubuntu: For Ubuntu based systems where Docker is used it is recommended to use
-the latest available LTS kernel. The latest LTS kernel available is the wily
-kernel (version 4.2). While all kernels should work for Docker, some older
-kernels may have issues with some of the different Docker back ends such as
-AUFS and OverlayFS. In order to update kernel in Ubuntu 14.04 LTS to 4.2, run:
+the latest available LTS kernel. While all kernels should work for Docker, some
+older kernels may have issues with some of the different Docker back ends such
+as AUFS and OverlayFS. In order to update kernel in Ubuntu 14.04 LTS to 4.2,
+run:
 
 ::
 
     apt-get install linux-image-generic-lts-wily
 
-.. WARNING::
-   Operators performing an evaluation or deployment should use a stable
-   branch. Operators performing development (or developers) should use
-   master.
-
 .. note:: Install is *very* sensitive about version of components. Please
-  review carefully because default Operating System repos are likely out of
-  date.
+   review carefully because default Operating System repos are likely out of
+   date.
 
 Dependencies for the stable/mitaka branch are:
 
 =====================   ===========  ===========  =========================
 Component               Min Version  Max Version  Comment
 =====================   ===========  ===========  =========================
-Ansible                 1.9.4        < 2.0.0      On deployment host
+Ansible                 1.9.4        <2.0.0       On deployment host
 Docker                  1.10.0       none         On target nodes
 Docker Python           1.6.0        none         On target nodes
 Python Jinja2           2.6.0        none         On deployment host
 =====================   ===========  ===========  =========================
 
-
-Dependencies for stable/newton and later (including master branch) are:
+Dependencies for the stable/newton branch and later (including master branch)
+are:
 
 =====================   ===========  ===========  =========================
 Component               Min Version  Max Version  Comment
@@ -104,32 +98,78 @@ Docker Python           1.6.0        none         On target nodes
 Python Jinja2           2.8.0        none         On deployment host
 =====================   ===========  ===========  =========================
 
-Make sure the ``pip`` package manager is installed and upgraded to latest
+Make sure the ``pip`` package manager is installed and upgraded to the latest
 before proceeding:
 
 ::
 
-    # CentOS 7
+    #CentOS
     yum install epel-release
     yum install python-pip
+    pip install -U pip
 
-    # Ubuntu 14.04 LTS
+    #Ubuntu
+    apt-get update
     apt-get install python-pip
-
-    # Upgrade pip and check version
     pip install -U pip
-    pip -V
-
 
 Install dependencies needed to build the code with ``pip`` package manager.
 
 ::
 
-    # Ubuntu
+    #CentOS
+    yum install python-devel libffi-devel gcc openssl-devel
+
+    #Ubuntu
     apt-get install python-dev libffi-dev gcc libssl-dev
 
-    # CentOS 7
-    yum install python-devel libffi-devel gcc openssl-devel
+Kolla deploys OpenStack using `Ansible <http://www.ansible.com>`__. Install
+Ansible from distribution packaging if the distro packaging has recommended
+version available.
+
+Some implemented distro versions of Ansible are too old to use distro
+packaging. Currently, CentOS and RHEL package Ansible >2.0 which is suitable
+for use with Kolla. Note that you will need to enable access to the EPEL
+repository to install via yum -- to do so, take a look at Fedora's EPEL `docs
+<https://fedoraproject.org/wiki/EPEL>`__ and `FAQ
+<https://fedoraproject.org/wiki/EPEL/FAQ>`__.
+
+On CentOS or RHEL systems, this can be done using:
+
+::
+
+    yum install ansible
+
+Many DEB based systems do not meet Kolla's Ansible version requirements. It is
+recommended to use pip to install Ansible >2.0. Finally Ansible >2.0 may be
+installed using:
+
+::
+
+    pip install -U ansible
+
+.. note:: It is recommended to use virtualenv to install non-system packages.
+
+If DEB based systems include a version of Ansible that meets Kolla's version
+requirements it can be installed by:
+
+::
+
+    apt-get install ansible
+
+.. WARNING::
+   Kolla uses PBR in its implementation. PBR provides version information
+   to Kolla about the package in use. This information is later used when
+   building images to specify the Docker tag used in the image built. When
+   installing the Kolla package via pip, PBR will always use the PBR version
+   information. When obtaining a copy of the software via git, PBR will use
+   the git version information, but **ONLY** if Kolla has not been pip
+   installed via the pip package manager. This is why there is an operator
+   workflow and a developer workflow.
+
+The following dependencies can be installed by bootstraping the host machine
+as described in the `Automatic host bootstrap`_ section. For manual
+installation, follow the instructions below:
 
 Since Docker is required to build images as well as be present on all deployed
 targets, the Kolla community recommends installing the official Docker, Inc.
@@ -176,38 +216,6 @@ Restart Docker by executing the following commands:
     systemctl daemon-reload
     systemctl restart docker
 
-For Ubuntu 14.04 which uses upstart and other non-systemd distros,
-run the following:
-
-::
-
-    mount --make-shared /run
-    mount --make-shared /var/lib/nova/mnt
-
-If ``/var/lib/nova/mnt`` is not partitioned, can do below work around
-
-::
-
-    mkdir -p /var/lib/nova/mnt /var/lib/nova/mnt1
-    mount --bind /var/lib/nova/mnt1 /var/lib/nova/mnt
-    mount --make-shared /var/lib/nova/mnt
-
-For mounting ``/run`` and ``/var/lib/nova/mnt`` as shared upon startup,
-add below commands to ``/etc/rc.local``
-
-::
-
-    # Edit /etc/rc.local to add:
-    mount --make-shared /run
-    mount --make-shared /var/lib/nova/mnt
-
-.. note:: If centos/fedora/oraclelinux container images are built on an Ubuntu
-  host, the back-end storage driver must not be AUFS (see the known issues in
-  :doc:`image-building`).
-
-.. note:: On ubuntu 16.04, please uninstall ``lxd`` and ``lxc`` packages. (issue
-  with cgroup mounts, mounts exponentially increasing when restarting container).
-
 On the target hosts you also need an updated version of the Docker python
 libraries:
 
@@ -268,174 +276,226 @@ On Ubuntu, apparmor will sometimes prevent libvirt from working.
 
 ::
 
-   /usr/sbin/libvirtd: error while loading shared libraries: libvirt-admin.so.0: cannot open shared object file: Permission denied
+   /usr/sbin/libvirtd: error while loading shared libraries:
+   libvirt-admin.so.0: cannot open shared object file: Permission denied
 
 If you are seeing the libvirt container fail with the error above, disable the
 libvirt profile.
 
 ::
 
-   sudo apparmor_parser -R /etc/apparmor.d/usr.sbin.libvirtd
-   sudo ln -s /etc/apparmor.d/usr.sbin.libvirtd /etc/apparmor.d/disable/
+    sudo apparmor_parser -R /etc/apparmor.d/usr.sbin.libvirtd
 
-Kolla deploys OpenStack using `Ansible <http://www.ansible.com>`__. Install
-Ansible from distribution packaging if the distro packaging has recommended
-version available.
 
-Some implemented distro versions of Ansible are too old to use distro
-packaging. Currently, CentOS and RHEL package Ansible >2.0 which is suitable
-for use with Kolla. Note that you will need to enable access to the EPEL
-repository to install via yum -- to do so, take a look at Fedora's EPEL
-`docs <https://fedoraproject.org/wiki/EPEL>`__ and
-`FAQ <https://fedoraproject.org/wiki/EPEL/FAQ>`__.
+.. note::
 
-On CentOS or RHEL systems, this can be done using:
+    On Ubuntu 16.04, please uninstall lxd and lxc packages. (An issue exists
+    with cgroup mounts, mounts exponentially increasing when restarting
+    container).
+
+Additional steps for upstart and other non-systemd distros
+==========================================================
+
+For Ubuntu 14.04 which uses upstart and other non-systemd distros, run the
+following.
 
 ::
 
-    yum install ansible
+    mount --make-shared /run
+    mount --make-shared /var/lib/nova/mnt
 
-Many DEB based systems do not meet Kolla's Ansible version requirements. It is
-recommended to use pip to install Ansible >2.0. Finally Ansible >2.0 may be
-installed using:
+If /var/lib/nova/mnt is not present, can do below work around.
 
 ::
 
-    pip install -U ansible
+    mkdir -p /var/lib/nova/mnt /var/lib/nova/mnt1
+    mount --bind /var/lib/nova/mnt1 /var/lib/nova/mnt
+    mount --make-shared /var/lib/nova/mnt
 
-If DEB based systems include a version of Ansible that meets Kolla's version
-requirements it can be installed by:
+For mounting /run and /var/lib/nova/mnt as shared upon startup, edit
+/etc/rc.local to add the following.
 
 ::
 
-    apt-get install ansible
+    mount --make-shared /run
+    mount --make-shared /var/lib/nova/mnt
 
-.. WARNING::
-   Kolla uses PBR in its implementation. PBR provides version information
-   to Kolla about the package in use. This information is later used when
-   building images to specify the Docker tag used in the image built. When
-   installing the Kolla package via pip, PBR will always use the PBR version
-   information. When obtaining a copy of the software via git, PBR will use
-   the git version information, but **ONLY** if Kolla has not been pip
-   installed via the pip package manager. This is why there is an operator
-   workflow and a developer workflow.
+.. note::
+
+    If CentOS/Fedora/OracleLinux container images are built on an Ubuntu host,
+    the back-end storage driver must not be AUFS (see the known issues in
+    :doc:`image-building`).
 
-Installing Kolla for evaluation or deployment
----------------------------------------------
+Install Kolla for deployment or evaluation
+==========================================
 
-Install Kolla and its dependencies:
+Install Kolla and its dependencies using pip.
 
 ::
 
     pip install kolla
 
-Copy the Kolla configuration files to ``/etc``:
+Copy the configuration files globals.yml and passwords.yml to /etc directory.
 
 ::
 
-    # CentOS 7
-    cp -r /usr/share/kolla/etc_examples/kolla /etc/
+    #CentOS
+    cp -r /usr/share/kolla/etc_examples/kolla /etc/kolla/
 
-    # Ubuntu
-    cp -r /usr/local/share/kolla/etc_examples/kolla /etc/
+    #Ubuntu
+    cp -r /usr/local/share/kolla/etc_examples/kolla /etc/kolla/
+
+The inventory files (all-in-one and multinode) are located in
+/usr/local/share/kolla/ansible/inventory. Copy the configuration files to the
+current directory.
+
+::
+
+   #CentOS
+   cp /usr/share/kolla/ansible/inventory/* .
 
-Installing Kolla and dependencies for development
--------------------------------------------------
+   #Ubuntu
+   cp /usr/local/share/kolla/ansible/inventory/* .
 
-To clone the Kolla repo:
+Install Kolla for development
+=============================
+
+Clone the Kolla and Kolla-Ansible repositories from git.
 
 ::
 
-    git clone https://git.openstack.org/openstack/kolla
+    git clone https://github.com/openstack/kolla
+    git clone https://github.com/openstack/kolla-ansible
 
-To install Kolla's Python dependencies use:
+Kolla-ansible holds configuration files (globals.yml and passwords.yml) in
+etc/kolla.  Copy the configuration files to /etc directory.
 
 ::
 
-    pip install -r kolla/requirements.txt -r kolla/test-requirements.txt
+    cp -r kolla-ansible/etc/kolla /etc/kolla/
+
+Kolla-ansible holds the inventory files (all-in-one and multinode) in
+ansible/inventory. Copy the configuration files to the current directory.
+
+::
+
+    cp kolla-ansible/ansible/inventory/* .
+
+Local Registry
+==============
+
+A local registry is recommended but not required for an ``all-in-one``
+installation when developing for master. Since no master images are available
+on docker hub, the docker cache may be used for all-in-one deployments.  When
+deploying multinode, a registry is strongly recommended to serve as a single
+source of images. Reference the :doc:`multinode` for more information on using
+a local Docker registry. Otherwise, the Docker Hub Image Registry contains all
+images from each of Kolla’s major releases. The latest release tag is 3.0.2 for
+Newton.
 
-.. note:: This does not actually install Kolla. Many commands in this documentation are named
-    differently in the tools directory.
+Automatic host bootstrap
+========================
 
-Kolla holds configurations files in ``etc/kolla``. Copy the configuration files
-to ``/etc``:
+Edit the ``/etc/kolla/globals.yml`` file to configure interfaces.
 
 ::
 
-    cd kolla
-    cp -r etc/kolla /etc/
+    network_interface: “ens3”
+    neutron_external_interface: “ens4"
 
-Install Python Clients
-======================
+Generate passwords. This will populate all empty fields in the
+``/etc/kolla/passwords.yml`` file using randomly generated values to secure the
+deployment. Optionally, the passwords may be populated in the file by hand.
 
-On the system where the OpenStack CLI/Python code is run, the Kolla community
-recommends installing the OpenStack python clients if they are not installed.
-This could be a completely different machine then the deployment host or
-deployment targets. Install dependencies needed to build the code with ``pip``
-package manager as explained earlier.
+::
+
+    kolla-genpwd
 
-To install the clients use:
+To quickly prepare hosts, playbook bootstrap-servers can be used.This is an
+Ansible playbook which works on Ubuntu 14.04, 16.04 and CentOS 7 hosts to
+install and prepare the cluster for OpenStack installation.
 
 ::
 
-    yum install python-openstackclient python-neutronclient
+    kolla-ansible -i <<inventory file>> bootstrap-servers
 
+Build container images
+======================
 
-Or using ``pip`` to install:
+When running with systemd, edit the file
+``/etc/systemd/system/docker.service.d/kolla.conf``
+to include the MTU size to be used for Docker containers.
 
 ::
 
-    pip install -U python-openstackclient python-neutronclient
+    [Service]
+    MountFlags=shared
+    ExecStart=
+    ExecStart=/usr/bin/docker daemon \
+     -H fd:// \
+     --mtu 1400
 
-Local Registry
-==============
+.. note::
 
-A local registry is not required for an ``all-in-one`` installation. Check out
-the :doc:`multinode` for more information on using a local registry. Otherwise,
-the `Docker Hub Image Registry`_ contains all images from each of Kolla's major
-releases. The latest release tag is 3.0.0 for Newton.
+    The MTU size should be less than or equal to the MTU size allowed on the
+    network interfaces of the host machine. If the MTU size allowed on the
+    network interfaces of the host machine is 1500 then this step can be
+    skipped. This step is relevant for building containers. Actual openstack
+    services won't be affected.
 
-Additional Environments
-=======================
+.. note::
 
-Two virtualized development environment options are available for Kolla. These
-options permit the development of Kolla without disrupting the host operating
-system.
+   Verify that the MountFlags parameter is configured as shared. If you do not
+   set the MountFlags option correctly then kolla-ansible will fail to deploy the
+   neutron-dhcp-agent container and throws APIError/HTTPError.
 
-If developing Kolla on a system that provides VirtualBox or Libvirt in addition
-to Vagrant, use the Vagrant virtual environment documented in
-:doc:`vagrant-dev-env`.
+Restart Docker and ensure that Docker is running.
 
-Building Container Images
-=========================
+::
+
+    systemctl daemon-reload
+    systemctl restart docker
 
 The Kolla community builds and pushes tested images for each tagged release of
-Kolla, but if running from master, it is recommended to build images locally.
+Kolla.  Pull required images with appropriate tags.
+
+::
+
+    kolla-ansible pull
+
+View the images.
+
+::
+
+    docker images
 
-Checkout the :doc:`image-building` for more advanced build configuration.
+Developers running from master are required to build container images as
+the Docker Hub does not contain built images for the master branch.
+Reference the :doc:`image-building` for more advanced build configuration.
 
-Before running the below instructions, ensure the Docker daemon is running
-or the build process will fail. To build images using default parameters run:
+To build images using default parameters run:
 
 ::
 
     kolla-build
 
-By default ``kolla-build`` will build all containers using CentOS as the base
-image and binary installation as base installation method. To change this
-behavior, please use the following parameters with ``kolla-build``:
+By default kolla-build will build all containers using CentOS as the base image
+and binary installation as base installation method. To change this behavior,
+please use the following parameters with kolla-build:
 
 ::
 
---base [ubuntu|centos|oraclelinux]
---type [binary|source]
+    --base [ubuntu|centos|oraclelinux]
+    --type [binary|source]
 
-Note ``--base`` and ``--type`` can be added to the above ``kolla-build``
-command if different distributions or types are desired.
+.. note::
 
-It is also possible to build individual containers. As an example, if the
-glance containers failed to build, all glance related containers can be rebuilt
-as follows:
+    --base and --type can be added to the above kolla-build command if
+    different distributions or types are desired.
+
+It is also possible to build individual container images. As an example, if the
+glance images failed to build, all glance related images can be rebuilt as
+follows:
 
 ::
 
@@ -447,26 +507,27 @@ In order to see all available parameters, run:
 
     kolla-build -h
 
-For more information about building Kolla container images, check the detailed
-instruction in :doc:`image-building`.
+View the images.
+
+::
+
+    docker images
 
 .. WARNING::
     Mixing of OpenStack releases with Kolla releases (example, updating
     kolla-build.conf to build Mitaka Keystone to be deployed with Newton Kolla) is
     not recommended and will likely cause issues.
 
-.. _deploying-kolla:
+Deploy Kolla
+============
 
-Deploying Kolla
-===============
-
-The Kolla community provides two example methods of Kolla deploy: *all-in-one*
-and *multinode*. The *all-in-one* deploy is similar to
-`devstack <http://docs.openstack.org/developer/devstack/>`__ deploy which
-installs all OpenStack services on a single host. In the *multinode* deploy,
-OpenStack services can be run on specific hosts. This documentation only
-describes deploying *all-in-one* method as most simple one. To setup
-*multinode* see the :doc:`multinode`.
+Kolla-Ansible is used to deploy containers by using images built by Kolla.
+There are two methods of deployment: *all-in-one* and *multinode*.  The
+*all-in-one* deployment is similar to `devstack
+<http://docs.openstack.org/developer/devstack/>`__ deploy which installs all
+OpenStack services on a single host. In the *multinode* deployment, OpenStack
+services can be run on specific hosts. This documentation describes deploying
+an *all-in-one* setup. To setup *multinode* see the :doc:`multinode`.
 
 Each method is represented as an Ansible inventory file. More information on
 the Ansible inventory file can be found in the Ansible `inventory introduction
@@ -485,229 +546,128 @@ deployment. Optionally, the passwords may be populate in the file by hand.
     kolla-genpwd
 
 Start by editing ``/etc/kolla/globals.yml``. Check and edit, if needed, these
-parameters: ``kolla_base_distro``, ``kolla_install_type``. These parameters
-should match what you used in the ``kolla-build`` command line. The default for
+parameters: ``kolla_base_distro``, ``kolla_install_type``. The default for
 ``kolla_base_distro`` is ``centos`` and for ``kolla_install_type`` is
 ``binary``. If you want to use ubuntu with source type, then you should make
-sure ``globals.yml`` has the following entries:
+sure globals.yml has the following entries:
 
 ::
 
-  kolla_base_distro: "ubuntu"
-  kolla_install_type: "source"
-
+    kolla_base_distro: “ubuntu"
+    kolla_install_type: "source"
 
 Please specify an unused IP address in the network to act as a VIP for
 ``kolla_internal_vip_address``. The VIP will be used with keepalived and added
-to the ``api_interface`` as specified in the ``globals.yml`` ::
-
-    kolla_internal_vip_address: "10.10.10.254"
-
-The ``network_interface`` variable is the interface to which Kolla binds API
-services. For example, when starting up Mariadb it will bind to the IP on the
-interface list in the ``network_interface`` variable. ::
-
-    network_interface: "eth0"
-
-The ``neutron_external_interface`` variable is the interface that will be used
-for the external bridge in Neutron. Without this bridge the deployment instance
-traffic will be unable to access the rest of the Internet. In the case of a
-single interface on a machine, a veth pair may be used where one end of the
-veth pair is listed here and the other end is in a bridge on the system. ::
-
-    neutron_external_interface: "eth1"
-
-For *all-in-one* deploys, the following commands can be run. These will
-setup all of the containers on the localhost. These commands will be
-wrapped in the kolla-script in the future.
-
-.. note:: Even for all-in-one installs it is possible to use the Docker
-   registry for deployment, although not strictly required.
-
-First, check that the deployment targets are in a state where Kolla may deploy
-to them:
+to the ``api_interface`` as specified in the ``globals.yml``
 
 ::
 
-    kolla-ansible prechecks
+    kolla_internal_vip_address: “192.168.137.79”
 
-Verify that all required images with appropriate tags are available:
+.. note::
 
-::
+    The kolla_internal_vip_address must be unique and should belong to the same
+    network to which the first network interface belongs to.
 
-    kolla-ansible pull
+.. note::
 
-Run the deployment:
+    The kolla_base_distro and kolla_install_type should be same as base and
+    install_type used in kolla-build command line.
 
-::
-
-    kolla-ansible deploy
-
-If APIError/HTTPError is received from the neutron-dhcp-agent container,
-remove the container and recreate it:
+The ``network_interface`` variable is the interface to which Kolla binds API
+services. For example, when starting Mariadb, it will bind to the IP on the
+interface list in the ``network_interface`` variable.
 
 ::
 
-    docker rm -v -f neutron_dhcp_agent
-    kolla-ansible deploy
+    network_interface: "ens3"
 
-In order to see all available parameters, run:
+The ``neutron_external_interface`` variable is the interface that will be used
+for the external bridge in Neutron. Without this bridge the deployment instance
+traffic will be unable to access the rest of the Internet.
 
 ::
 
-    kolla-ansible -h
+    neutron_external_interface: "ens4"
 
-.. note:: In case of deploying using the _nested_ environment (*eg*.
-  Using Virtualbox VM's, KVM VM's), if your compute node supports
-  hardware acceleration for virtual machines.
-
-  For this, run the follow command in **compute node**:
+In case of deployment using the **nested** environment (eg. Using Virtualbox
+VM’s, KVM VM’s), verify if your compute node supports hardware acceleration for
+virtual machines by executing the following command in the *compute node*.
 
 ::
 
     egrep -c '(vmx|svm)' /proc/cpuinfo
 
-
-If this command returns a value of **zero**, your compute node does not
-support hardware acceleration and you **must** configure libvirt to use
-**QEMU** instead of KVM.
-
-For this, change the **virt_type** option in the `[libvirt]` section
-of **nova-compute.conf** file inside the ``/etc/kolla/config/`` directory.
+If this command returns a value of **zero**, your compute node does not support
+hardware acceleration and you **must** configure libvirt to use **QEMU**
+instead of KVM. Create a file /etc/kolla/config/nova/nova-compute.conf and add
+the content shown below.
 
 ::
 
+    mkdir /etc/kolla/config/nova
+    cat << EOF > /etc/kolla/config/nova/nova-compute.conf
     [libvirt]
     virt_type=qemu
+    EOF
 
-A bare metal system with Ceph takes 18 minutes to deploy. A virtual machine
-deployment takes 25 minutes. These are estimates; different hardware may be
-faster or slower but should be near these results.
-
-After successful deployment of OpenStack, the Horizon dashboard will be
-available by entering IP address or hostname from ``kolla_external_fqdn``, or
-``kolla_internal_fqdn``. If these variables were not set during deploy they
-default to ``kolla_internal_vip_address``.
-
-Useful tools
-------------
-After successful deployment of OpenStack, run the following command can create
-an openrc file ``/etc/kolla/admin-openrc.sh`` on the deploy node. Or view
-``tools/openrc-example`` for an example of an openrc that may be used with the
-environment.
-
-::
-
-    kolla-ansible post-deploy
-
-After the openrc file is created, use the following command to initialize an
-environment with a glance image and neutron networks:
-
-::
-
-    . /etc/kolla/admin-openrc.sh
-    kolla/tools/init-runonce
-
-Failures
-========
+For *all-in-one* deployments, the following commands can be run. These will
+setup all of the containers on the localhost. These commands will be
+wrapped in the kolla-script in the future.
 
-Nearly always when Kolla fails, it is caused by a CTRL-C during the deployment
-process or a problem in the ``globals.yml`` configuration.
+.. note:: Even for all-in-one installs it is possible to use the Docker
+   registry for deployment, although not strictly required.
 
-To correct the problem where Operators have a misconfigured environment, the
-Kolla developers have added a precheck feature which ensures the deployment
-targets are in a state where Kolla may deploy to them. To run the prechecks,
-execute:
+First, validate that the deployment targets are in a state where Kolla may
+deploy to them. Provide the correct path to inventory file in the following
+commands.
 
 ::
 
-    kolla-ansible prechecks
+    kolla-ansible prechecks -i /path/to/all-in-one
 
-If a failure during deployment occurs it nearly always occurs during evaluation
-of the software. Once the Operator learns the few configuration options
-required, it is highly unlikely they will experience a failure in deployment.
-
-Deployment may be run as many times as desired, but if a failure in a
-bootstrap task occurs, a further deploy action will not correct the problem.
-In this scenario, Kolla's behavior is undefined.
-
-The fastest way during evaluation to recover from a deployment failure is to
-remove the failed deployment:
-
-On each node where OpenStack is deployed run:
+Deploy OpenStack.
 
 ::
 
-    tools/cleanup-containers
-    tools/cleanup-host
-
-The Operator will have to copy via scp or some other means the cleanup scripts
-to the various nodes where the failed containers are located.
+    kolla-ansible deploy -i /path/to/all-in-one
 
-Any time the tags of a release change, it is possible that the container
-implementation from older versions won't match the Ansible playbooks in a new
-version. If running multinode from a registry, each node's Docker image cache
-must be refreshed with the latest images before a new deployment can occur. To
-refresh the Docker cache from the local Docker registry:
-
-::
-
-    kolla-ansible pull
-
-Debugging Kolla
-===============
-
-The container's status can be determined on the deployment targets by
-executing:
+List the running containers.
 
 ::
 
     docker ps -a
 
-If any of the containers exited, this indicates a bug in the container. Please
-seek help by filing a `launchpad bug`_ or contacting the developers via IRC.
-
-The logs can be examined by executing:
+Generate the ``admin-openrc.sh`` file. The file will be created in
+``/etc/kolla/`` directory.
 
 ::
 
-    docker exec -it heka bash
-
-The logs from all services in all containers may be read from
-``/var/log/kolla/SERVICE_NAME``
+    kolla-ansible post-deploy
 
-If the stdout logs are needed, please run:
+To test your deployment, run the following commands to initialize the network
+with a glance image and neutron networks.
 
 ::
 
-    docker logs <container-name>
-
-Note that most of the containers don't log to stdout so the above command will
-provide no information.
+    source /etc/kolla/admin-openrc.sh
 
-To learn more about Docker command line operation please refer to `Docker
-documentation <https://docs.docker.com/reference/commandline/cli/>`__.
+    #centOS
+    cd /usr/share/kolla
+    ./init-runonce
 
-When ``enable_central_logging`` is enabled, to view the logs in a web browser
-using Kibana, go to:
+    #ubuntu
+    cd /usr/local/share/kolla
+    ./init-runonce
 
-::
-
-    http://<kolla_internal_vip_address>:<kibana_server_port>
-    or http://<kolla_external_vip_address>:<kibana_server_port>
+.. note::
 
-and authenticate using ``<kibana_user>`` and ``<kibana_password>``.
+    Different hardware results in results in variance with deployment times.
 
-The values ``<kolla_internal_vip_address>``, ``<kolla_external_vip_address>``
-``<kibana_server_port>`` and ``<kibana_user>`` can be found in
-``<kolla_install_path>/kolla/ansible/group_vars/all.yml`` or if the default
-values are overridden, in ``/etc/kolla/globals.yml``. The value of
-``<kibana_password>`` can be found in ``/etc/kolla/passwords.yml``.
-
-.. note:: When you log in to Kibana web interface for the first time, you are
-          prompted to create an index. Please create an index using the name ``log-*``.
-          This step is necessary until the default Kibana dashboard is implemented in
-          Kolla.
+After successful deployment of OpenStack, the Horizon dashboard will be
+available by entering IP address or hostname from ``kolla_external_fqdn``, or
+``kolla_internal_fqdn``. If these variables were not set during deploy they
+default to ``kolla_internal_vip_address``.
 
 .. _Docker Hub Image Registry: https://hub.docker.com/u/kolla/
 .. _launchpad bug: https://bugs.launchpad.net/kolla/+filebug
diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst
new file mode 100644
index 000000000..ae56e532c
--- /dev/null
+++ b/doc/troubleshooting.rst
@@ -0,0 +1,132 @@
+.. troubleshooting:
+
+=====================
+Troubleshooting Guide
+=====================
+
+Failures
+========
+
+If Kolla fails, often it is caused by a CTRL-C during the deployment
+process or a problem in the ``globals.yml`` configuration.
+
+To correct the problem where Operators have a misconfigured environment, the
+Kolla community has added a precheck feature which ensures the deployment
+targets are in a state where Kolla may deploy to them. To run the prechecks,
+execute:
+
+Production
+==========
+
+::
+
+    kolla-ansible prechecks
+
+Development
+===========
+
+::
+
+    ./tools/kolla-ansible prechecks
+
+If a failure during deployment occurs it nearly always occurs during evaluation
+of the software. Once the Operator learns the few configuration options
+required, it is highly unlikely they will experience a failure in deployment.
+
+Deployment may be run as many times as desired, but if a failure in a
+bootstrap task occurs, a further deploy action will not correct the problem.
+In this scenario, Kolla's behavior is undefined.
+
+The fastest way during to recover from a deployment failure is to
+remove the failed deployment:
+
+Production
+==========
+
+::
+
+    kolla-ansible destroy -i <<inventory-file>>
+
+Development
+===========
+
+::
+
+    ./tools/kolla-ansible destroy -i <<inventory-file>>
+
+Any time the tags of a release change, it is possible that the container
+implementation from older versions won't match the Ansible playbooks in a new
+version. If running multinode from a registry, each node's Docker image cache
+must be refreshed with the latest images before a new deployment can occur. To
+refresh the docker cache from the local Docker registry:
+
+Production
+==========
+
+::
+
+    kolla-ansible pull
+
+Development
+===========
+
+::
+
+    ./tools/kolla-ansible pull
+
+Debugging Kolla
+===============
+
+The status of containers after deployment can be determined on the deployment
+targets by executing:
+
+::
+
+    docker ps -a
+
+If any of the containers exited, this indicates a bug in the container. Please
+seek help by filing a `launchpad bug`_ or contacting the developers via IRC.
+
+The logs can be examined by executing:
+
+::
+
+    docker exec -it heka bash
+
+The logs from all services in all containers may be read from
+``/var/log/kolla/SERVICE_NAME``
+
+If the stdout logs are needed, please run:
+
+::
+
+    docker logs <container-name>
+
+Note that most of the containers don't log to stdout so the above command will
+provide no information.
+
+To learn more about Docker command line operation please refer to `Docker
+documentation <https://docs.docker.com/reference/commandline/cli/>`__.
+
+When ``enable_central_logging`` is enabled, to view the logs in a web browser
+using Kibana, go to:
+
+::
+
+    http://<kolla_internal_vip_address>:<kibana_server_port>
+    or http://<kolla_external_vip_address>:<kibana_server_port>
+
+and authenticate using ``<kibana_user>`` and ``<kibana_password>``.
+
+The values ``<kolla_internal_vip_address>``, ``<kolla_external_vip_address>``
+``<kibana_server_port>`` and ``<kibana_user>`` can be found in
+``<kolla_install_path>/kolla/ansible/group_vars/all.yml`` or if the default
+values are overridden, in ``/etc/kolla/globals.yml``. The value of
+``<kibana_password>`` can be found in ``/etc/kolla/passwords.yml``.
+
+.. note:: When you log in to Kibana web interface for the first time, you are
+   prompted to create an index. Please create an index using the name ``log-*``.
+   This step is necessary until the default Kibana dashboard is implemented in
+   Kolla.
+
+.. _launchpad bug: https://bugs.launchpad.net/kolla/+filebug