From c38fbe15576ac56a43d92f124aefdd22908232c2 Mon Sep 17 00:00:00 2001 From: David Shrewsbury Date: Wed, 3 Apr 2013 13:18:40 -0400 Subject: [PATCH] Update worker documentation. Make some corrections and add some preliminary docs for worker messages. Change-Id: I603bac7e674c2ab667a3e9bb523d8f1c01292563 --- doc/worker/about.rst | 7 +- doc/worker/code.rst | 7 +- doc/worker/index.rst | 1 + doc/worker/messages.rst | 275 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 282 insertions(+), 8 deletions(-) create mode 100644 doc/worker/messages.rst diff --git a/doc/worker/about.rst b/doc/worker/about.rst index c5d23560..b1ff9f21 100644 --- a/doc/worker/about.rst +++ b/doc/worker/about.rst @@ -77,12 +77,7 @@ 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!** +and :option:`--group ` options. You can verify that the worker is running by using the sample Gearman client in the bin/ directory:: diff --git a/doc/worker/code.rst b/doc/worker/code.rst index a136406c..d25f0896 100644 --- a/doc/worker/code.rst +++ b/doc/worker/code.rst @@ -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 -------------------------------------- diff --git a/doc/worker/index.rst b/doc/worker/index.rst index af0150f9..943c2c75 100644 --- a/doc/worker/index.rst +++ b/doc/worker/index.rst @@ -6,3 +6,4 @@ Libra Gearman Worker about code + messages diff --git a/doc/worker/messages.rst b/doc/worker/messages.rst new file mode 100644 index 00000000..026912f3 --- /dev/null +++ b/doc/worker/messages.rst @@ -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." + } +