379 lines
8.7 KiB
ReStructuredText
379 lines
8.7 KiB
ReStructuredText
LBaaS Device API (v1, DEPRECATED)
|
|
=================================
|
|
|
|
Description
|
|
-----------
|
|
|
|
The LBaaS service provides two classes of APIs including a tenant facing
|
|
API and admin API. The admin API is designed for internal usage to allow
|
|
administration of the LBaaS service itself. As part of this, the *Device
|
|
API* allows for managing devices which are the actual load balancer
|
|
devices used by LBaaS.
|
|
|
|
API Overview
|
|
------------
|
|
|
|
The device API is not visible to tenants thus it is designed to operate
|
|
on its own HTTPS port which is configurable. The device API only
|
|
supports a JSON resource representation for reading and writing. The API
|
|
is designed as a RESTful API including support of CRUD operations for
|
|
creating, reading, updating and deleting devices.
|
|
|
|
Base URL and port
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
All device API calls run on the same TCP port and require HTTPS for
|
|
access. The specific HTTPS port and certificate are configurable by the
|
|
LBaaS service and will comply with the Cloud security requirements
|
|
including the certificate signing. The API is version'ed such that all
|
|
calls are prefixed with a version URI. For example,
|
|
|
|
``https://lbaas-service:8889/v1/devices/...``
|
|
|
|
would access the LBaaS system hosted on lbaas-service, using HTTPS on
|
|
port 8889 using version 1 of the API.
|
|
|
|
Exceptions
|
|
^^^^^^^^^^
|
|
|
|
As a RESTful service, the device API can return standard HTTP status
|
|
codes with each request including success and error codes mentioned
|
|
below. In the event a non 200 series status is returned, a JSON
|
|
formatted error body is provided with additional details. The format of
|
|
the JSON error body is as follows:
|
|
|
|
*Example of a bad request JSON error response body*
|
|
|
|
::
|
|
|
|
{
|
|
"message":"Bad Request",
|
|
"details":"device name : lbaas-10.5.251.48 already exists",
|
|
"code":400
|
|
}
|
|
|
|
Base URI
|
|
^^^^^^^^
|
|
|
|
All LBaaS Device API calls have a common base URI defined as follows:
|
|
|
|
``<baseURI> = https://<lbaas-system-addr>:<lbaas-device-port>/v1``
|
|
|
|
- *lbaas-system-addr* is the system name / address where the LBaaS API
|
|
service is running.
|
|
|
|
- *lbaas-device-port* is the TCP port in which the device service is
|
|
listening for HTTPS REST requests.
|
|
|
|
- */v1/devices* will prefix all REST calls.
|
|
|
|
Device Data Model
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
Device REST calls allow reading and writing device resources represented
|
|
in JSON. The data model for devices is defined as follows:
|
|
|
|
id
|
|
^^
|
|
|
|
*id* is an integer representing a unique id for the device. *id* is
|
|
created by the LBaaS service when devices are created. *id* is used to
|
|
reference devices as the REST collection id.
|
|
|
|
updated
|
|
^^^^^^^
|
|
|
|
*updated* is a text string representing the last time this device
|
|
resource was updated.
|
|
|
|
created
|
|
^^^^^^^
|
|
|
|
*created* is a text string representing when the device was created.
|
|
|
|
status
|
|
^^^^^^
|
|
|
|
*status* is a text string representing the status of the device as
|
|
reported by the device to the LBaaS service ( this is done through the
|
|
gearman client / worker interface ). Status values can be 'OFFLINE',
|
|
'ONLINE', 'ERROR'.
|
|
|
|
address
|
|
^^^^^^^
|
|
|
|
*address* is the IPv4 or IPV6 address of the device. This is the adress
|
|
which will be used as the loadbalancer's address used by the customer.
|
|
Note, this should be a Nova floating IP address for usage with HAProxy
|
|
on Nova.
|
|
|
|
name
|
|
^^^^
|
|
|
|
*name* is the name of the device which is used internally by LBaaS as
|
|
the gearman worker name. Each device name is specified by the pool
|
|
manager and must be unique for each device. The format of the name is
|
|
``lbaas-<version>-<id>`` where ``<version>`` is the gearman worker
|
|
version e.g. *v1* and ``<id>`` is a unique UUID for the name.
|
|
|
|
loadbalancer
|
|
^^^^^^^^^^^^
|
|
|
|
*loadbalancer* are references to logical loadbalancers who are using
|
|
this device. This is a list of one or more integers. An empty or zero
|
|
value denotes that this device is not used and is free. Note, if the
|
|
device is not in use, it has no customer loadbalancer config and is in a
|
|
'OFFLINE' state.
|
|
|
|
type
|
|
^^^^
|
|
|
|
*type* is a text string describing the type of device. Currently only
|
|
'HAProxy' is supported.
|
|
|
|
Example of a single device
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
{
|
|
"id": 1,
|
|
"updated": "2013-06-10T14:29:14",
|
|
"created": "2013-06-10T14:29:14",
|
|
"status": "OFFLINE",
|
|
"floatingIpAddress": "15.185.96.125",
|
|
"publicIpAddress": "15.185.96.125",
|
|
"name": "lbaas-v1-067e6162-3b6f-4ae2-a171-2470b63dff00",
|
|
"loadBalancers": [{"id": 10313, "tenantid": "42374872347634"}],
|
|
"type": "basename: libra-haproxy, image: 12345",
|
|
"az": 2
|
|
}
|
|
|
|
Operations
|
|
==========
|
|
|
|
Get all Devices
|
|
---------------
|
|
|
|
Get all devices currently defined.
|
|
|
|
::
|
|
|
|
GET <baseURI>/devices
|
|
|
|
Return Status
|
|
^^^^^^^^^^^^^
|
|
|
|
200 on success, 500 for internal error
|
|
|
|
Example
|
|
^^^^^^^
|
|
|
|
::
|
|
|
|
curl -k https://15.185.107.220:8889/v1/devices
|
|
|
|
Response:
|
|
|
|
::
|
|
|
|
{
|
|
"devices": [
|
|
{
|
|
"id": 1,
|
|
"updated": "2013-06-10T14:29:14",
|
|
"created": "2013-06-10T14:29:14",
|
|
"status": "OFFLINE",
|
|
"floatingIpAddress ":"15.185.96.125",
|
|
"publicIpAddress": "15.185.96.125",
|
|
"name": "lbaas-v1-067e6162-3b6f-4ae2-a171-2470b63dff00",
|
|
"loadBalancers": [{"id": 10313, "tenantid": "42374872347634"}],
|
|
"type": "basename: libra-haproxy, image: 12345",
|
|
"az": 2
|
|
}
|
|
]
|
|
}
|
|
|
|
Get a Device
|
|
------------
|
|
|
|
Get a specific device.
|
|
|
|
::
|
|
|
|
GET <baseURI>/devices/{deviceId}
|
|
|
|
Return Status
|
|
^^^^^^^^^^^^^
|
|
|
|
200 on success, 404 not found, 500 for internal error
|
|
|
|
Example
|
|
^^^^^^^
|
|
|
|
::
|
|
|
|
curl -k https://15.185.107.220:8889/v1/devices/1
|
|
|
|
Response:
|
|
|
|
::
|
|
|
|
{
|
|
"id": 1,
|
|
"updated": "2013-06-10T14:29:14",
|
|
"created": "2013-06-10T14:29:14",
|
|
"status": "OFFLINE",
|
|
"floatingIpAddress": "15.185.96.125",
|
|
"publicIpAddress": "15.185.96.125",
|
|
"name": "lbaas-v1-067e6162-3b6f-4ae2-a171-2470b63dff00",
|
|
"loadBalancers": [{"id": 10313, "tenantid": "42374872347634"}],
|
|
"type": "basename: libra-haproxy, image: 12345",
|
|
"az": 2
|
|
}
|
|
|
|
Create a Device
|
|
---------------
|
|
|
|
Create a new device will register an already deployed device with the
|
|
LBaaS service. In order to do so, LBaaS will need to know its name and
|
|
address. Returned will be the new device including its *id*.
|
|
|
|
::
|
|
|
|
POST <baseURI>/devices
|
|
|
|
Return Status
|
|
^^^^^^^^^^^^^
|
|
|
|
200 on success, 400 bad request, 500 for internal error
|
|
|
|
Request Body
|
|
^^^^^^^^^^^^
|
|
|
|
A JSON request body is required for this request.
|
|
|
|
::
|
|
|
|
{
|
|
"name": "lbaas-v1-067e6162-3b6f-4ae2-a171-2470b63dff00",
|
|
"publicIpAddress": "15.185.96.125",
|
|
"floatingIpAddress": "15.185.96.125",
|
|
"az": 2,
|
|
"type": "basename: libra-haproxy, image: 12345"
|
|
}
|
|
|
|
Example
|
|
^^^^^^^
|
|
|
|
::
|
|
|
|
curl -X POST -H "Content-type:application/json" --data-binary "@device.json" -k https://15.185.107.220:8889/v1/devices
|
|
|
|
Response:
|
|
|
|
::
|
|
|
|
{
|
|
"id": 1,
|
|
"updated": "2013-06-10T14:29:14",
|
|
"created": "2013-06-10T14:29:14",
|
|
"status": "OFFLINE",
|
|
"floatingIpAddress": "15.185.96.125",
|
|
"publicIpAddress": "15.185.96.125",
|
|
"name": "lbaas-v1-067e6162-3b6f-4ae2-a171-2470b63dff00",
|
|
"loadBalancers": [{"id": 10313, "tenantid": "42374872347634"}],
|
|
"type": "basename: libra-haproxy, image: 12345",
|
|
"az": 2
|
|
}
|
|
|
|
Delete a Device
|
|
---------------
|
|
|
|
Delete a device will delete a device from the LBaaS service. Note, this
|
|
call can be dangerous and effect a customers load balancer if it is in
|
|
use. *please use this call with extreme caution!*.
|
|
|
|
::
|
|
|
|
DELETE <baseURI>/devices/{deviceId}
|
|
|
|
Return Status
|
|
^^^^^^^^^^^^^
|
|
|
|
204 on success, 400 bad request, 500 for internal error
|
|
|
|
Example
|
|
^^^^^^^
|
|
|
|
::
|
|
|
|
curl -X DELETE -k https://15.185.107.220:8889/v1/devices/1
|
|
|
|
Update a Device
|
|
---------------
|
|
|
|
Update the status of a device, it can set the status to `ERROR` or `ONLINE`
|
|
and the statusDescription field. No other fields can be changed and will be
|
|
ignored.
|
|
|
|
::
|
|
|
|
PUT <baseURI>/devices/{deviceId}
|
|
|
|
Return Status
|
|
^^^^^^^^^^^^^
|
|
|
|
200 on success, 400 bad request, 500 for internal error
|
|
|
|
Request Body
|
|
^^^^^^^^^^^^
|
|
|
|
A JSON request body is required for this request.
|
|
|
|
::
|
|
|
|
{
|
|
"status": "ERROR",
|
|
"statusDescription": "Load Balancer has failed"
|
|
}
|
|
|
|
Example
|
|
^^^^^^^
|
|
|
|
::
|
|
|
|
curl -X PUT -H "Content-type:application/json" --data-binary "@device.json" -k https://15.185.107.220:8889/v1/devices/1
|
|
|
|
Get Usage of Devices
|
|
--------------------
|
|
|
|
This call allows obtaining usage summary information for all devices.
|
|
|
|
::
|
|
|
|
GET <baseURI>/devices/usage
|
|
|
|
Return Status
|
|
^^^^^^^^^^^^^
|
|
|
|
200 on success, 500 for internal error
|
|
|
|
Example
|
|
^^^^^^^
|
|
|
|
::
|
|
|
|
curl -k https://15.185.107.220:8889/v1/devices/usage
|
|
|
|
Response:
|
|
|
|
::
|
|
|
|
{
|
|
"total": 100,
|
|
"free" : 50,
|
|
"taken": 50
|
|
}
|
|
|