[DOCS] Add v2 Admin API docs
Change-Id: I471eb79c06b7c12645a8a133759fb3cef96740be
This commit is contained in:
Andrew Hutchings
parent
6aabea4b51
commit
622eda08c1
File diff suppressed because it is too large
Load Diff
@ -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
|
||||
|
||||
@ -11,3 +11,4 @@ Libra Admin API Server
|
||||
schedulers
|
||||
stats-drivers
|
||||
api
|
||||
v1api
|
||||
|
||||
378
doc/admin_api/v1api.rst
Normal file
378
doc/admin_api/v1api.rst
Normal 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
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user