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 JSON field names is case-sensitive. * The JSON field values is case-insensitive. * 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" } DIAGNOSTICS Message ------------------- The DIAGNOSTICS message will run some basic network connection tests to see if the device the worker lives on is healthy. At the moment it runs a connect test to Google and a gearman connect test. Example Request ^^^^^^^^^^^^^^^ .. code-block:: json { "hpcs_action": "DIAGNOSTICS" } Example Response ^^^^^^^^^^^^^^^^ .. code-block:: json { "hpcs_action": "DIAGNOSTICS", "network": "PASS", "gearman": [ { "15.185.1.2": "PASS" }, { "15.185.1.3": "FAIL" } ], "release": "1.0.alpha.3.gca84083", "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. It will be in the format of .. A **release** field will also be returned in the JSON message. It contains more complete versioning information as returned from a 'git describe'. Required Fields ^^^^^^^^^^^^^^^ * hpcs_action Example Request ^^^^^^^^^^^^^^^ .. code-block:: json { "hpcs_action": "DISCOVER" } Example Response ^^^^^^^^^^^^^^^^ .. code-block:: json { "hpcs_action": "DISCOVER", "version": "1.0", "release": "1.0.alpha.3.gca84083", "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/100", "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/100", "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." } STATS Message ------------- The STATS message queries the worker for general availability (i.e., a ping) Currently, this doesn't do more than verify that the HAProxy process is running and we can successfully query its statistics socket. Required Fields ^^^^^^^^^^^^^^^ * hpcs_action Example Request ^^^^^^^^^^^^^^^ .. code-block:: json { "hpcs_action": "STATS" } Example Response ^^^^^^^^^^^^^^^^ .. code-block:: json { "hpcs_action": "STATS", "hpcs_response": "PASS" } METRICS Message --------------- The METRICS message queries the worker for load balancer usage metrics. The number of bytes out for each load balancer defined on the device is returned in the response. Required Fields ^^^^^^^^^^^^^^^ * hpcs_action Example Request ^^^^^^^^^^^^^^^ .. code-block:: json { "hpcs_action": "METRICS" } Example Response ^^^^^^^^^^^^^^^^ .. code-block:: json { "hpcs_action": "METRICS", "utc_start": "2014-01-09 15:11.45.704754", "utc_end": "2014-01-09 16:10.00.72683", "loadBalancers": [ { "protocol": "HTTP", "bytes_out": "12345" }, { "protocol": "TCP", "bytes_out": "5678" } ], "hpcs_response": "PASS" }