Change README to represent entire Libra tool set.
Moved the worker specific stuff from README to the Sphinx docs. Change-Id: I5addfac74184a594690b48b20fd9add13817b921
This commit is contained in:
David Shrewsbury
101
README
101
README
@@ -1,11 +1,29 @@
|
||||
Description
|
||||
-----------
|
||||
|
||||
A Python-based Gearman worker that handles work for the job queue named
|
||||
'lbaas-<IP>'. 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
|
||||
|
||||
@@ -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 <libra_worker.py -c>` 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 <libra_worker.py -n>` 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 <libra_worker.py -p>`
|
||||
option) and the directory where the log files will be written
|
||||
(:option:`--logfile <libra_worker.py -l>` option) exists and is writable
|
||||
by the user/group specified with the :option:`--user <libra_worker.py --user>`
|
||||
and :option:`--group <libra_worker.py --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.
|
||||
|
||||
Reference in New Issue
Block a user