stackforge/libra
Code Issues Proposed changes

Update worker documentation.

Browse Source 
Make some corrections and add some preliminary docs for worker messages.

Change-Id: I603bac7e674c2ab667a3e9bb523d8f1c01292563
This commit is contained in:
David Shrewsbury
2013-04-03 13:18:40 -04:00
parent c99bb8d4da
commit c38fbe1557
4 changed files with 282 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
doc/worker/about.rst
View File

@@ -77,12 +77,7 @@ 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!**
and :option:`--group <libra_worker.py --group>` options.
You can verify that the worker is running by using the sample Gearman
client in the bin/ directory::

7
doc/worker/code.rst
View File

@@ -73,8 +73,9 @@ LoadBalancerDriver Class
Generally, an appliance driver should queue up any configuration changes
made via these API calls until the :py:meth:`create` method is called.
The :py:meth:`suspend`, :py:meth:`enable`, and :py:meth:`delete` methods
should take immediate action.
The :py:meth:`suspend`, :py:meth:`enable`, :py:meth:`delete`,
:py:meth:`get_stats()` and :py:meth:`archive` methods should take
immediate action.
.. py:method:: init()
@@ -94,6 +95,8 @@ LoadBalancerDriver Class
.. py:method:: get_stats()
.. py:method:: archive()
Known Load Balancer Drivers Dictionary
--------------------------------------

1
doc/worker/index.rst
View File

@@ -6,3 +6,4 @@ Libra Gearman Worker
about
code
messages

275
doc/worker/messages.rst Normal file
View File

@@ -0,0 +1,275 @@
Worker Messages
===============
.. py:module:: libra.worker.controller
The worker expects several different types of JSON messages. Below are examples
of each. The :py:class:`~LBaaSController` class expects the messages to be
one of the types defined below.
Some things in common with all messages:
* The type is determined by the **hpcs_action**
field of the JSON message, which is required to be present.
* The casing of the JSON field names or values does not matter.
* Extraneous fields are ignored.
* Every response will return the original message with some additional fields.
* Every response will include a **hpcs_response** field with a value of either
*PASS* or *FAIL*. Additional fields will vary depending on message type.
UPDATE Message
--------------
The UPDATE message creates or updates the load balancer configuration.
Either one or two load balancers may be defined within this message. If two
are defined, one must be with the HTTP protocol and the other must be with
the TCP protocol. No other exceptions are allowed.
Required Fields
^^^^^^^^^^^^^^^
* hpcs_action
* loadbalancers
* loadbalancers.protocol
* loadbalancers.nodes
* loadbalancers.nodes.address
* loadbalancers.nodes.port
Example Request
^^^^^^^^^^^^^^^
.. code-block:: json
{
"hpcs_action": "UPDATE",
"loadbalancers": [
{
"name": "a-new-loadbalancer",
"protocol": "http",
"nodes": [
{
"address": "10.0.0.1",
"port": "80",
"weight": "1"
}
]
}
]
}
Example Response
^^^^^^^^^^^^^^^^
.. code-block:: json
{
"hpcs_action": "UPDATE",
"loadbalancers": [
{
"name": "a-new-loadbalancer",
"protocol": "http",
"nodes": [
{
"address": "10.0.0.1",
"port": "80",
"weight": "1"
}
]
}
],
"hpcs_response": "PASS"
}
SUSPEND Message
---------------
The SUSPEND message will temporarily disable a load balancer until it is
reenabled with an ENABLE message.
Required Fields
^^^^^^^^^^^^^^^
* hpcs_action
Example Request
^^^^^^^^^^^^^^^
.. code-block:: json
{
"hpcs_action": "SUSPEND"
}
Example Response
^^^^^^^^^^^^^^^^
.. code-block:: json
{
"hpcs_action": "SUSPEND",
"hpcs_response": "PASS"
}
ENABLE Message
--------------
The ENABLE message will reenable a previously suspsended load balancer.
Required Fields
^^^^^^^^^^^^^^^
* hpcs_action
Example Request
^^^^^^^^^^^^^^^
.. code-block:: json
{
"hpcs_action": "ENABLE"
}
Example Response
^^^^^^^^^^^^^^^^
.. code-block:: json
{
"hpcs_action": "ENABLE",
"hpcs_response": "PASS"
}
DELETE Message
--------------
The DELETE message will permanently disable a load balancer. This process
is not expected to be reversible.
Required Fields
^^^^^^^^^^^^^^^
* hpcs_action
Example Request
^^^^^^^^^^^^^^^
.. code-block:: json
{
"hpcs_action": "DELETE"
}
Example Response
^^^^^^^^^^^^^^^^
.. code-block:: json
{
"hpcs_action": "DELETE",
"hpcs_response": "PASS"
}
DISCOVER Message
----------------
The DISCOVER message allows a sender (i.e., API server) to discover the version
of a running worker process. The version can then be used to decide which
messages are supported.
A **version** field will be returned in the JSON message.
Required Fields
^^^^^^^^^^^^^^^
* hpcs_action
Example Request
^^^^^^^^^^^^^^^
.. code-block:: json
{
"hpcs_action": "DISCOVER"
}
Example Response
^^^^^^^^^^^^^^^^
.. code-block:: json
{
"hpcs_action": "DISCOVER",
"version": "1.0",
"hpcs_response": "PASS"
}
ARCHIVE Message
---------------
The ARCHIVE message requests that the load balancer send any available logs
to a destination defined within the request. Currently, the only supported
destination is a Swift account.
If the request fails, **hpcs_response** will be set to *FAIL* and a field
named **hpcs_error** will be added with an error message explaining the
failure.
Required Fields
^^^^^^^^^^^^^^^
* hpcs_action
* hpcs_object_store_type
* hpcs_object_store_basepath
* hpcs_object_store_endpoint
* hpcs_object_store_token
* loadbalancers
* loadbalancers.protocol
Example Request
^^^^^^^^^^^^^^^
.. code-block:: json
{
"hpcs_action": "ARCHIVE",
"hpcs_object_store_basepath": "lbaaslogs",
"hpcs_object_store_endpoint": "https://example.com/v1/80074562416143",
"hpcs_object_store_token": "MY_AUTH_TOKEN",
"hpcs_object_store_type": "swift",
"loadbalancers": [
{
"id": "15",
"name": "lb #1",
"protocol": "HTTP"
}
]
}
Example Response
^^^^^^^^^^^^^^^^
.. code-block:: json
{
"hpcs_action": "ARCHIVE",
"hpcs_object_store_basepath": "lbaaslogs",
"hpcs_object_store_endpoint": "https://example.com/v1/80074562416143",
"hpcs_object_store_token": "MY_AUTH_TOKEN",
"hpcs_object_store_type": "swift",
"loadbalancers": [
{
"id": "15",
"name": "lb #1",
"protocol": "HTTP"
}
]
"hpcs_response": "FAIL",
"hpcs_error": "Some error string explaining the failure."
}