Merge "Rework documentaton to actually get people rolling"

4 files changed, 315 insertions, 37 deletions

diff --git a/docs/dev-quickstart.rst b/docs/dev-quickstart.rst
index e5cecf53d..57e38a700 100644
--- a/docs/dev-quickstart.rst
+++ b/docs/dev-quickstart.rst
@@ -1,24 +1,42 @@
-Developer Environment
-=====================
+Quickstart to Deploying OpenStack using Ansible
+===============================================
 
-If you are developing Kolla on an existing OpenStack cloud that supports
-Heat, then follow the Heat template
-`README <https://github.com/stackforge/kolla/blob/master/devenv/README.md>`__.
-Another option available on systems with VirutalBox is the use of
-`Vagrant <https://github.com/stackforge/kolla/blob/master/docs/vagrant.md>`__.
+Evaluation and Developer Environments
+-------------------------------------
 
-The best experience is available with bare metal deployment by following
-the instructions below to manually create your Kolla deployment.
+Two virtualized evaluation and development environment options are
+available.  These options permit the evaluation of Kolla without
+disrupting the host operating system.
+
+If developing or evaluating Kolla on an OpenStack cloud environment that
+supports Heat, follow the
+`Heat evaluation and developer environment guide <https://github.com/stackforge/kolla/blob/master/docs/devenv-heat.rst>`__.
+
+If developing or evaluating Kolla on a system that provides VirtualBox,
+Vagrant may be used and is documented in the
+`Vagrant evaluation and developer environment guide <https://github.com/stackforge/kolla/blob/master/docs/devenv-vagrant.rst>`__.
+
+If evaluating or deploying OpenStack on bare-metal with Kolla, follow the
+instructions in this document to get started.
 
 Installing Dependencies
 -----------------------
 
-NB: Kolla will not run on Fedora 22 or later. Fedora 22 compresses
-kernel modules with the .xz compressed format. The guestfs system cannot
-read these images because a dependent package supermin in CentOS needs
-to be updated to add .xz compressed format support.
+Kolla will not run on Fedora 22 or later currently. Fedora 22 compresses
+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.
+
+On the deployment host Ansible>=1.8.4 must be installed and is the only
+requirement for deploying OpenStack.  To build the Docker container images
+locally the dependnencies docker>=1.7.0 and the Python libraries
+docker-py>=1.2.0 and Jinja2>=2.6 must be installed.
 
-To install Kolla depenedencies use:
+The deployment targt nodes require the installation of docker>=1.7.0 and
+docker-py>=1.2.0.
+
+To install Kolla Python depenedencies use:
 
 ::
 
@@ -26,67 +44,132 @@ To install Kolla depenedencies use:
     cd kolla
     sudo pip install -r requirements.txt
 
-In order to run Kolla, it is mandatory to run a version of ``docker``
-that is 1.7.0 or later.
-
-For most systems you can install the latest stable version of Docker
-with the following command:
+Since Docker is required to build images as well as be present on all deployed
+targets, the Kolla community recommends installing the Docker Inc. packaged
+version of Docker for maximum stability and compatiblity with the following
+command:
 
 ::
 
     curl -sSL https://get.docker.io | bash
 
-For Ubuntu based systems, do not use AUFS when starting Docker daemon
-unless you are running the Utopic (3.19) kernel. AUFS requires
+For Ubuntu based systems where Docker is used, do not use AUFS when starting
+Docker daemon unless you are running the Utopic (3.19) kernel. AUFS requires
 CONFIG\_AUFS\_XATTR=y set when building the kernel. On Ubuntu, versions
-prior to 3.19 did not set that flag. If you are unable to upgrade your
-kernel, you should use a different storage backend such as btrfs.
+prior to 3.19 did not set this flag to be compatible with Docker. If unable
+to upgrade the kernel, the Kolla community recommends using a different storage
+backend such as btrfs.
 
-Next, install the OpenStack python clients if they are not installed:
+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.  To install these clients use:
 
 ::
 
     sudo pip install -U python-openstackclient
 
-Finally stop libvirt on the host machine. Only one copy of libvirt may
+Libvirt is started by default on many operating systems.  Please disable libvirt
+on any machines that will be deployment targets.  Only one copy of libvirt may
 be running at a time.
 
 ::
 
+    service libvirtd disable
     service libvirtd stop
 
-The basic starting environment will be created using ``ansible``. This
-environment will start up the OpenStack services listed in the inventory
-file.
+Kolla deploys OpenStack using
+`Ansible <https://ansible.com>`__.  Install Ansible from distribution
+packaging if the distro packaging has 1.8.4 or greater available.  Currently
+Ubuntu's version of Ansible is too old to use from packaging.  On RPM
+based systems install from packaging using:
+
+::
+
+    yum -y install ansible
+
+On DEB based systems this can be done using:
+
+::
+
+    apt-get install ansible
+
+If the distro packaged version of Ansible is too old, install Ansible using
+pip:
+
+::
+
+    pip install -U ansible
+
+Buildling Container Images
+--------------------------
+
+The Kolla community does not currently generate new images for each commit
+to the repository.  The push time for a full image build to the docker registry
+is about 5 hours on 100mbit Internet, so there are technical limitations to
+using the Docker Hub registry with our current OpenStack CI/CD systems.
+
+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.
+All Docker images can be built as follows:
+
+::
+
+    tools/build.py -T 1000
+
+The -T option specifies how many threads to run concurrently.  A docker build
+of all containers on Xeon hardware with SSDs and 100mbit network takes roughly
+15 minutes.  The CentOS mirrors are flakey and the RDO delorean repository is
+not mirrored at all.  As a result occasionally some containers will fail to
+build.  If something important fails to bulid, repeat the entire build process
+again.  The Kolla community recognizes this is not ideal and the Kolla
+community is adding an individual container build option to solve this
+particular problem.
 
 Starting Kolla
 --------------
 
-Configure Ansible by reading the Kolla
-`Ansible configuration <https://github.com/stackforge/kolla/blob/master/docs/ansible-deployment.md>`__ documentation.
+Configure Ansible by reading the
+`Kolla Ansible configuration Guide <https://github.com/stackforge/kolla/blob/master/docs/ansible-deployment.md>`__ documentation.
 
-Next, run the start command:
+Finally, run the deploy operation:
 
 ::
 
     $ sudo ./tools/kolla-ansible deploy
 
 A bare metal system takes three minutes to deploy AIO. A virtual machine
-takes five minutes to deploy AIO. These are estimates; your hardware may
-be faster or slower but should near these results.
+deployment takes five minutes to deploy AIO. These are estimates; different
+hardware may be faster or slower but should be near these results.
 
 Debugging Kolla
 ---------------
 
-You can determine a container's status by executing:
+The container's status can be determined on the deployment targets by
+executing:
 
 ::
 
-    $ sudo docker ps -a
+    $ docker ps -a
+
+If any of the containers exited, this indicates a bug in the container.  Please
+seek help by filing a bug or contacting the developers via IRC.
 
-If any of the containers exited you can check the logs by executing:
+ the logs can be examined by executing:
 
 ::
 
-    $ sudo docker logs <container-name>
+    $ docker logs <container-name>
+
+Note some of the containers don't log to stdout at present so the above
+command will provide no information.  Instead they log to files
+in _/var_/log_/_<service_> inside the container.  The Kolla community is
+working to improve auditing and make things more consistent.  The Kolla
+community expects this work to complete by Liberty rc1.  An example of
+reading the logs for nova-api:
+
+::
+    $ docker exec -t nova_api more /var/log/nova/nova-api.log
 
+Note reading the logs via an exec operation can only be done if the
+container is running.
diff --git a/docs/devenv-heat.rst b/docs/devenv-heat.rst
new file mode 100644
index 000000000..4436f4660
--- /dev/null
+++ b/docs/devenv-heat.rst
@@ -0,0 +1,195 @@
+A Kolla Cluster with Heat
+=========================
+
+These `Heat <https://wiki.openstack.org/wiki/Heat>`__ templates will
+deploy an *N*-node `Kolla <https://launchpad.net/kolla>`__ cluster,
+where *N* is the value of the ``number_of_nodes`` parameter you specify
+when creating the stack.
+
+Kolla has recently undergone a considerable design change. The details
+of the design change is addressed in this
+`spec <https://review.openstack.org/#/c/153798/>`__. As part of the
+design change, containers share pid and networking namespaces with the
+Docker host. Therefore, containers no longer connect to a docker0 bridge
+and have separate networking from the host. As a result, Kolla
+networking has a configuration similar to:
+
+.. figure:: https://raw.githubusercontent.com/stackforge/kolla/master/devenv/kollanet.png
+   :alt: Image
+
+   Image
+Sharing pid and networking namespaces is detailed in the `super
+privileged
+containers <http://sdake.io/2015/01/28/an-atomic-upgrade-process-for-openstack-compute-nodes/>`__
+concept.
+
+The Kolla cluster is based on Fedora 21, requires the minimum Docker
+version of 1.7.0
+`binary <https://docs.docker.com/installation/binaries/>`__.
+
+These templates are designed to work with the Icehouse or Juno versions
+of Heat. If using Icehouse Heat, this
+`patch <https://review.openstack.org/#/c/121139/>`__ is required to
+correct a bug with template validation when using the "Fn::Join"
+function).
+
+Create the Glance Image
+=======================
+
+After cloning the project, run the get-image.sh script from the
+project's devenv directory:
+
+::
+
+    $ ./get-image.sh
+
+The script will create a Fedora 21 image with the required
+modifications.
+
+Add the image to your Glance image store:
+
+::
+
+    $ glance image-create --name "fedora-21-x86_64" \
+    --file /var/lib/libvirt/images/fedora-21-x86_64 \
+    --disk-format qcow2 --container-format bare \
+    --is-public True --progress
+
+Create the Stack
+================
+
+Copy local.yaml.example to local.yaml and edit the contents to match
+your deployment environment. Here is an example of a customized
+local.yaml:
+
+::
+
+    parameters:
+      ssh_key_name: admin-key
+      external_network_id: 028d70dd-67b8-4901-8bdd-0c62b06cce2d
+      container_external_network_id: 028d70dd-67b8-4901-8bdd-0c62b06cce2d
+      container_external_subnet_id: 575770dd-6828-1101-34dd-0c62b06fjf8s
+      dns_nameserver: 192.168.200.1
+
+The external\_network\_id is used by Heat to automatically assign
+floating IP's to your Kolla nodes. You can then access your Kolla nodes
+directly using the floating IP. The network ID is derived from the
+``neutron net-list`` command.
+
+The container\_external\_network\_id is used by the nova-network
+container within the Kolla node as the FLAT\_INTERFACE. The
+FLAT\_INTERFACE tells Nova what device to use (i.e. eth1) to pass
+network traffic between Nova instances across Kolla nodes. This network
+should be seperate from the external\_network\_id above and is derived
+from the 'neutron net-list' command.
+
+The container\_external\_subnet\_id: is the subnet equivalent to
+container\_external\_network\_id
+
+Review the parameters section of kollacluster.yaml for a full list of
+configuration options. **Note:** You must provide values for:
+
+-  ``ssh_key_name``
+-  ``external_network_id``
+-  ``container_external_network_id``
+-  ``container_external_subnet_id``
+
+And then create the stack, referencing that environment file:
+
+::
+
+    $ heat stack-create -f kollacluster.yaml -e local.yaml kolla-cluster
+
+Access the Kolla Nodes
+======================
+
+You can get the ip address of the Kolla nodes using the
+``heat output-show`` command:
+
+::
+
+    $ heat output-show kolla-cluster kolla_node_external_ip
+    "192.168.200.86"
+
+You can ssh into that server as the ``fedora`` user:
+
+::
+
+    $ ssh fedora@192.168.200.86
+
+Once logged into your Kolla node, setup your environment. The basic
+starting environment will be created using ``docker-compose``. This
+environment will start up the openstack services listed in the compose
+directory.
+
+To start, setup your environment variables.
+
+::
+
+    $ cd kolla
+    $ ./tools/genenv
+
+The ``genenv`` script will create a compose/openstack.env file and an
+openrc file in your current directory. The openstack.env file contains
+all of your initialized environment variables, which you can edit for a
+different setup.
+
+Next, run the start script.
+
+::
+
+    $ ./tools/kolla-compose start
+
+The ``start`` script is responsible for starting the containers using
+``docker-compose -f <osp-service-container> up -d``.
+
+If you want to start a container set by hand use this template
+
+::
+
+    $ docker-compose -f glance-api-registry.yml up -d
+
+Debugging
+=========
+
+All Docker commands should be run from the directory of the Docker
+binaray, by default this is ``/``.
+
+A few commands for debugging the system.
+
+::
+
+    $ sudo ./docker images
+
+Lists all images that have been pulled from the upstream kollaglue
+repository thus far. This can be run on the node during the ``./start``
+operation to check on the download progress.
+
+::
+
+    $ sudo ./docker ps -a
+
+This will show all processes that docker has started. Removing the
+``-a`` will show only active processes. This can be run on the node
+during the ``./start`` operation to check that the containers are
+orchestrated.
+
+::
+
+    $ sudo ./docker logs <containerid>
+
+::
+
+    $ curl http://<NODE_IP>:3306
+
+You can use curl to test connectivity to a container. This example
+demonstrates the Mariadb service is running on the node. Output should
+appear as follows
+
+::
+
+    $ curl http://10.0.0.4:3306
+    Trying 10.0.0.4...
+    Connected to 10.0.0.4.
+    Escape character is '^]'.
+
diff --git a/docs/vagrant.rst b/docs/devenv-vagrant.rst
index f3fe559aa..f3fe559aa 100644
--- a/docs/vagrant.rst
+++ b/docs/devenv-vagrant.rst
diff --git a/docs/kollanet.png b/docs/kollanet.png
new file mode 100644
index 000000000..cfb0c6014
--- /dev/null
+++ b/docs/kollanet.png