LBaaS Device API ================ 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: `` = https://:/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--`` where ```` is the gearman worker version e.g. *v1* and ```` 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 /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 /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 /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 /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 /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 /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 }