diff --git a/doc/admin_api/api.rst b/doc/admin_api/api.rst index 0409e403..2567d408 100644 --- a/doc/admin_api/api.rst +++ b/doc/admin_api/api.rst @@ -1,378 +1,775 @@ -LBaaS Device API -================ +Admin API REST Inteface (v2) +============================ -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 +Introduction ------------ +This is the new Admin API interface for the LBaaS system. It will allow the engineers as well as support teams to perform basic tasks on the LBaaS system without direct access using Salt, SSH or MySQL. It can also be used to automate tasks such as monitoring overall system health. -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. +Authentication & Security +------------------------- +Authentication will be performed in a similar way to the main API server, via. keystone to anyone registered to our service. There will be, however, one crucial addition. The database will contain a list of tenant IDs that can actually use the Admin API, anyone else will get a 401 response. This will also have two levels of access for now we will call 'staff' (USER) and 'administrators' (ADMIN). In addition to this the Admin API's port will be restricted to users on a VPN. -Base URL and port -^^^^^^^^^^^^^^^^^ +Since this is an Admin API all actions should be well logged along with the tenantID of the user who actioned them. -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, +API Sections +------------ +The Admin API will initially be divided into three distinct sections, Devices, LoadBalancers and Status. Once we have per-customer defined limits a new section should be added to support that. In the table below the following conventions are used: -``https://lbaas-service:8889/v1/devices/...`` +{baseURI} - the endpoint address/IP for the Admin API server -would access the LBaaS system hosted on lbaas-service, using HTTPS on -port 8889 using version 1 of the API. +{ver} - The version number (1.0 already exists as a system Admin API, 2.0 shall be the first version) -Exceptions -^^^^^^^^^^ +{lbID} - The load balancer ID -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: +{deviceID} - The device ID -*Example of a bad request JSON error response body* ++---------------+----------------------------------+--------+---------------------------------------------+ +| Resource | Operation | Method | Path | ++===============+==================================+========+=============================================+ +| Devices | Get a list of devices | GET | {baseURI}/{ver}/devices | ++---------------+----------------------------------+--------+---------------------------------------------+ +| Devices | Get a single device | GET | {baseURI}/{ver}/devices/{deviceID} | ++---------------+----------------------------------+--------+---------------------------------------------+ +| Devices | Get a device version | GET | {baseURI}/{ver}/devices/{deviceID}/discover | ++---------------+----------------------------------+--------+---------------------------------------------+ +| Devices | Deletes a device | DELETE | {baseURI}/{ver}/devices/{deviceID} | ++---------------+----------------------------------+--------+---------------------------------------------+ +| LoadBalancers | Get a list of load balancers | GET | {baseURI}/{ver}/loadbalancers | ++---------------+----------------------------------+--------+---------------------------------------------+ +| LoadBalancers | Gets a single load balancer | GET | {baseURI}/{ver}/loadbalancers/{lbID} | ++---------------+----------------------------------+--------+---------------------------------------------+ +| LoadBalancers | Delete a single load balancer | DELETE | {baseURI}/{ver}/loadbalancers/{lbID} | ++---------------+----------------------------------+--------+---------------------------------------------+ +| Status | Get a pool status | GET | {baseURI}/{ver}/status/pool | ++---------------+----------------------------------+--------+---------------------------------------------+ +| Status | Get the counters | GET | {baseURI}/{ver}/status/counters | ++---------------+----------------------------------+--------+---------------------------------------------+ +| Status | Get a service status | GET | {baseURI}/{ver}/status/service | ++---------------+----------------------------------+--------+---------------------------------------------+ +| Status | Get the global service limits | GET | {baseURI}/{ver}/status/limits | ++---------------+----------------------------------+--------+---------------------------------------------+ +| Status | Change the global service limits | PUT | {baseURI}/{ver}/status/limits | ++---------------+----------------------------------+--------+---------------------------------------------+ +| Status | Get a tenant's service limits | GET | {baseURI}/{ver}/status/limits/{tenantID} | ++---------------+----------------------------------+--------+---------------------------------------------+ +| Status | Change a tenant's service limits | PUT | {baseURI}/{ver}/status/limits/{tenantID} | ++---------------+----------------------------------+--------+---------------------------------------------+ +| User | Get a list of Admin API users | GET | {baseURI}/{ver}/user | ++---------------+----------------------------------+--------+---------------------------------------------+ +| User | Get an Admin API user | GET | {baseURI}/{ver}/user/{tenantID} | ++---------------+----------------------------------+--------+---------------------------------------------+ +| User | Delete an Admin API user | DELETE | {baseURI}/{ver}/user/{tenantID} | ++---------------+----------------------------------+--------+---------------------------------------------+ +| User | Add an Admin API user | POST | {baseURI}/{ver}/user | ++---------------+----------------------------------+--------+---------------------------------------------+ +| User | Modify an Admin API user | PUT | {baseURI}/{ver}/user/{tenantID} | ++---------------+----------------------------------+--------+---------------------------------------------+ -:: +Get a list of devices +--------------------- +This will be used to get either a whole list of devices or a filtered list given certain criteria. A future expansion to this would be to add pagination support. - { - "message":"Bad Request", - "details":"device name : lbaas-10.5.251.48 already exists", - "code":400 - } +Request type +^^^^^^^^^^^^ +GET -Base URI -^^^^^^^^ +Path +^^^^ +/2.0/devices -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 +Access ^^^^^^ +It should be available to both 'staff' and 'administrators'. -*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'. +Response codes +^^^^^^^^^^^^^^ +Success: 200 -address -^^^^^^^ +Failure: 400 (Bad request), 500 (Service error) -*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 +Query parameters supported ^^^^^^^^^^^^^^^^^^^^^^^^^^ +* status - A specified status type to filter by such as 'OFFLINE', 'ONLINE' or 'ERROR' +* name - A specified device name (in a future version we could accept wildcards) +* ip - A specified device ip address (in a future version we could accept ranges) +* vip - A specified floating ip address (in a future version we could accept ranges) -:: +Response Example +^^^^^^^^^^^^^^^^ - { - "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 - } +.. code-block:: json -Operations -========== + {"devices": [ + { + "id": 123, + "name": "7908c1f2-1bce-11e3-bcd3-fa163e9790b4", + "status": "OFFLINE", + "ip": "15.125.30.123", + "vip": null, + "created": "2013-05-12 12:13:54", + "updated": "2013-06-02 14:21:31" + } + ]} -Get all Devices ---------------- +Get a single device +------------------- +This will be used to get details of a single device specified by its ID. This will contain additional information such as load balancers attached to a given device. -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 +Request type ^^^^^^^^^^^^ +GET -A JSON request body is required for this request. +Path +^^^^ +/2.0/devices/{id} -:: +Access +^^^^^^ +It should be available to both 'staff' and 'administrators'. - { - "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" - } +Response codes +^^^^^^^^^^^^^^ +Success: 200 -Example -^^^^^^^ +Failure: 400 (Bad request), 500 (Service error), 404 (Not found) -:: +Query parameters supported +^^^^^^^^^^^^^^^^^^^^^^^^^^ +Not applicable - curl -X POST -H "Content-type:application/json" --data-binary "@device.json" -k https://15.185.107.220:8889/v1/devices +Response Example +^^^^^^^^^^^^^^^^ -Response: +.. code-block:: json -:: + { + "id": 123, + "name": "7908c1f2-1bce-11e3-bcd3-fa163e9790b4", + "status": "ONLINE", + "ip": "15.125.30.123", + "vip": "15.125.50.45", + "created": "2013-05-12 12:13:54", + "updated": "2013-06-02 14:21:31", + "loadBalancers": [ + { + "id": 5263 + } + ] + } - { - "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 +Get a device version -------------------- +This will be used to send a DISCOVER gearman message to a given device's worker and get its version response. -This call allows obtaining usage summary information for all devices. +Request type +^^^^^^^^^^^^ +GET -:: +Path +^^^^ +/2.0/devices/{id}/discover - GET /devices/usage +Access +^^^^^^ +It should be available to both 'staff' and 'administrators'. -Return Status -^^^^^^^^^^^^^ +Response codes +^^^^^^^^^^^^^^ +Success: 200 -200 on success, 500 for internal error +Failure: 400 (Bad request), 500 (Service error), 404 (Not found) -Example -^^^^^^^ +Query parameters supported +^^^^^^^^^^^^^^^^^^^^^^^^^^ +Not applicable -:: +Response Example +^^^^^^^^^^^^^^^^ - curl -k https://15.185.107.220:8889/v1/devices/usage +.. code-block:: json -Response: + { + "id": 123, + "version": "1.0", + "release": "1.0.alpha.3.gca84083" + } -:: +Delete a device +--------------- +This will be used to delete a device, if the device has load balancers attached these will be moved to a new device. Typically this could be used for worker upgrades, going through each device rebuilding it using a a pool with newer workers. If there are no load balancers attached it should just mark the device for deletion, in this scenario a 204 with empty body will be returned. - { - "total": 100, - "free" : 50, - "taken": 50 - } +Request type +^^^^^^^^^^^^ +DELETE +Path +^^^^ +/2.0/devices/{id} + +Access +^^^^^^ +It should be available to 'administrators' only. + +Response codes +^^^^^^^^^^^^^^ +Success: 200 or 204 + +Failure: 400 (Bad request), 500 (Service error), 404 (Not found) + +Query parameters supported +^^^^^^^^^^^^^^^^^^^^^^^^^^ +Not applicable + +Response Example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "oldId": 123, + "newId": 148 + } + +Get a list of LoadBalancers +--------------------------- +This will be used to get a list of all load balancers or a filtered list using given criteria. A future expansion to this would be to add pagination support. + +Request type +^^^^^^^^^^^^ +GET + +Path +^^^^ +/2.0/loadbalancers + +Access +^^^^^^ +It should be available to both 'staff' and 'administrators'. + +Response codes +^^^^^^^^^^^^^^ +Success: 200 + +Failure: 400 (Bad request), 500 (Service error) + +Query parameters supported +^^^^^^^^^^^^^^^^^^^^^^^^^^ +* status - A specified status type to filter by such as 'ACTIVE', 'DEGRADED' or 'ERROR' +* tenant - The tenant/project ID for a given customer +* name - A specified device name (in a future version we could accept wildcards) +* ip - A specified device ip address (in a future version we could accept ranges) +* vip - A specified floating ip address (in a future version we could accept ranges) + +Response Example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + {"loadBalancers": [ + { + "id": 4561, + "name": "my load balancer", + "status": "ACTIVE", + "tenant": 8637027649, + "vip": "15.125.30.123", + "protocol": "HTTP", + "algorithm": "ROUND_ROBIN", + "port": 80, + "created": "2013-05-12 12:13:54", + "updated": "2013-06-02 14:21:31" + } + ]} + +Get a single LoadBalancer +------------------------- +This will be used to get details of a single load balancer specified by its ID. This will contain additional information such as nodes attached to the load balancer and which device is used. + +Request type +^^^^^^^^^^^^ +GET + +Path +^^^^ +/2.0/loadbalancers/{id} + +Access +^^^^^^ +It should be available to both 'staff' and 'administrators'. + +Response codes +^^^^^^^^^^^^^^ +Success: 200 + +Failure: 400 (Bad request), 500 (Service error), 404 (Not found) + +Query parameters supported +^^^^^^^^^^^^^^^^^^^^^^^^^^ +Not applicable + +Response Example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "id": 4561, + "name": "my load balancer", + "status": "ACTIVE", + "tenant": 8637027649, + "vip": "15.125.30.123", + "protocol": "HTTP", + "algorithm": "ROUND_ROBIN", + "port": 80, + "device": 123, + "created": "2013-05-12 12:13:54", + "updated": "2013-06-02 14:21:31", + "nodes": [ + { + "ip": "15.185.23.157", + "port": 80, + "weight": 1, + "enabled": true, + "status": "ONLINE" + } + ], + "monitor": { + "type": "HTTP", + "delay": "30", + "timeout": "30", + "attemptsBeforeDeactivation": "2", + "path": "/healthcheck" + } + } + +Delete a single LoadBalancer (NOT IMPLEMENTED!) +----------------------------------------------- +This will be used to delete a single load balancer in the same way a given user would. + +Request type +^^^^^^^^^^^^ +DELETE + +Path +^^^^ +/2.0/loadbalancers/{id} + +Access +^^^^^^ +It should be available to 'administrators' only. + +Response codes +^^^^^^^^^^^^^^ +Success: 204 + +Failure: 400 (Bad request), 500 (Service error), 404 (Not found) + +Query parameters supported +^^^^^^^^^^^^^^^^^^^^^^^^^^ +Not applicable + +Get pool status +--------------- +This is used to get an overview of the current status of the load balancer pool + +Request type +^^^^^^^^^^^^ +GET + +Path +^^^^ +/2.0/status/pool + +Access +^^^^^^ +It should be available to both 'staff' and 'administrators'. + +Response codes +^^^^^^^^^^^^^^ +Success: 200 + +Failure: 400 (Bad request), 500 (Service error) + +Query parameters supported +^^^^^^^^^^^^^^^^^^^^^^^^^^ +Not applicable + +Response Example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "devices": { + "used": 325, + "available": 50, + "error": 3, + "pendingDelete": 2 + }, + "vips": { + "used": 325, + "available": 15, + "bad" 2 + } + } + +Get counters +------------ +This is used to get the current counters from the API server. There is no reset for this at the moment so this is from the first installation of a version of the API supporting counters. + +Request type +^^^^^^^^^^^^ +GET + +Path +^^^^ +/2.0/status/counters + +Access +^^^^^^ +It should be available to both 'staff' and 'administrators'. + +Response codes +^^^^^^^^^^^^^^ +Success: 200 + +Failure: 400 (Bad request), 500 (Service error) + +Response example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + [ + { + "name": "loadbalancers_rebuild", + "value": 10 + }, + { + "name": "loadbalancers_error", + "value": 0 + } + ] + +Get service status +------------------ +This is used to get the health of vital service components. It will initially test all MySQL and Gearman servers to see if they are online. + +Request type +^^^^^^^^^^^^ +GET + +Path +^^^^ +/2.0/status/service + +Access +^^^^^^ +It should be available to both 'staff' and 'administrators'. + +Response codes +^^^^^^^^^^^^^^ +Success: 200 + +Failure: 400 (Bad request), 500 (Service error) + +Response example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "mysql": [ + { + "ip": "15.185.14.125", + "status": "ONLINE" + } + ], + "gearman": [ + { + "ip": "15.185.14.75", + "status": "OFFLINE" + } + ] + } + +Get global service limits +------------------------- +This is used to get the defined global limits (executed per-tenant) of the service. + +Request type +^^^^^^^^^^^^ +GET + +Path +^^^^ +/2.0/status/limits + +Access +^^^^^^ +It should be available to both 'staff' and 'administrators'. + +Response codes +^^^^^^^^^^^^^^ +Success: 200 + +Failure: 400 (Bad request), 500 (Service error) + +Response example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "maxLoadBalancerNameLength": 128, + "maxVIPsPerLoadBalancer": 1, + "maxNodesPerLoadBalancer": 50, + "maxLoadBalancers": 20 + } + +Change global service limits +---------------------------- +This is used to modify the global limits of the service. It can be used to modify maxLoadBalancerNameLength, maxVIPsPerLoadBalancer, maxNodesPerLoadBalancer and/or maxLoadBalancers. + +Request type +^^^^^^^^^^^^ +PUT + +Path +^^^^ +/2.0/status/limits + +Access +^^^^^^ +It should be available to 'administrators' only. + +Request body example +^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "maxNodesPerLoadBalancer": 75 + } + +Response codes +^^^^^^^^^^^^^^ +Success: 204 + +Failure: 400 (Bad request), 500 (Service error) + +Get a tenant's service limits +----------------------------- +This is used to get individual tenant limits of the service (currently only maxLoadBalancers). + +Request type +^^^^^^^^^^^^ +GET + +Path +^^^^ +/2.0/status/limits/{tenantID} + +Access +^^^^^^ +It should be available to both 'staff' and 'administrators'. + +Response codes +^^^^^^^^^^^^^^ +Success: 200 + +Failure: 400 (Bad request), 500 (Service error) + +Response example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "maxLoadBalancers": 20 + } + +Change a tenant's service limits +-------------------------------- +This is used to modify a tenant's limits of the service, if there is no current individual tenant limit a new one will be set. It can currently be used to modify maxLoadBalancers only. + +Request type +^^^^^^^^^^^^ +PUT + +Path +^^^^ +/2.0/status/limits/{tenantID} + +Access +^^^^^^ +It should be available to 'administrators' only. + +Request body example +^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "maxLoadBalancers": 75 + } + +Response codes +^^^^^^^^^^^^^^ +Success: 204 + +Failure: 400 (Bad request), 500 (Service error) + +List Admin API users +-------------------- +This is used to get a list of users for the admin API with their access levels, USER (referred to as staff in this document) or ADMIN + +Request type +^^^^^^^^^^^^ +GET + +Path +^^^^ +/2.0/user + +Access +^^^^^^ +It should be available to 'administrators' only. + +Response codes +^^^^^^^^^^^^^^ +Success: 200 + +Failure: 400 (Bad request), 500 (Service error) + +Response example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + [ + { + "tenant": "123456", + "level": "USER" + }, + { + "tenant": "654321", + "level": "ADMIN" + } + ] + +Get an Admin API user +--------------------- +This is used to get a single user for the admin API with their access levels, USER (referred to as staff in this document) or ADMIN + +Request type +^^^^^^^^^^^^ +GET + +Path +^^^^ +/2.0/user/{tenantID} + +Access +^^^^^^ +It should be available to 'administrators' only. + +Response codes +^^^^^^^^^^^^^^ +Success: 200 + +Failure: 400 (Bad request), 500 (Service error) + +Response example +^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "tenant": "123456", + "level": "USER" + } + +Delete an Admin API user +------------------------ +This is used to delete a single user for the admin API with their access levels, USER (referred to as staff in this document) or ADMIN + +Request type +^^^^^^^^^^^^ +DELETE + +Path +^^^^ +/2.0/user/{tenantID} + +Access +^^^^^^ +It should be available to 'administrators' only. + +Response codes +^^^^^^^^^^^^^^ +Success: 204 + +Failure: 400 (Bad request), 500 (Service error) + +Add an Admin API user +--------------------- +This is used to add a single user for the admin API with their access levels, USER (referred to as staff in this document) or ADMIN + +Request type +^^^^^^^^^^^^ +POST + +Path +^^^^ +/2.0/user + +Access +^^^^^^ +It should be available to 'administrators' only. + +Request body example +^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "tenant": 654321, + "level": "ADMIN" + } + +Response codes +^^^^^^^^^^^^^^ +Success: 200 + +Failure: 400 (Bad request), 500 (Service error) + +Modify an Admin API user +------------------------ +This is used to modify a single user for the admin API with their access levels, USER (referred to as staff in this document) or ADMIN + +Request type +^^^^^^^^^^^^ +POST + +Path +^^^^ +/2.0/user/{tenantID} + +Access +^^^^^^ +It should be available to 'administrators' only. + +Request body example +^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: json + + { + "level": "ADMIN" + } + +Response codes +^^^^^^^^^^^^^^ +Success: 200 + +Failure: 400 (Bad request), 500 (Service error) diff --git a/doc/admin_api/config.rst b/doc/admin_api/config.rst index 0d40d92a..2effd8f6 100644 --- a/doc/admin_api/config.rst +++ b/doc/admin_api/config.rst @@ -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 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 + + 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 The drivers to be used for alerting. This option can be used multiple diff --git a/doc/admin_api/index.rst b/doc/admin_api/index.rst index 0295e81a..4a200638 100644 --- a/doc/admin_api/index.rst +++ b/doc/admin_api/index.rst @@ -11,3 +11,4 @@ Libra Admin API Server schedulers stats-drivers api + v1api diff --git a/doc/admin_api/v1api.rst b/doc/admin_api/v1api.rst new file mode 100644 index 00000000..2589a751 --- /dev/null +++ b/doc/admin_api/v1api.rst @@ -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: + +`` = 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 + } +