diff --git a/doc/architecture/index.rst b/doc/architecture/index.rst index bb18a599..2d6b9322 100644 --- a/doc/architecture/index.rst +++ b/doc/architecture/index.rst @@ -1,7 +1,7 @@ .. _architecture: Architecture -================== +============ .. toctree:: :maxdepth: 2 diff --git a/doc/architecture/logical.rst b/doc/architecture/logical.rst index 6b096395..22e6d317 100644 --- a/doc/architecture/logical.rst +++ b/doc/architecture/logical.rst @@ -1,6 +1,6 @@ -============= +==================== Logical architecture -============= +==================== See information for each component for more information. diff --git a/doc/config.rst b/doc/config.rst index 69d6f3a7..ef6bf614 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -1,3 +1,9 @@ +.. _configuration: + +============= +Configuration +============= + Configuration of Services ========================= diff --git a/doc/getting-started.rst b/doc/getting-started.rst index 76ba5eb7..c4051428 100644 --- a/doc/getting-started.rst +++ b/doc/getting-started.rst @@ -4,8 +4,271 @@ Getting started Libra is a system to provide LoadBalancing as a Service on top of various platforms. It is comprised of four components :ref:`libra-api`, -:ref:`libra-admin-api`, :ref:`libra-pool-mgr` and :ref:`libra-worker`, +:ref:`libra-admin-api`, :ref:`libra-pool-mgm` and :ref:`libra-worker`, supported by a few other open source components. For more information see :doc:`architecture/index`. +Development environment ++++++++++++++++++++++++ +This guide will walk you through howto setup a development environment for Libra +using: + +* 1 Node for the API, Admin API and Pool mgm with MySQL +* n+ Nodes for workers that is going to run HAProxy +* Ubuntu 12.04 as our OS of choice + +Common steps +============ + +1. Install general system dependencies + +:: + + $ sudo apt-get install -qy python-virtualenv python-pip python-dev git gcc + +2. Clone the repo from Stackforge at GitHub + +:: + + $ git clone ssh://git@github.com/stackforge/libra + $ cd libra + +3. Create needed directories + +:: + + $ sudo mkdir -p /var/run/libra /var/log/libra + $ sudo chown ubuntu:ubuntu /var/run/libra /var/log/libra + + +Installing +========== + +.. index:: + double: install; libra + +1. Do steps in :ref:`ppa` + +2. Do steps in 'Common steps' + +3. Install dependencies + +:: + + $ sudo apt-get install -qy gearman-jobs-server mysql-server + +4. Setup a VirtualEnvironment + +.. note:: + + This is to not interfere with systemwide libraries. + +:: + + $ virtualenv .venv + $ . .venv/bin/active + +5. Install python-gearman + +.. note:: + + This is a custom version with patches commited upstream but not release yet. + + sudo pip install https://launchpad.net/~libra-core/+archive/ppa/+files/gearman_2.0.2.git2.orig.tar.gz + +6. Install dependencies using pip + +:: + + $ pip install -r requirements.txt -r test-requirements.txt + + +7. Install python-keystoneclient + +:: + pip install python-keystoneclient + +8. Install Libra in development mode + +:: + + $ python setup.py develop + +9. Copy the configuration file to /etc + +:: + + $ sudo cp etc/sample_libra.cfg /etc/libra.cfg + +10. Change running as libra to ubuntu + +.. note:: + + This is to not have to add a new user. + +:: + + $ sudo sed -r -i 's/^(group|user).*libra/\1 = ubuntu/' /etc/libra.cfg + +11. Configure libra + +:: + + $ sudo vi /etc/libra.cfg + +.. note:: + + See :ref:`configuration` for how to proceed for various options. + + You should at least configure the variables needed for your environment. + + +Setup database and gearman +========================== +1. Import the initial database + +:: + + $ mysql < libra/common/api/lbaas.sql + +2. Change the listening address of Gearman server + +:: + + $ sudo vi /etc/default/gearman-job-server + +3. Restart gearman + +:: + + $ sudo service gearman-job-server restart + + +Bring up services +================= + +1. Start the Pool Manager + +:: + + $ libra-pool-mgm -c /etc/libra.cfg + +2. Start Admin API & API services + +:: + + $ libra-admin-api -c /etc/libra.cfg + $ libra-api -c /etc/libra.cfg + + +Creating a Worker Image +======================= + +.. note:: + + In this setup we'll be using OpenStack as the underlying provider for our Libra Worker nodes to run HAProxy on. + +1. Boot a server using Nova + +.. note:: + + You should at least open (for now at least) port 22 for ssh. + + --nic argument is only needed if you have multiple networks. + --security-groups is not needed at the time if you have 22 in default + +:: + + $ nova boot --flavor --image --key-name default --nic net-id= --security-groups= worker + +2. Create a floating ip + +:: + + $ neutron floatingip-create + +3. Assign a floating ip to the instance + +.. note:: + + You can view all the ports by issuing `neutron port-list`. + +:: + + $ neutron floatingip-associate + +4. Login to the instance + +:: + + $ ssh ubuntu@ + +5. Do steps in 'Common steps' + +6. Install HAProxy + +:: + + $ apt-get install -qy haproxy socat + + +7. Install python-gearman + +.. note:: + + This is a custom version with patches commited upstream but not release yet. + + sudo pip install https://launchpad.net/~libra-core/+archive/ppa/+files/gearman_2.0.2.git2.orig.tar.gz + +8. Install dependencies using pip + +:: + + $ sudo pip install -r requirements.txt -r test-requirements.txt + +9. Install Libra in development mode + +:: + + $ sudo python setup.py develop + +10. Install a Upstart job + +:: + + $ sudo wget https://raw.github.com/pcrews/lbaas-salt/master/lbaas-haproxy-base/libra_worker.conf -O /etc/init/libra_worker.conf + +11. Make a snapshot of the worker image + +:: + + $ nova image-create worker libra-worker + +12. At the libra-poo-mgm node change the 'nova_image' setting to the value of your newly created snapshot + +.. note:: + + To get the ID of the snapshot do + glance image-show libra-worker | grep -w id | cut -d '|' -f3 + +:: + + $ sudo vi /etc/libra.cfg + +13. Restart libra-pool-mgm + +:: + + $ killall -9 libra_pool_mgm + $ libra_pool_mgm -c /etc/libra.cfg + +Verifying that it works +======================= + +If you have done all correctly you should be able to do something like the +below command on the node that has the :ref:`libra-pool-mgm` + +:: + + $ tail -f /var/log/libra/libra_mgm.log \ No newline at end of file diff --git a/doc/installation/ppa.rst b/doc/installation/ppa.rst new file mode 100644 index 00000000..411f01d7 --- /dev/null +++ b/doc/installation/ppa.rst @@ -0,0 +1,26 @@ +.. _ppa: + +========= +Libra PPA +========= + +Currently we require a PPA that is provided by the HPCS LBaaS / Libra team in order +to get the right versions of the dependencies. So we'll need to setup a PPA. + +To add it to your Ubuntu node follow the instructions below. + + +Adding the PPA +============== + +1. Install a utility package + +:: + + $ sudo apt-get install python-software-properties + +2. Add the PPA + +:: + + $ sudo apt-add-repository ppa:libra-core/ppa \ No newline at end of file diff --git a/doc/pool_mgm/index.rst b/doc/pool_mgm/index.rst index 17170dda..a3c9d61e 100644 --- a/doc/pool_mgm/index.rst +++ b/doc/pool_mgm/index.rst @@ -1,4 +1,4 @@ -.. _libra-pool-mgr: +.. _libra-pool-mgm: Libra Node Pool Manager =======================