From 815f9dd9ab1330bcc592da8ad34daaabb96595bf Mon Sep 17 00:00:00 2001 From: David Shrewsbury Date: Tue, 20 Nov 2012 11:17:54 -0500 Subject: [PATCH] Change README to represent entire Libra tool set. Moved the worker specific stuff from README to the Sphinx docs. Change-Id: I5addfac74184a594690b48b20fd9add13817b921 --- README | 101 +++++++++++-------------------------------- doc/worker/about.rst | 84 ++++++++++++++++++++++++++++++----- 2 files changed, 97 insertions(+), 88 deletions(-) diff --git a/README b/README index f0613e73..72253668 100644 --- a/README +++ b/README @@ -1,11 +1,29 @@ Description ----------- -A Python-based Gearman worker that handles work for the job queue named -'lbaas-'. It receives JSON data describing a load balancer, and -returns this same JSON object, but with status fields added to describe -the state of the LB. +Libra is a tool set to create and manager load balancers in an OpenStack +environment. +Tools +----- + + * libra_client + + Python utility designed to communicate with Atlas API based LBaaS systems. + + * libra_pool_mgm + + Python daemon that manages a pool of Nova instances. + + * libra_statsd + + Python daemon to receive load balancer statistics from Libra workers. + + * libra_worker + + Python daemon that will receive messages from an API server via + a Gearman job server to create/modify load balancers on the local + machine. Running Tests ------------- @@ -19,78 +37,9 @@ Once it is installed, run the tests: $ tox - -Installing the Tools --------------------- - -You must have Python setuptools installed. On Ubuntu: - - $ sudo apt-get install python-setuptools - -Now you may install the Libra toolset: - - $ sudo python setup.py install - -The worker also needs some packages installed in order to be used with -HAProxy. The commands below will install them on Ubuntu: - - $ sudo apt-get install haproxy - $ sudo apt-get install socat - - -Edit /etc/sudoers ------------------ - -The worker needs to be able to run some commands as root without being -prompted for a password. It is suggested that you run the worker as -the `haproxy` user and `haproxy` group on Ubuntu systems. Then add the -following line to /etc/sudoers: - - %haproxy ALL = NOPASSWD: /usr/sbin/service, /bin/cp, /bin/mv, /bin/rm, /usr/bin/socat - -The above lets everyone in the `haproxy` group run those commands -as root without being prompted for a password. - - -Running the Worker +More Documentation ------------------ -The worker can run in either daemon or non-daemon mode. Daemon mode requires -escalated privileges so that it can behave like a proper daemon. Non-daemon -mode (--nodaemon option) is useful for testing. +You can build the complete documentation with: -Basic commands: - - # Getting help - $ libra_worker -h - - # Start up as a daemon running as the `haproxy` user and - # connecting to the local Gearman job server. - $ sudo libra_worker --user haproxy --group haproxy --server 127.0.0.1:4730 - - # Start up with debugging output in non-daemon mode - $ libra_worker --debug --nodaemon - -NOTE: When running the worker in daemon mode, you must make sure that the -directory where the PID file will be (-p/--pid option) and the directory where -the log files will be written (-l/--logfile option) exists and is writable -by the user/group specified with the --user and --group options. Also, the -Python module used to start the daemon process does not like it when the PID -file already exists at startup. - - IF THE WORKER IMMEDIATELY EXITS WHEN STARTED IN DAEMON MODE, AND NO ERROR - MESSAGES ARE IN THE LOG, ONE OF THESE REASONS IS THE MOST LIKELY CAUSE! - -You can verify that the worker is running by using the sample Gearman -client in the bin/ directory: - - $ bin/client.py - - -Configuration File ------------------- - -It can be easier to give options via a configuration file. See the sample -configuration file etc/sample_libra.cfg for an example and further -documentation. Use the -c/--config option to specify the configuration -file to read. + $ python setup.py build_sphinx diff --git a/doc/worker/about.rst b/doc/worker/about.rst index 577bc23c..df93b824 100644 --- a/doc/worker/about.rst +++ b/doc/worker/about.rst @@ -4,24 +4,84 @@ Description Purpose ------- - The Libra Gearman worker does cool stuff. +A Python-based Gearman worker that handles work for the job queue named +'lbaas-HOSTNAME'. It receives JSON data describing a load balancer, and +returns this same JSON object, but with status fields added to describe +the state of the LB. -Design ------- +Installation +------------ - The design rocks. +Installing the Required Tools +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +You must have Python setuptools installed. On Ubuntu:: -Gearman Messages -^^^^^^^^^^^^^^^^ + $ sudo apt-get install python-setuptools - Yup, we got 'em. +Now you may install the Libra toolset:: -Pluggable Drivers + $ sudo python setup.py install + +The worker also needs some packages installed in order to be used with +HAProxy. The commands below will install them on Ubuntu:: + + $ sudo apt-get install haproxy + $ sudo apt-get install socat + +Edit /etc/sudoers ^^^^^^^^^^^^^^^^^ - HAProxy is one. +The worker needs to be able to run some commands as root without being +prompted for a password. It is suggested that you run the worker as +the `haproxy` user and `haproxy` group on Ubuntu systems. Then add the +following line to /etc/sudoers:: -HAProxy OS Support -^^^^^^^^^^^^^^^^^^ + %haproxy ALL = NOPASSWD: /usr/sbin/service, /bin/cp, /bin/mv, /bin/rm, /usr/bin/socat + +The above lets everyone in the *haproxy* group run those commands +as root without being prompted for a password. + +Configuration File +------------------ + +It can be easier to give options via a configuration file. See the sample +configuration file etc/sample_libra.cfg for an example and further +documentation. Use the :option:`--config ` option +to specify the configuration file to read. + +Running the Worker +------------------ + +The worker can run in either daemon or non-daemon mode. Daemon mode requires +escalated privileges so that it can behave like a proper daemon. Non-daemon +mode (:option:`--nodaemon ` option) is useful for testing. + +Basic commands:: + + # Getting help + $ libra_worker -h + + # Start up as a daemon running as the `haproxy` user and + # connecting to the local Gearman job server. + $ sudo libra_worker --user haproxy --group haproxy --server 127.0.0.1:4730 + + # Start up with debugging output in non-daemon mode + $ libra_worker --debug --nodaemon + +NOTE: When running the worker in daemon mode, you must make sure that the +directory where the PID file will be (:option:`--pid ` +option) and the directory where the log files will be written +(:option:`--logfile ` option) exists and is writable +by the user/group specified with the :option:`--user ` +and :option:`--group ` options. Also, the +Python module used to start the daemon process does not like it when the PID +file already exists at startup. + + **IF THE WORKER IMMEDIATELY EXITS WHEN STARTED IN DAEMON MODE, AND NO ERROR + MESSAGES ARE IN THE LOG, ONE OF THESE REASONS IS THE MOST LIKELY CAUSE!** + +You can verify that the worker is running by using the sample Gearman +client in the bin/ directory:: + + $ bin/client.py - Only Ubuntu now, but designed for others to be easily implemented.