stackforge
/
libra
Code Issues Proposed changes

[DOCS] Add v2 Admin API docs 

Change-Id: I471eb79c06b7c12645a8a133759fb3cef96740be
This commit is contained in:
Andrew Hutchings 2014-03-12 12:35:50 +00:00
parent 6aabea4b51
commit 622eda08c1
4 changed files with 1118 additions and 331 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1059
doc/admin_api/api.rst
View File

File diff suppressed because it is too large Load Diff

11
doc/admin_api/config.rst
View File

@ -17,6 +17,7 @@ Configuration File
ssl_certfile=/opt/server.crt
ssl_keyfile=/opt/server.key
gearman=127.0.0.1:4730
keystone_module=keystoneclient.middleware.auth_token:AuthProtocol
[mysql1]
host=localhost
@ -40,6 +41,10 @@ Command Line Options
The port number to listen on, default is 8889
.. option:: --disable_keystone
Do not use keystone authentication, for testing purposes only
.. option:: --db_sections <SECTIONNAME>
Config file sections that describe the MySQL servers. This option can
@ -91,6 +96,12 @@ Command Line Options
Used to specify the Gearman job server hostname and port. This option
can be used multiple times to specify multiple job servers
.. option:: --keystone_module <MODULE:CLASS>
A colon separated module and class to use as the keystone authentication
module. The class should be compatible with keystone's AuthProtocol
class.
.. option:: --stats_driver <DRIVER LIST>
The drivers to be used for alerting. This option can be used multiple

1
doc/admin_api/index.rst
View File

@ -11,3 +11,4 @@ Libra Admin API Server
schedulers
stats-drivers
api
v1api

378
doc/admin_api/v1api.rst Normal file
View File

@ -0,0 +1,378 @@
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
}