libra/doc/worker/messages.rst

Worker Messages

The worker expects several different types of JSON messages. Below are examples of each. The :py~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

{
  "hpcs_action": "UPDATE",
  "loadBalancers": [
    {
      "name": "a-new-loadbalancer",
      "protocol": "http",
      "nodes": [
        {
          "address": "10.0.0.1",
          "port": "80",
          "weight": "1"
        }
      ]
    }
  ]
}

Example Response

{
  "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

{
  "hpcs_action": "SUSPEND"
}

Example Response

{
  "hpcs_action": "SUSPEND",
  "hpcs_response": "PASS"
}

ENABLE Message

The ENABLE message will reenable a previously suspsended load balancer.

Required Fields

• hpcs_action

Example Request

{
  "hpcs_action": "ENABLE"
}

Example Response

{
  "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

{
  "hpcs_action": "DELETE"
}

Example Response

{
  "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

{
  "hpcs_action": "DIAGNOSTICS"
}

Example Response

{
  "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 <major>.<minor>.

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

{
  "hpcs_action": "DISCOVER"
}

Example Response

{
  "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

{
  "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

{
  "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

{
  "hpcs_action": "STATS"
}

Example Response

{
  "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

{
  "hpcs_action": "METRICS"
}

Example Response

{
  "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"
}