From af55574093526b659831b9f836017dba96bcee92 Mon Sep 17 00:00:00 2001 From: Endre Karlson Date: Wed, 25 Sep 2013 13:26:05 +0200 Subject: [PATCH] API documentation re-amp * Split the API into 1 section pr item aka vip, lb etc * Update docs to be up to date with features. * Add healthmonitoring section Change-Id: I3cc568a6dec089060e51da263e93c08a52c5b5d2 --- doc/api/api.rst | 1889 ++----------------------------- doc/api/rest/algorithms.rst | 116 ++ doc/api/rest/health-monitor.rst | 360 ++++++ doc/api/rest/limits.rst | 117 ++ doc/api/rest/load-balancer.rst | 746 ++++++++++++ doc/api/rest/logs.rst | 70 ++ doc/api/rest/node.rst | 539 +++++++++ doc/api/rest/protocols.rst | 107 ++ doc/api/rest/vip.rst | 101 ++ 9 files changed, 2233 insertions(+), 1812 deletions(-) create mode 100644 doc/api/rest/algorithms.rst create mode 100644 doc/api/rest/health-monitor.rst create mode 100644 doc/api/rest/limits.rst create mode 100644 doc/api/rest/load-balancer.rst create mode 100644 doc/api/rest/logs.rst create mode 100644 doc/api/rest/node.rst create mode 100644 doc/api/rest/protocols.rst create mode 100644 doc/api/rest/vip.rst diff --git a/doc/api/api.rst b/doc/api/api.rst index 64b69f1e..90253f03 100644 --- a/doc/api/api.rst +++ b/doc/api/api.rst @@ -1,6 +1,13 @@ Load Balancer as a Service (LBaaS) API Specification ==================================================== + +.. toctree:: + :maxdepth: 2 + :glob: + + rest/* + 1. Overview ----------- @@ -16,9 +23,7 @@ which are described in detail. ~~~~~~~~~~~~~~~~~~~~~~ This API definition represents the Load Balancer as a Service -in Beta release form. Functionality represented within this -specification is supported. The LBaaS API defined within this -specification represents version 1.1 of LBaaS. +in Beta release form. **Maturity Level**: *Experimental* @@ -37,7 +42,7 @@ of purposes including load balancers for your external cloud hosted services as well as internal load balancing needs. The load balancing solution is meant to provide both load balancing and high availability in an industry standard manner. The LBaaS APIs defined are integrated -within the API ecosystem including integration with the +within the API ecosystem including integration with the identity management system, billing and monitoring systems. 2.2 Conceptual/Logical Architecture View @@ -53,19 +58,21 @@ A load balancer is a logical device. It is used to distribute workloads between multiple back-end systems or services called 'nodes', based on the criteria defined as part of its configuration. -2.2.2 Virtual IP -^^^^^^^^^^^^^^^^ +2.2.2 Virtual IP Address +^^^^^^^^^^^^^^^^^^^^^^^^ -A virtual IP is an Internet Protocol (IP) address configured on the load -balancer for use by clients connecting to a service that is load +A virtual IP address is an Internet Protocol (IP) address configured on the +load balancer for use by clients connecting to a service that is load balanced. Incoming connections and requests are distributed to back-end -nodes based on the configuration of the load balancer. +nodes based on the configuration of the load balancer. The load balancer will +need to registered with the appropriate DNS domain record in order for users +to access the nodes via a domain name-based URL. 2.2.3 Node ^^^^^^^^^^ -A node is a back-end device providing a service on a specified IP and -port. +A node is a back-end device providing a service, like a web server or file +server, on a specified IP and port. The nodes defined by the load balancer are responsible for servicing the requests received through the load balancers virtual IP. By default, the @@ -74,15 +81,24 @@ listening on its defined port. The node is checked at the time of addition and at regular intervals as defined by the load balancer health check configuration. If a back-end node is not listening on its port or does not meet the conditions of the defined active health check for the -load balancer, then the loadbalancer will not forward connections or +load balancer, then the load balancer will not forward connections or requests to it and its status will be listed as OFFLINE. Only nodes that are in an ONLINE status will receive and be able to service traffic from the load balancer. +2.2.4 Heath Monitors +~~~~~~~~~~~~~~~~~~~~ + +A health monitor is a configurable, active monitoring operation that exists for all load balancer nodes. In addition to the basic health checks, active health monitoring operations periodically check your back-end nodes to ensure they are responding correctly. + +Active health monitoring offers two choices for the type of monitor it can provide; CONNECT or HTTP. CONNECT monitoring is the most basic type of health check and it does not perform post-processing or protocol specific health checks. HTTP monitoring, on the other hand, is more intelligent and it is capable of processing HTTP responses to determine the condition of a node. For both options, a user may configure the time delay between monitoring checks, the timeout period for a connection to a node, the number of attempts before removing a node from rotation and for HTTP monitoring, the HTTP path to test. + +Active health monitoring, by default is configured to use CONNECT type monitoring with a 30 second delay, 30 second timeout, and 2 retries, and it can not be disabled. The caller may configure one health monitor per load balancer and the same configuration is used to monitor all of the back-end nodes. + 2.3 Infrastructure Architecture View ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -LBaaS fits into the ecosystem of APIs by utilizing the common +LBaaS fits into the ecosystem of APIs by utilizing the same common authentication mechanisms as any other services. In order to use LBaaS, a user account must have activated "Load Balancer" service. All API calls require require a valid authentication token. @@ -91,14 +107,14 @@ All API calls require require a valid authentication token. --------------------- Once the account is activated, the LBaaS service will show up -in the service catelog returned during user login. In addition, LBaaS +in the service catalog returned during user login. In addition, LBaaS endpoints to be used will also be presented. Availability zone information may vary based on region. 3.1 Service Catalog ~~~~~~~~~~~~~~~~~~~ -Once user authenticates using REST API, a service +Once a user authenticates using RESTful API, a service catalog will list the availability of the LBaaS service, roles and endpoints for the region you have logged into and in which you are activated for. @@ -177,7 +193,7 @@ methods currently supported. As shown in the example above, logging into your region will provide you with the appropriate LBaaS endpoints to use. In addition, all supported -versions are published within the service catalog. A client may chose to +versions are published within the service catalog. A client may choose to use any LBaaS API version listed. 4.3 Request/Response Types @@ -194,22 +210,12 @@ default. ~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, the API supports persistent connections via HTTP/1.1 -'keep-alive's. All connections will be kept alive unless the connection +'keep-alives'. All connections will be kept alive unless the connection header is set to close. In adherence with the IETF HTTP RFCs, the server may close the connection at any time and clients should not rely on this behavior. -4.5 Paginated Collections -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some LBaaS APIs have the capability to return collections as a list of -many resources. To reduce load on the service, list operations will -return a maximum of 100 items at a time. To navigate the collection, -Openstack style 'limit' and 'marker' query parameters are utilized. For -example, '?limit=50&marker=1' can be set in the URI. If a marker beyond -the end of a list is given, an empty list is returned. - -4.6 Absolute Limits +4.5 Absolute Limits ~~~~~~~~~~~~~~~~~~~ Absolute limits are limits which prohibit a user from creating too many @@ -231,7 +237,7 @@ made the request. | maxVIPsPerLoadBalancer | Maximum number of Virtual IPs for each load balancer | +-----------------------------+------------------------------------------------------------+ -4.7 Faults +4.6 Faults ~~~~~~~~~~ When issuing a LBaaS API request, it is possible that an error can @@ -251,7 +257,7 @@ all faults:* "code": HTTP standard error status } -4.8 Specifying Tenant IDs +4.7 Specifying Tenant IDs ~~~~~~~~~~~~~~~~~~~~~~~~~ Tenant identifiers with LBaaS API URIs are not required. The tenant @@ -268,7 +274,7 @@ methods. Each resource and method is defined in detail in the subsequent sections. **Derived resource identifiers:** - +i **{baseURI}** is the endpoint URI returned in the service catalog upon logging in including the protocol, endpoint and base URI. @@ -297,15 +303,15 @@ by the LBaaS service. +-----------------+------------------------------------------------------------+----------+-----------------------------------------------------------------+ | Algorithms | :ref:`Get list of supported algorithms ` | GET | {baseURI}/{ver}/algorithms | +-----------------+------------------------------------------------------------+----------+-----------------------------------------------------------------+ -| Load Balancer | :ref:`Get list of all load balancers ` | GET | {baseURI}/{ver}/loadbalancers | +| Load Balancer | :ref:`Get list of all load balancers ` | GET | {baseURI}/{ver}/loadbalancers | +-----------------+------------------------------------------------------------+----------+-----------------------------------------------------------------+ -| Load Balancer | :ref:`Get load balancer details ` | GET | {baseURI}/{ver}/loadbalancers/{loadbalancerId} | +| Load Balancer | :ref:`Get load balancer details ` | GET | {baseURI}/{ver}/loadbalancers/{loadbalancerId} | +-----------------+------------------------------------------------------------+----------+-----------------------------------------------------------------+ -| Load Balancer | :ref:`Create a new load balancer ` | POST | {baseURI}/{ver}/loadbalancers | +| Load Balancer | :ref:`Create a new load balancer ` | POST | {baseURI}/{ver}/loadbalancers | +-----------------+------------------------------------------------------------+----------+-----------------------------------------------------------------+ -| Load Balancer | :ref:`Update load balancer attributes ` | PUT | {baseURI}/{ver}/loadbalancers/{loadbalancerId} | +| Load Balancer | :ref:`Update load balancer attributes ` | PUT | {baseURI}/{ver}/loadbalancers/{loadbalancerId} | +-----------------+------------------------------------------------------------+----------+-----------------------------------------------------------------+ -| Load Balancer | :ref:`Delete an existing load balancer ` | DELETE | {baseURI}/{ver}/loadbalancers/{loadbalancerId} | +| Load Balancer | :ref:`Delete an existing load balancer ` | DELETE | {baseURI}/{ver}/loadbalancers/{loadbalancerId} | +-----------------+------------------------------------------------------------+----------+-----------------------------------------------------------------+ | Node | :ref:`Get list of load balancer nodes ` | GET | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/nodes | +-----------------+------------------------------------------------------------+----------+-----------------------------------------------------------------+ @@ -321,6 +327,12 @@ by the LBaaS service. +-----------------+------------------------------------------------------------+----------+-----------------------------------------------------------------+ | Logs | :ref:`Archive log file to Object Storage ` | POST | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/logs | +-----------------+------------------------------------------------------------+----------+-----------------------------------------------------------------+ +| Health Monitor | :ref:`Get a load balancer monitor ` | GET | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/healthmonitor | ++-----------------+------------------------------------------------------------+----------+-----------------------------------------------------------------+ +| Health Monitor | :ref:`Update a load balancer monitor ` | PUT | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/healthmonitor | ++-----------------+------------------------------------------------------------+----------+-----------------------------------------------------------------+ +| Health Monitor | :ref:`Reset a load balancer monitor ` | DELETE | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/healthmonitor | ++-----------------+------------------------------------------------------------+----------+-----------------------------------------------------------------+ 5.2 Common Request Headers ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -459,14 +471,14 @@ The response body contains a list of all supported versions of LBaaS. { "versions": [ { - "id": "v1.1", + "id": "v1.1", "links": [ { - "href": "http://api-docs.hpcloud.com", + "href": "http://api-docs.hpcloud.com", "rel": "self" } - ], - "status": "CURRENT", + ], + "status": "CURRENT", "updated": "2012-12-18T18:30:02.25Z" } ] @@ -552,7 +564,7 @@ version. :: - curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1 + curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1 **Response** @@ -560,1784 +572,23 @@ version. { "version": { - "id": "v1.1", + "id": "v1.1", "links": [ { - "href": "http://api-docs.hpcloud.com", + "href": "http://api-docs.hpcloud.com", "rel": "self" } - ], + ], "media-types": [ { "base": "application/json" } - ], - "status": "CURRENT", + ], + "status": "CURRENT", "updated": "2012-12-18T18:30:02.25Z" } } -.. _api-limits: - -8. Get List of LBaaS API Limits -------------------------------- - -8.1 Operation -~~~~~~~~~~~~~ - -+------------+----------------------------+----------+--------------------------+ -| Resource | Operation | Method | Path | -+============+============================+==========+==========================+ -| Limits | Get list of LBaaS limits | GET | {baseURI}/{ver}/limits | -+------------+----------------------------+----------+--------------------------+ - -8.2 Description -~~~~~~~~~~~~~~~ - -This method allows querying the LBaaS service for a list of API limits -which apply on a tenant basis. Each tenant may not utilize LBaaS API -resources exceeding these limits and will receive and over limit error -if attempted (413). - -+-----------------------------+------------------------------------------------------------+ -| Returned Limit Name | Value | -+=============================+============================================================+ -| maxLoadBalancers | Maximum number of load balancers allowed for this tenant | -+-----------------------------+------------------------------------------------------------+ -| maxNodesPerLoadBalancer | Maximum number of nodes allowed for each load balancer | -+-----------------------------+------------------------------------------------------------+ -| maxLoadBalancerNameLength | Maximum length allowed for a load balancer name | -+-----------------------------+------------------------------------------------------------+ -| maxVIPsPerLoadBalancer | Maximum number of Virtual IPs for each load balancer | -+-----------------------------+------------------------------------------------------------+ - -8.3 Request Data -~~~~~~~~~~~~~~~~ - -None required. - -8.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -8.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -8.6 Request Body -~~~~~~~~~~~~~~~~ - -None required. - -8.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 200 | OK | -+--------------------+---------------+ - -8.8 Response Body -~~~~~~~~~~~~~~~~~ - -The response body contains information regarding limits imposed for the -tenant making the request. - -8.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+----------------+ -| HTTP Status Code | Description | -+====================+================+ -| 400 | Bad Request | -+--------------------+----------------+ -| 401 | Unauthorized | -+--------------------+----------------+ -| 404 | Not Found | -+--------------------+----------------+ -| 405 | Not Allowed | -+--------------------+----------------+ -| 500 | LBaaS Fault | -+--------------------+----------------+ - -8.10 Example -~~~~~~~~~~~~ - -**Curl Request** - -:: - - curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/limits - -**Response** - -:: - - { - "limits": { - "absolute": { - "values": { - "maxLoadBalancerNameLength": 128, - "maxLoadBalancers": 20, - "maxNodesPerLoadBalancer": 5, - "maxVIPsPerLoadBalancer": 1 - } - } - } - } - -.. _api-protocols: - -9. Get List Of Supported LBaaS Protocols ----------------------------------------- - -9.1 Operation -~~~~~~~~~~~~~ - -+-------------+-----------------------------------+----------+-----------------------------+ -| Resource | Operation | Method | Path | -+=============+===================================+==========+=============================+ -| Protocols | Get list of supported protocols | GET | {baseURI}/{ver}/protocols | -+-------------+-----------------------------------+----------+-----------------------------+ - -9.2 Description -~~~~~~~~~~~~~~~ - -All load balancers must be configured with the protocol of the service -which is being load balanced. The protocol selection should be based on -the protocol of the back-end nodes. The current specification supports -HTTP, HTTPS and TCP services. - -When configuring an HTTP or HTTPS load balancer, the default port for -the given protocol will be selected unless otherwise specified. For TCP -load balancers, the port attribute must be provided. - -9.3 Request Data -~~~~~~~~~~~~~~~~ - -None required. - -9.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -9.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -9.6 Request Body -~~~~~~~~~~~~~~~~ - -None required. - -9.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 200 | OK | -+--------------------+---------------+ - -9.8 Response Body -~~~~~~~~~~~~~~~~~ - -The response body contains the currently supported protocols and port -numbers. - -9.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+----------------+ -| HTTP Status Code | Description | -+====================+================+ -| 400 | Bad Request | -+--------------------+----------------+ -| 401 | Unauthorized | -+--------------------+----------------+ -| 404 | Not Found | -+--------------------+----------------+ -| 405 | Not Allowed | -+--------------------+----------------+ -| 500 | LBaaS Fault | -+--------------------+----------------+ - -9.10 Example -~~~~~~~~~~~~ - -**Curl Request** - -:: - - curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/protocols - -**Response** - -:: - - { - "protocols": [ - { - "name": "HTTP", - "port": 80 - }, - { - "name": "TCP", - "port": 443 - } - ] - } - -.. _api-algorithms: - -10. Get List Of Supported LBaaS Algorithms ------------------------------------------- - -10.1 Operation -~~~~~~~~~~~~~~ - -+--------------+------------------------------------+----------+------------------------------+ -| Resource | Operation | Method | Path | -+==============+====================================+==========+==============================+ -| Algorithms | Get list of supported algorithms | GET | {baseURI}/{ver}/algorithms | -+--------------+------------------------------------+----------+------------------------------+ - -10.2 Description -~~~~~~~~~~~~~~~~ - -All load balancers utilize an algorithm that defines how traffic should -be directed between back end nodes. The default algorithm for newly -created load balancers is ROUND\_ROBIN, which can be overridden at -creation time or changed after the load balancer has been initially -provisioned. - -The algorithm name is to be constant within a major revision of the load -balancing API, though new algorithms may be created with a unique -algorithm name within a given major revision of this API. - -**Supported Algorithms** - -+----------------------+-------------------------------------------------------------------------+ -| Name | Description | -+======================+=========================================================================+ -| LEAST\_CONNECTIONS | The node with the lowest number of connections will receive requests. | -+----------------------+-------------------------------------------------------------------------+ -| ROUND\_ROBIN | Connections are routed to each of the back-end servers in turn. | -+----------------------+-------------------------------------------------------------------------+ - -10.3 Request Data -~~~~~~~~~~~~~~~~~ - -None required. - -10.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -10.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -10.6 Request Body -~~~~~~~~~~~~~~~~~ - -None required. - -10.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 200 | OK | -+--------------------+---------------+ - -10.8 Response Body -~~~~~~~~~~~~~~~~~~ - -The response body contains the currently supported algorithms. - -10.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+----------------+ -| HTTP Status Code | Description | -+====================+================+ -| 400 | Bad Request | -+--------------------+----------------+ -| 401 | Unauthorized | -+--------------------+----------------+ -| 404 | Not Found | -+--------------------+----------------+ -| 405 | Not Allowed | -+--------------------+----------------+ -| 500 | LBaaS Fault | -+--------------------+----------------+ - -10.10 Example -~~~~~~~~~~~~~ - -**Curl Request** - -:: - - curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/algorithms - -**Response** - -:: - - { - "algorithms": [ - { - "name": "ROUND_ROBIN" - }, - { - "name": "LEAST_CONNECTIONS" - } - ] - } - -.. _api-list: - -11. Get List Of All Load Balancers ----------------------------------- - -11.1 Operation -~~~~~~~~~~~~~~ - -+-----------------+----------------------------------+----------+---------------------------------+ -| Resource | Operation | Method | Path | -+=================+==================================+==========+=================================+ -| Load Balancer | Get list of all load balancers | GET | {baseURI}/{ver}/loadbalancers | -+-----------------+----------------------------------+----------+---------------------------------+ - -11.2 Description -~~~~~~~~~~~~~~~~ - -This operation provides a list of all load balancers configured and -associated with your account. This includes a summary of attributes for -each load balancer. In order to retrieve all the details for a load -balancer, an individual request for the load balancer must be made. - -This operation returns the following attributes for each load balancer: - -**id :** Unique identifier for the load balancer - -**name :** Creator-assigned name for the load balancer - -**algorithm :** Creator-specified algorithm for the load balancer - -**protocol :** Creator-specified protocol for the load balancer - -**port :** Creator-specified port for the load balancer - -**status :** Current status, see section on load balancer status within -load balancer create - -**created :** When the load balancer was created - -**updated :** When the load balancer was last updated - -11.3 Request Data -~~~~~~~~~~~~~~~~~ - -None required. - -11.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -11.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -11.6 Request Body -~~~~~~~~~~~~~~~~~ - -None required. - -11.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 200 | OK | -+--------------------+---------------+ - -11.8 Response Body -~~~~~~~~~~~~~~~~~~ - -The response body contains a list of load balancers for the tenant -making the request. - -11.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+----------------+ -| HTTP Status Code | Description | -+====================+================+ -| 400 | Bad Request | -+--------------------+----------------+ -| 401 | Unauthorized | -+--------------------+----------------+ -| 404 | Not Found | -+--------------------+----------------+ -| 405 | Not Allowed | -+--------------------+----------------+ -| 500 | LBaaS Fault | -+--------------------+----------------+ - -11.10 Example -~~~~~~~~~~~~~ - -**Curl Request** - -:: - - curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers - -**Response** - -:: - - { - "loadBalancers":[ - { - "name":"lb-site1", - "id":"71", - "protocol":"HTTP", - "port":"80", - "algorithm":"LEAST_CONNECTIONS", - "status":"ACTIVE", - "created":"2010-11-30T03:23:42Z", - "updated":"2010-11-30T03:23:44Z" - }, - { - "name":"lb-site2", - "id":"166", - "protocol":"TCP", - "port":"9123", - "algorithm":"ROUND_ROBIN", - "status":"ACTIVE", - "created":"2010-11-30T03:23:42Z", - "updated":"2010-11-30T03:23:44Z" - } - ] - } - -.. _api-status: - -12. Get Load Balancer Details ------------------------------ - -12.1 Operation -~~~~~~~~~~~~~~ - -+-----------------+--------------------------------+----------+--------------------------------------------------+ -| Resource | Operation | Method | Path | -+=================+================================+==========+==================================================+ -| Load Balancer | Get a specific load balancer | GET | {baseURI}/{ver}/loadbalancers/{loadbalancerId} | -+-----------------+--------------------------------+----------+--------------------------------------------------+ - -12.2 Description -~~~~~~~~~~~~~~~~ - -This operation provides detailed description for a specific load -balancer configured and associated with your account. This operation is -not capable of returning details for a load balancer which has been -deleted. Details include load balancer virtual IP and node information. - -12.3 Request Data -~~~~~~~~~~~~~~~~~ - -None required. - -12.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -12.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -12.6 Request Body -~~~~~~~~~~~~~~~~~ - -None required. - -12.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 200 | OK | -+--------------------+---------------+ - -12.8 Response Body -~~~~~~~~~~~~~~~~~~ - -The response body contains the load balancer requested or 404, if not -found. - -12.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+----------------+ -| HTTP Status Code | Description | -+====================+================+ -| 400 | Bad Request | -+--------------------+----------------+ -| 401 | Unauthorized | -+--------------------+----------------+ -| 404 | Not Found | -+--------------------+----------------+ -| 405 | Not Allowed | -+--------------------+----------------+ -| 500 | LBaaS Fault | -+--------------------+----------------+ - -12.10 Example -~~~~~~~~~~~~~ - -**Curl Request** - -:: - - curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/2000 - -**Response** - -:: - - { - "id": "2000", - "name":"sample-loadbalancer", - "protocol":"HTTP", - "port": "80", - "algorithm":"ROUND_ROBIN", - "status":"ACTIVE", - "created":"2010-11-30T03:23:42Z", - "updated":"2010-11-30T03:23:44Z", - "virtualIps":[ - { - "id": "1000", - "address":"192.168.1.1", - "type":"PUBLIC", - "ipVersion":"IPV4" - } - ], - "nodes": [ - { - "id": "1041", - "address":"10.1.1.1", - "port": "80", - "condition":"ENABLED", - "status":"ONLINE" - }, - { - "id": "1411", - "address":"10.1.1.2", - "port": "80", - "condition":"ENABLED", - "status":"ONLINE" - } - ], - } - -.. _api-create: - -13. Create a New Load Balancer ------------------------------- - -13.1 Operation -~~~~~~~~~~~~~~ - -+-----------------+------------------------------+----------+---------------------------------+ -| Resource | Operation | Method | Path | -+=================+==============================+==========+=================================+ -| Load Balancer | Create a new load balancer | POST | {baseURI}/{ver}/loadbalancers | -+-----------------+------------------------------+----------+---------------------------------+ - -13.2 Description -~~~~~~~~~~~~~~~~ - -This operation provisions a new load balancer based on the configuration -defined in the request object. Once the request is validated and -progress has started on the provisioning process, a response object will -be returned. The object will contain a unique identifier and status of -the request. - -If the status returned is set to 'BUILD', then using the identifier of -the load balancer, the caller can check on the progress of the creation -operation by performing a GET on loadbalancers/{loadbalancerId}. When -the status of the load balancer returned changes to 'ACTIVE', then the -load balancer has been successfully provisioned and is now operational. - -**Load Balancer Status Values** - -+-------------------+----------------------------------------------------------------+ -| Status Name | Description | -+===================+================================================================+ -| BUILD | Load balancer is in a building state and not yet operational | -+-------------------+----------------------------------------------------------------+ -| ACTIVE | Load balancer is in an operational state | -+-------------------+----------------------------------------------------------------+ -| PENDING\_UPDATE | Load balancer is in the process of an update | -+-------------------+----------------------------------------------------------------+ -| ERROR | Load balancer is in an error state and not operational | -+-------------------+----------------------------------------------------------------+ - -The caller of this operation must specify at least the following -attributes of the load balancer: - -\*name - -\*At least one node - -If the request cannot be fulfilled due to insufficient or invalid data, -an HTTP 400 (Bad Request) error response will be returned with -information regarding the nature of the failure in the body of the -response. Failures in the validation process are non-recoverable and -require the caller to correct the cause of the failure and POST the -request again. - -By default, the system will create a loadbalancer with protocol set to -HTTP, port set to 80 (or 443 if protocol is HTTPS), and assign a public -IPV4 address to the loadbalancer. The default algorithm used is set to -ROUND\_ROBIN. - -A load balancer name has a max length that can be determined by querying -limits. - -Users may configure all documented features of the load balancer at -creation time by simply providing the additional elements or attributes -in the request. This document provides an overview of all the features -the load balancing service supports. - -If you have at least one load balancer, you may create subsequent load -balancers that share a single virtual IP by issuing a POST and supplying -a virtual IP ID instead of a type. Additionally, this feature is highly -desirable if you wish to load balance both an unsecured and secure -protocol using one IP address. For example, this method makes it -possible to use the same load balancing configuration to support an HTTP -and an HTTPS load balancer. Load balancers sharing a virtual IP must -utilize a unique port. - -13.3 Request Data -~~~~~~~~~~~~~~~~~ - -The caller is required to provide a request data with the POST which -includes the appropriate information to create a new load balancer. - -13.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -13.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- **X-Auth-Token** -- **Accept: application/json** -- **Content-Type: application/json** - -13.6 Request Body -~~~~~~~~~~~~~~~~~ - -The request body must follow the correct format for new load balancer -creation, examples.... - -**Request body example to create a load balancer with two nodes** - -:: - - { - "name": "a-new-loadbalancer", - "nodes": [ - { - "address": "10.1.1.1", - "port": "80" - }, - { - "address": "10.1.1.2", - "port": "81" - } - ] - } - -**Request body example to create a load balancer using existing load -balancer virtual IP** - -:: - - { - "name":"a-new-loadbalancer", - "port":"83", - "protocol":"HTTP", - "virtualIps": [ - { - "id":"39" - } - ], - "nodes": [ - { - "address":"10.1.1.1", - "port":"80", - "condition":"ENABLED" - } - ] - } - -13.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 202 | Accepted | -+--------------------+---------------+ - -13.8 Response Body -~~~~~~~~~~~~~~~~~~ - -The response body contains the load balancer requested or appropriate -error. - -**Create Load Balancer (Required Attributes with Shared IP) Response: -JSON** - -:: - - { - "name": "a-new-loadbalancer", - "id": "144", - "protocol": "HTTP", - "port": "83", - "algorithm": "ROUND_ROBIN", - "status": "BUILD", - "created": "2011-04-13T14:18:07Z", - "updated":"2011-04-13T14:18:07Z", - "virtualIps": [ - { - "address": "3ffe:1900:4545:3:200:f8ff:fe21:67cf", - "id": "39", - "type": "PUBLIC", - "ipVersion": "IPV6" - } - ], - "nodes": [ - { - "address": "10.1.1.1", - "id": "653", - "port": "80", - "status": "ONLINE", - "condition": "ENABLED" - } - ] - } - -13.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+-----------------------+ -| HTTP Status Code | Description | -+====================+=======================+ -| 400 | Bad Request | -+--------------------+-----------------------+ -| 401 | Unauthorized | -+--------------------+-----------------------+ -| 404 | Not Found | -+--------------------+-----------------------+ -| 405 | Not Allowed | -+--------------------+-----------------------+ -| 413 | Over Limit | -+--------------------+-----------------------+ -| 500 | LBaaS Fault | -+--------------------+-----------------------+ -| 503 | Service Unavailable | -+--------------------+-----------------------+ - -13.10 Example -~~~~~~~~~~~~~ - -**Contents of Request file lb.json** - -:: - - { - "name": "lb #1", - "protocol":"tcp", - "nodes": [ - { - "address": "15.185.229.153", - "port": "443" - }, - { - "address": "15.185.226.163", - "port": "443" - }, - ], - } - -**Curl Request** - -:: - - curl -X POST -H "X-Auth-Token: TOKEN" --data-binary "@lb.json" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers - -**Response** - -:: - - { - "port":"443", - "id":"10", - "protocol":"tcp", - "updated":"2013-02-10T18:20Z", - "created":"2013-02-10T18:20Z", - "status":"BUILD", - "nodes":[ - { - "port":"443", - "id":"19", - "condition":"ENABLED", - "status":"ONLINE", - "address":"15.185.229.153" - }, - { - "port":"443", - "id":"20", - "condition":"ENABLED", - "status":"ONLINE", - "address":"15.185.226.163" - } - ], - "name":"lb #1", - "virtualIps":[ - { - "id":"5", - "address":"15.185.96.125", - "ipVersion":"IPV_4", - "type":"PUBLIC" - } - ], - "algorithm":"ROUND_ROBIN" - } - -.. _api-modify: - -14. Update An Existing Load Balancer ------------------------------------- - -14.1 Operation -~~~~~~~~~~~~~~ - -+-----------------+-----------------------------------+----------+--------------------------------------------------+ -| Resource | Operation | Method | Path | -+=================+===================================+==========+==================================================+ -| Load Balancer | Update load balancer attributes | PUT | {baseURI}/{ver}/loadbalancers/{loadbalancerId} | -+-----------------+-----------------------------------+----------+--------------------------------------------------+ - -14.2 Description -~~~~~~~~~~~~~~~~ - -This operation updates the attributes of the specified load balancer. -Upon successful validation of the request, the service will return a 202 -(Accepted) response code. A caller should check that the load balancer -status is ACTIVE to confirm that the update has taken effect. If the -load balancer status is 'PENDING\_UPDATE' then the caller can poll the -load balancer with its ID (using a GET operation) to wait for the -changes to be applied and the load balancer to return to an ACTIVE -status. - -This operation allows the caller to change one or more of the following -attributes: - -\*name - -\*algorithm - -This operation does not return a response body. - -Note: The load balancer ID, status, port and protocol are immutable -attributes and cannot be modified by the caller. Supplying an -unsupported attribute will result in a 400 (badRequest) fault. - -14.3 Request Data -~~~~~~~~~~~~~~~~~ - -Load balancer body with attributes to be updated. - -14.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -14.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -14.6 Request Body -~~~~~~~~~~~~~~~~~ - -**Example** - -:: - - { - "name": "newname-loadbalancer", - "algorithm": "LEAST_CONNECTIONS" - } - -14.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 202 | Accepted | -+--------------------+---------------+ - -14.8 Response Body -~~~~~~~~~~~~~~~~~~ - -None. - -14.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+----------------+ -| HTTP Status Code | Description | -+====================+================+ -| 400 | Bad Request | -+--------------------+----------------+ -| 401 | Unauthorized | -+--------------------+----------------+ -| 404 | Not Found | -+--------------------+----------------+ -| 405 | Not Allowed | -+--------------------+----------------+ -| 500 | LBaaS Fault | -+--------------------+----------------+ - -14.10 Example -~~~~~~~~~~~~~ - -**Contents of Request file lb.json** - -:: - - { - "name": "newname-loadbalancer", - "algorithm": "LEAST_CONNECTIONS" - } - -**Curl Request** - -:: - - curl -X PUT -H "X-Auth-Token: TOKEN" --data-binary "@lb.json" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalance/100 - -**Response** - -202 status with no response body. - -.. _api-delete: - -15. Delete Load Balancer ------------------------- - -15.1 Operation -~~~~~~~~~~~~~~ - -+-----------------+------------------------------------+----------+--------------------------------------------------+ -| Resource | Operation | Method | Path | -+=================+====================================+==========+==================================================+ -| Load Balancer | Delete an existing load balancer | DELETE | {baseURI}/{ver}/loadbalancers/{loadbalancerId} | -+-----------------+------------------------------------+----------+--------------------------------------------------+ - -15.2 Description -~~~~~~~~~~~~~~~~ - -Delete load balancer removes the specified load balancer and its -associated configuration from the account. Any and all configuration -data is immediately purged and is not recoverable. - -This operation does not require a request body. - -15.3 Request Data -~~~~~~~~~~~~~~~~~ - -None required. - -15.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -15.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -15.6 Request Body -~~~~~~~~~~~~~~~~~ - -None required. - -15.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 202 | Accepted | -+--------------------+---------------+ - -15.8 Response Body -~~~~~~~~~~~~~~~~~~ - -None. - -15.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+----------------+ -| HTTP Status Code | Description | -+====================+================+ -| 400 | Bad Request | -+--------------------+----------------+ -| 401 | Unauthorized | -+--------------------+----------------+ -| 404 | Not Found | -+--------------------+----------------+ -| 405 | Not Allowed | -+--------------------+----------------+ -| 500 | LBaaS Fault | -+--------------------+----------------+ - -15.10 Example -~~~~~~~~~~~~~ - -**Curl Example** - -:: - - curl -X DELETE -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalance/100 - -**Response** - -202 status with no response body. - -.. _api-node-list: - -16. List All Load Balancer Nodes --------------------------------- - -16.1 Operation -~~~~~~~~~~~~~~ - -+------------+-----------------------------------+----------+--------------------------------------------------------+ -| Resource | Operation | Method | Path | -+============+===================================+==========+========================================================+ -| Node | Get list of load balancer nodes | GET | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/nodes | -+------------+-----------------------------------+----------+--------------------------------------------------------+ - -16.2 Description -~~~~~~~~~~~~~~~~ - -List all nodes for a specified load balancer. - -16.3 Request Data -~~~~~~~~~~~~~~~~~ - -None required. - -16.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -16.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -16.6 Request Body -~~~~~~~~~~~~~~~~~ - -None required. - -16.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 200 | OK | -+--------------------+---------------+ - -16.8 Response Body -~~~~~~~~~~~~~~~~~~ - -The response body contains the load balancer nodes requested or 404, if -not found. - -16.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+----------------+ -| HTTP Status Code | Description | -+====================+================+ -| 400 | Bad Request | -+--------------------+----------------+ -| 401 | Unauthorized | -+--------------------+----------------+ -| 404 | Not Found | -+--------------------+----------------+ -| 405 | Not Allowed | -+--------------------+----------------+ -| 500 | LBaaS Fault | -+--------------------+----------------+ - -16.10 Example -~~~~~~~~~~~~~ - -**Curl Example** - -:: - - curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalance/100/nodes - -**Response** - -:: - - { - "nodes" : [ - { - "id":"410", - "address":"10.1.1.1", - "port":"80", - "condition":"ENABLED", - "status":"ONLINE" - }, - { - "id":"236", - "address":"10.1.1.2", - "port":"80", - "condition":"ENABLED", - "status":"ONLINE" - }, - { - "id":"2815", - "address":"10.1.1.3", - "port":"83", - "condition":"DISABLED", - "status":"OFFLINE" - }, - ] - } - -.. _api-node-status: - -17. Get Load Balancer Node --------------------------- - -17.1 Operation -~~~~~~~~~~~~~~ - -+------------+-------------------------------------+----------+-----------------------------------------------------------------+ -| Resource | Operation | Method | Path | -+============+=====================================+==========+=================================================================+ -| Node | Get a specific load balancer node | GET | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/nodes/{nodeId} | -+------------+-------------------------------------+----------+-----------------------------------------------------------------+ - -17.2 Description -~~~~~~~~~~~~~~~~ - -This operation retrieves the configuration of a node. - -17.3 Request Data -~~~~~~~~~~~~~~~~~ - -None required. - -17.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -17.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -17.6 Request Body -~~~~~~~~~~~~~~~~~ - -None required. - -17.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 200 | OK | -+--------------------+---------------+ - -17.8 Response Body -~~~~~~~~~~~~~~~~~~ - -The response body contains the load balancer node requested or 404, if -not found. - -17.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+----------------+ -| HTTP Status Code | Description | -+====================+================+ -| 400 | Bad Request | -+--------------------+----------------+ -| 401 | Unauthorized | -+--------------------+----------------+ -| 404 | Not Found | -+--------------------+----------------+ -| 405 | Not Allowed | -+--------------------+----------------+ -| 500 | LBaaS Fault | -+--------------------+----------------+ - -17.10 Example -~~~~~~~~~~~~~ - -**Curl Example** - -:: - - curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalance/100/nodes/410 - -**Response** - -:: - - { - "id":"410", - "address":"10.1.1.2", - "port":"80", - "condition":"ENABLED", - "status":"ONLINE" - } - -.. _api-node-create: - -18. Create Load Balancer Node ------------------------------ - -18.1 Operation -~~~~~~~~~~~~~~ - -+------------+-----------------------------------+----------+--------------------------------------------------------+ -| Resource | Operation | Method | Path | -+============+===================================+==========+========================================================+ -| Node | Create a new load balancer node | POST | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/nodes | -+------------+-----------------------------------+----------+--------------------------------------------------------+ - -18.2 Description -~~~~~~~~~~~~~~~~ - -Add a new node to any existing loadbalancer. When a node is added, it is -assigned a unique identifier that can be used for mutating operations -such as changing the condition, or removing the node from the load -balancer. When a node is added to a load balancer, it is enabled by -default. - -18.3 Request Data -~~~~~~~~~~~~~~~~~ - -The request must contain information regarding the new node to be added. -More than one node can be added at a time. - -18.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -18.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -18.6 Request Body -~~~~~~~~~~~~~~~~~ - -The request body defines the attributes of the new node to be created. - -18.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 202 | Accepted | -+--------------------+---------------+ - -18.8 Response Body -~~~~~~~~~~~~~~~~~~ - -The response body contains the load balancer requested or 404, if not -found. - -18.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+----------------+ -| HTTP Status Code | Description | -+====================+================+ -| 400 | Bad Request | -+--------------------+----------------+ -| 401 | Unauthorized | -+--------------------+----------------+ -| 404 | Not Found | -+--------------------+----------------+ -| 405 | Not Allowed | -+--------------------+----------------+ -| 413 | Over Limit | -+--------------------+----------------+ -| 500 | LBaaS Fault | -+--------------------+----------------+ - -18.10 Example -~~~~~~~~~~~~~ - -**Contents of Request file nodes.json** - -:: - - { - "nodes": [ - { - "address": "10.1.1.1", - "port": "80" - }, - { - "address": "10.2.2.1", - "port": "80" - }, - { - "address": "10.2.2.2", - "port": "88", - "condition": "DISABLED" - } - ] - } - -**Curl Request** - -:: - - curl -X POST -H "X-Auth-Token: TOKEN" --data-binary "@nodes.json" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100/nodes - -**Response** - -:: - - { - "nodes": [ - { - "id": "7298", - "address": "10.1.1.1", - "port": "80", - "condition": "ENABLED", - "status": "ONLINE" - }, - { - "id": "293", - "address": "10.2.2.1", - "port": "80", - "condition": "ENABLED", - "status": "OFFLINE" - }, - { - "id": "183", - "address": "10.2.2.2", - "port": "88", - "condition": "DISABLED", - "status": "OFFLINE" - } - ] - } - -.. _api-node-modify: - -19. Update Load Balancer Node Condition ---------------------------------------- - -19.1 Operation -~~~~~~~~~~~~~~ - -+------------+-------------------------------+----------+-----------------------------------------------------------------+ -| Resource | Operation | Method | Path | -+============+===============================+==========+=================================================================+ -| Node | Update a load balancer node | PUT | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/nodes/{nodeId} | -+------------+-------------------------------+----------+-----------------------------------------------------------------+ - -19.2 Description -~~~~~~~~~~~~~~~~ - -Every node in the load balancer is either enabled or disabled which -determines its role within the load balancer. When the node has -condition='ENABLED' the node is permitted to accept new connections. Its -status will eventually become 'ONLINE' to reflect this configuration. -When the node has condition='DISABLED' the node is not permitted to -accept any new connections. Existing connections to the node are -forcibly terminated. The nodes status changes to OFFLINE once the -configuration has been successfully applied. - -The node IP and port are immutable attributes and cannot be modified -with a PUT request. Supplying an unsupported attribute will result in a -400 fault. A load balancer supports a maximum number of nodes. The -maximum number of nodes per loadbalancer is returned when querying the -limits of the LB service. - -19.3 Request Data -~~~~~~~~~~~~~~~~~ - -Request data includes the desired condition of the node. - -19.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -19.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -19.6 Request Body -~~~~~~~~~~~~~~~~~ - -The request body includes the node 'condition' attribute and its desired -state. - -19.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 202 | Accepted | -+--------------------+---------------+ - -19.8 Response Body -~~~~~~~~~~~~~~~~~~ - -None. - -19.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+----------------+ -| HTTP Status Code | Description | -+====================+================+ -| 400 | Bad Request | -+--------------------+----------------+ -| 401 | Unauthorized | -+--------------------+----------------+ -| 404 | Not Found | -+--------------------+----------------+ -| 405 | Not Allowed | -+--------------------+----------------+ -| 500 | LBaaS Fault | -+--------------------+----------------+ - -19.10 Example -~~~~~~~~~~~~~ - -**Contents of Request file node.json** - -:: - - { - "condition": "DISABLED" - } - -**Curl Request** - -:: - - curl -X PUT -H "X-Auth-Token: TOKEN" --data-binary "@node.json" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100/nodes/100 - -**Response** - -202 status with no response body. - -.. _api-node-delete: - -20. Delete Load Balancer Node ------------------------------ - -20.1 Operation -~~~~~~~~~~~~~~ - -+------------+-------------------------------+----------+-----------------------------------------------------------------+ -| Resource | Operation | Method | Path | -+============+===============================+==========+=================================================================+ -| Node | Delete a load balancer node | DELETE | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/nodes/{nodeId} | -+------------+-------------------------------+----------+-----------------------------------------------------------------+ - -20.2 Description -~~~~~~~~~~~~~~~~ - -Delete node for a load balancer. Note: A load balancer must have at -least one node. Attempting to remove the last node of a loadbalancer -will result in a 401 error. - -20.3 Request Data -~~~~~~~~~~~~~~~~~ - -None required. - -20.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -20.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -20.6 Request Body -~~~~~~~~~~~~~~~~~ - -None required. - -20.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 202 | Accepted | -+--------------------+---------------+ - -20.8 Response Body -~~~~~~~~~~~~~~~~~~ - -None. - -20.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+----------------+ -| HTTP Status Code | Description | -+====================+================+ -| 400 | Bad Request | -+--------------------+----------------+ -| 401 | Unauthorized | -+--------------------+----------------+ -| 404 | Not Found | -+--------------------+----------------+ -| 405 | Not Allowed | -+--------------------+----------------+ -| 500 | LBaaS Fault | -+--------------------+----------------+ - -20.10 Example -~~~~~~~~~~~~~ - -**Curl Request** - -:: - - curl -X DELETE -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100/nodes/100 - -**Response** - -202 status with no response body. - -.. _api-vips: - -21. Get List of Virtual IPs ---------------------------- - -21.1 Operation -~~~~~~~~~~~~~~ - -+--------------+---------------------------+----------+-------------------------------------------------------------+ -| Resource | Operation | Method | Path | -+==============+===========================+==========+=============================================================+ -| Virtual IP | Get list of virtual IPs | GET | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/virtualips | -+--------------+---------------------------+----------+-------------------------------------------------------------+ - -21.2 Description -~~~~~~~~~~~~~~~~ - -This operation lists all the virtual IP addresses of a load balancer.The -maximum number of VIPs that can be configured when creating a load -balancer can be discovered by querying the limits of the LB service. - -21.3 Request Data -~~~~~~~~~~~~~~~~~ - -None required. - -21.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -21.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -21.6 Request Body -~~~~~~~~~~~~~~~~~ - -None required. - -21.7 Normal Response Code -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+---------------+ -| HTTP Status Code | Description | -+====================+===============+ -| 200 | OK | -+--------------------+---------------+ - -21.8 Response Body -~~~~~~~~~~~~~~~~~~ - -The response body contains the load balancer VIP list requested or 404, -if not found. - -21.9 Error Response Codes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+--------------------+----------------+ -| HTTP Status Code | Description | -+====================+================+ -| 400 | Bad Request | -+--------------------+----------------+ -| 401 | Unauthorized | -+--------------------+----------------+ -| 404 | Not Found | -+--------------------+----------------+ -| 405 | Not Allowed | -+--------------------+----------------+ -| 500 | LBaaS Fault | -+--------------------+----------------+ - -21.10 Example -~~~~~~~~~~~~~ - -**Curl Request** - -:: - - curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100/virtualips - -**Response** - -:: - - { - "virtualIps": [ - { - "id": "1021", - "address": "206.10.10.210", - "type": "PUBLIC", - "ipVersion": "IPV4" - } - ] - } - -.. _api-logs: - -22. Archive log file to Object Storage --------------------------------------- - -22.1 Operation -~~~~~~~~~~~~~~ - -+----------+------------------------------------+--------+-----------------------------------------------------+ -| Resource | Operation | Method | Path | -+==========+====================================+========+=====================================================+ -| Logs | Archive log file to Object Storage | POST | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/logs | -+----------+------------------------------------+--------+-----------------------------------------------------+ - -22.2 Description -~~~~~~~~~~~~~~~~ - -The operation tells the load balancer to push the current log file into an HP Cloud Object Storage container. The status of the load balancer will be set to 'PENDING_UPDATE' during the operation and back to 'ACTIVE' upon success or failure. A success/failure message can be found in the 'statusDescription' field when getting the load balancer details. - -**Load Balancer Status Values** - -+----------------+---------------+--------------------------------+ -| Status | Name | Description | -+================+===============+================================+ -| ACTIVE | Load balancer | is in an operational state | -| PENDING_UPDATE | Load balancer | is in the process of an update | -+----------------+---------------+--------------------------------+ - -By default with empty POST data the load balancer will upload to the swift account owned by the same tenant as the load balancer in a container called 'lbaaslogs'. To change this the following optional parameters need to be provided in the POST body: - -**objectStoreBasePath** : the object store container to use - -**objectStoreEndpoint** : the object store endpoint to use including tenantID, for example: https://region-b.geo-1.objects.hpcloudsvc.com:443/v1/1234567890123 - -**authToken** : an authentication token to the object store for the load balancer to use - -22.3 Request Data -~~~~~~~~~~~~~~~~~ - -The caller is required to provide a request data with the POST which includes the appropriate information to upload logs. - -22.4 Query Parameters Supported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -None required. - -22.5 Required HTTP Header Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**X-Auth-Token** - -22.6 Request Body -~~~~~~~~~~~~~~~~~ - -The request body must follow the correct format for new load balancer creation, examples.... - -A request that uploads the logs to a different object store - -:: - - { - "objectStoreBasePath": "mylblogs", - "objectStoreEndpoint": "https://region-b.geo-1.objects.hpcloudsvc.com:443/v1/1234567890123", - "authToken": "HPAuth_d17efd" - } - Features Currently Not Implemented or Supported @@ -2345,9 +596,23 @@ Features Currently Not Implemented or Supported The following features are not supported. -1. IPV6 address types are not supported. +* IPV6 address types are not supported. -2. HTTPS protocol for load balancers are not supported. It is not - advertised in /protocols request. Instead TCP will be used for port 443 - and the HTTPS connections will be passed through the load balancer with no - termination at the load balancer. +SSL +--- + +Supported +~~~~~~~~~ + +End-to-end HTTPS protocol support is currently provided by the TCP load balancer option. HTTPS-based traffic will flow between end-users and application server nodes via the TCP load balancer connection. + +* The same SSL certificate needs to be installed on each application server node. +* The same private key needs to be installed on each application server node. +* The SSL certificate needs to reference the load balancer fully qualified domain name (FQDN) or external IP address of the load balancer in the Subject CommonName(CN) or Subject Alternative + Name field of the certificate. The IP address of the servers behind the load balancer should not be used. + +Not supported +~~~~~~~~~~~~~ + +* SSL certificate termination on the load balancer +* HTTPS/SSL session affinity or "stickyness" \ No newline at end of file diff --git a/doc/api/rest/algorithms.rst b/doc/api/rest/algorithms.rst new file mode 100644 index 00000000..a3a95c98 --- /dev/null +++ b/doc/api/rest/algorithms.rst @@ -0,0 +1,116 @@ +.. _api-algorithms: + +========== +Algorithms +========== + + +Get List Of Supported LBaaS Algorithms +-------------------------------------- + +Operation +~~~~~~~~~ + ++--------------+------------------------------------+----------+------------------------------+ +| Resource | Operation | Method | Path | ++==============+====================================+==========+==============================+ +| Algorithms | Get list of supported algorithms | GET | {baseURI}/{ver}/algorithms | ++--------------+------------------------------------+----------+------------------------------+ + +Description +~~~~~~~~~~~ + +All load balancers utilize an algorithm that defines how traffic should +be directed between back end nodes. The default algorithm for newly +created load balancers is ROUND\_ROBIN, which can be overridden at +creation time or changed after the load balancer has been initially +provisioned. + +The algorithm name is to be constant within a major revision of the load +balancing API, though new algorithms may be created with a unique +algorithm name within a given major revision of this API. + +**Supported Algorithms** + ++----------------------+-------------------------------------------------------------------------+ +| Name | Description | ++======================+=========================================================================+ +| LEAST\_CONNECTIONS | The node with the lowest number of connections will receive requests. | ++----------------------+-------------------------------------------------------------------------+ +| ROUND\_ROBIN | Connections are routed to each of the back-end servers in turn. | ++----------------------+-------------------------------------------------------------------------+ + +Request Data +~~~~~~~~~~~~ + +None required. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +None required. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 200 | OK | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~ + +The response body contains the currently supported algorithms. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------------+ +| HTTP Status Code | Description | ++====================+================+ +| 400 | Bad Request | ++--------------------+----------------+ +| 401 | Unauthorized | ++--------------------+----------------+ +| 404 | Not Found | ++--------------------+----------------+ +| 405 | Not Allowed | ++--------------------+----------------+ +| 500 | LBaaS Fault | ++--------------------+----------------+ + +Example +~~~~~~~ + +**Curl Request** + +:: + + curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/algorithms + +**Response** + +:: + + { + "algorithms": [ + { + "name": "ROUND_ROBIN" + }, + { + "name": "LEAST_CONNECTIONS" + } + ] + } \ No newline at end of file diff --git a/doc/api/rest/health-monitor.rst b/doc/api/rest/health-monitor.rst new file mode 100644 index 00000000..a8765733 --- /dev/null +++ b/doc/api/rest/health-monitor.rst @@ -0,0 +1,360 @@ +.. _api-monitor: + +=============== +Health Monitors +=============== + + +.. _api-monitor-status: + +Get Load Balancer Health Monitor +-------------------------------- + +Operation +~~~~~~~~~ + ++--------------------+------------------------------------------+-------+--------------------------------------------------------------+ +|Resource |Operation |Method |Path | ++====================+==========================================+=======+==============================================================+ +|Health Monitor |Get a load balancer health monitor |GET |{baseURI}/{ver}/loadbalancers/{loadbalancerId}/healthmonitor | ++--------------------+------------------------------------------+-------+--------------------------------------------------------------+ + +Description +̃~~~~~~~~~~~ + +This operation retrieves the current configuration of a load balancer health monitor. + +Request Data +̃~~~~~~~~~~~~ + +None required. + +Query Parameters Supported +̃~~~~~~~~~~~̃~~~~~~~~~~~̃~~~~ + +None required. + +Required HTTP Header Values +̃~~~~~~~~~~~̃~~~~~~~~~~~̃~~~~~ + +**X-Auth-Token** + +Request Body +̃~~~~~~~~~~~̃~ + +None required. + +Normal Response Code +̃~~~~~~~~~~~̃~~~~~~~~~ + ++------------------+---------------------+ +| HTTP Status Code | Description | ++==================+=====================+ +|200 |OK | ++------------------+---------------------+ + +Response Body +̃~~~~~~~~~~~̃~~ + +The response body contains the health monitor for the requested load balancer or 404, if not found. + +Error Response Codes +̃~~~~~~~~~~~̃~~~~~~~~~ + ++------------------+---------------------+ +| HTTP Status Code | Description | ++==================+=====================+ +|400 |Bad Request | ++------------------+---------------------+ +|401 |Unauthorized | ++------------------+---------------------+ +|404 |Not Found | ++------------------+---------------------+ +|405 |Not Allowed | ++------------------+---------------------+ +|500 |LBaaS Fault | ++------------------+---------------------+ + +Example +̃~~~~~~~ + +**Curl Example** + +:: + + curl -H "Content-Type: application/json" -H "Accept: application/json" -H "X-Auth-Token:HPAuth_d17efd" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100/healthmonitor + +**Response** + +:: + + { + "type": "CONNECT", + "delay": "30", + "timeout": "30", + "attemptsBeforeDeactivation": "2" + } + +or.. + +:: + + { + "type": "HTTP", + "delay": "30", + "timeout": "30", + "attemptsBeforeDeactivation": "2", + "path": "/healthcheck" + } + + +.. _api-monitor-modify: + +Update Load Balancer Health Monitor +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Operation +~~~~~~~~~ + ++--------------------+------------------------------------------+-------+--------------------------------------------------------------+ +|Resource |Operation |Method |Path | ++====================+==========================================+=======+==============================================================+ +|Health Monitor |Update a load balancer health monitor |PUT |{baseURI}/{ver}/loadbalancers/{loadbalancerId}/healthmonitor | ++--------------------+------------------------------------------+-------+--------------------------------------------------------------+ + +Description +~~~~~~~~~~~ + +Active health monitoring provides two types of health monitors, CONNECT or HTTP. The caller can configure one health monitor per load balancer. + +The health monitor has a type attribute to signify which types it is. The required atrributes for each type is as follows: + +**CONNECT Monitor** + +The monitor connects to each node on its defined port to ensure that the node is listening properly. + +The CONNECT monitor is the most basic type of health check and does not perform post-processing or protocol specific health checks. It includes several configurable properties: + +- delay: This is the minimum time in seconds between regular calls to a monitor. The default is 30 seconds. +- timeout: Maximum number of seconds for a monitor to wait for a connection to be established to the node before it times out. The value cannot be greater than the delay value. The default is 30 seconds. +- attemptsBeforeDeactivation: Number of permissible monitor failures before removing a node from rotation. Must be a number between 1 and 10. The default is 2 attempts. + +**HTTP Monitor** + +The HTTP monitor is more intelligent than the CONNECT monitor. It is capable of processing an HTTP response to determine the condition of a node. It supports the same basic properties as the CONNECT monitor and includes the additional attribute of path that is used to evaluate the HTTP response to a monitor probe. + +- path: The HTTP path used in the HTTP request by the monitor. This must be a string beginning with a / (forward slash). The monitor expects a response from the node with an HTTP status code of 200. + +The default Health Monitor Configuration, when a load balancer is created is: + +:: + + { + "type": "CONNECT", + "delay": "30", + "timeout": "30", + "attemptsBeforeDeactivation": "2" + } + +Request Data +~~~~~~~~~~~~ + +Request data includes the desired configuration attributes of the health monitor. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +The request body includes the health monitor attributes. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++------------------+---------------------+ +| HTTP Status Code | Description | ++==================+=====================+ +|202 |Accepted | ++------------------+---------------------+ + +Response Body +~~~~~~~~~~~~~ + +The response body contains the health monitor requested + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++------------------+---------------------+ +| HTTP Status Code | Description | ++==================+=====================+ +|400 |Bad Request | ++------------------+---------------------+ +|401 |Unauthorized | ++------------------+---------------------+ +|404 |Not Found | ++------------------+---------------------+ +|405 |Not Allowed | ++------------------+---------------------+ +|500 |LBaaS Fault | ++------------------+---------------------+ + +Example +~~~~~~~ + +**Contents of Request file node.json** + +**Request** + +:: + + { + "type": "CONNECT", + "delay": "30", + "timeout": "30", + "attemptsBeforeDeactivation": "2" + } + +or.. + +:: + + { + "type": "HTTP", + "delay": "30", + "timeout": "30", + "attemptsBeforeDeactivation": "2", + "path": "/healthcheck" + } + +**Curl Request** + + curl -X PUT -H "X-Auth-Token:HPAuth_d17efd" --data-binary "@node.json" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100/healthmonitor + +**Response** + +Status with the following response body. + +:: + + { + "type": "CONNECT", + "delay": "30", + "timeout": "30", + "attemptsBeforeDeactivation": "2" + } + +or.. + +:: + + { + "type": "HTTP", + "delay": "30", + "timeout": "30", + "attemptsBeforeDeactivation": "2", + "path": "/healthcheck" + } + + +.. _api-monitor-delete: + +Reset Load Balancer Health Monitor +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Operation +~~~~~~~~~ ++--------------------+------------------------------------------+-------+--------------------------------------------------------------+ +|Resource |Operation |Method |Path | ++====================+==========================================+=======+==============================================================+ +|Health Monitor |Reset a load balancer health monitor |DELETE |{baseURI}/{ver}/loadbalancers/{loadbalancerId}/healthmonitor | ++--------------------+------------------------------------------+-------+--------------------------------------------------------------+ + +Description +~~~~~~~~~~~ + +Reset health monitor settings for a load balancer back to the following default configuration. + +:: + + { + "type": "CONNECT", + "delay": "30", + "timeout": "30", + "attemptsBeforeDeactivation": "2" + } + +Request Data +~~~~~~~~~~~~ + +None required. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +None required. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++------------------+---------------------+ +| HTTP Status Code | Description | ++==================+=====================+ +|202 |Accepted | ++------------------+---------------------+ + +Response Body +~~~~~~~~~~~~~ + +None. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++------------------+---------------------+ +| HTTP Status Code | Description | ++==================+=====================+ +|400 |Bad Request | ++------------------+---------------------+ +|401 |Unauthorized | ++------------------+---------------------+ +|404 |Not Found | ++------------------+---------------------+ +|405 |Not Allowed | ++------------------+---------------------+ +|500 |LBaaS Fault | ++------------------+---------------------+ + + +Example +~~~~~~~ + + +**Curl Request** + +:: + + curl -X DELETE -H "X-Auth-Token:HPAuth_d17efd" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100/healthmonitor + + +**Response** + +202 status with no response body. diff --git a/doc/api/rest/limits.rst b/doc/api/rest/limits.rst new file mode 100644 index 00000000..c4714996 --- /dev/null +++ b/doc/api/rest/limits.rst @@ -0,0 +1,117 @@ +.. _api-limits: + +====== +Limits +====== + + +Get List of LBaaS API Limits +---------------------------- + +Operation +~~~~~~~~~~ + ++------------+----------------------------+----------+--------------------------+ +| Resource | Operation | Method | Path | ++============+============================+==========+==========================+ +| Limits | Get list of LBaaS limits | GET | {baseURI}/{ver}/limits | ++------------+----------------------------+----------+--------------------------+ + +Description +~~~~~~~~~~~ + +This method allows querying the LBaaS service for a list of API limits +which apply on a tenant basis. Each tenant may not utilize LBaaS API +resources exceeding these limits and will receive and over limit error +if attempted (413). + ++-----------------------------+------------------------------------------------------------+ +| Returned Limit Name | Value | ++=============================+============================================================+ +| maxLoadBalancers | Maximum number of load balancers allowed for this tenant | ++-----------------------------+------------------------------------------------------------+ +| maxNodesPerLoadBalancer | Maximum number of nodes allowed for each load balancer | ++-----------------------------+------------------------------------------------------------+ +| maxLoadBalancerNameLength | Maximum length allowed for a load balancer name | ++-----------------------------+------------------------------------------------------------+ +| maxVIPsPerLoadBalancer | Maximum number of Virtual IPs for each load balancer | ++-----------------------------+------------------------------------------------------------+ + +Request Data +~~~~~~~~~~~~ + +None required. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +None required. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 200 | OK | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~ + +The response body contains information regarding limits imposed for the +tenant making the request. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------------+ +| HTTP Status Code | Description | ++====================+================+ +| 400 | Bad Request | ++--------------------+----------------+ +| 401 | Unauthorized | ++--------------------+----------------+ +| 404 | Not Found | ++--------------------+----------------+ +| 405 | Not Allowed | ++--------------------+----------------+ +| 500 | LBaaS Fault | ++--------------------+----------------+ + +Example +~~~~~~~ + +**Curl Request** + +:: + + curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/limits + +**Response** + +:: + + { + "limits": { + "absolute": { + "values": { + "maxLoadBalancerNameLength": 128, + "maxLoadBalancers": 20, + "maxNodesPerLoadBalancer": 5, + "maxVIPsPerLoadBalancer": 1 + } + } + } + } + diff --git a/doc/api/rest/load-balancer.rst b/doc/api/rest/load-balancer.rst new file mode 100644 index 00000000..9e148e02 --- /dev/null +++ b/doc/api/rest/load-balancer.rst @@ -0,0 +1,746 @@ +.. api-lb: + +============= +Load Balancer +============= + + +.. _api-lb-list: + +Get List Of All Load Balancers +------------------------------ + +Operation +~~~~~~~~~ + ++-----------------+----------------------------------+----------+---------------------------------+ +| Resource | Operation | Method | Path | ++=================+==================================+==========+=================================+ +| Load Balancer | Get list of all load balancers | GET | {baseURI}/{ver}/loadbalancers | ++-----------------+----------------------------------+----------+---------------------------------+ + +Description +~~~~~~~~~~~ + +This operation provides a list of all load balancers configured and +associated with your account. This includes a summary of attributes for +each load balancer. In order to retrieve all the details for a load +balancer, an individual request for the load balancer must be made. + +This operation returns the following attributes for each load balancer: + +**id :** Unique identifier for the load balancer + +**name :** Creator-assigned name for the load balancer + +**algorithm :** Creator-specified algorithm for the load balancer + +**protocol :** Creator-specified protocol for the load balancer + +**port :** Creator-specified port for the load balancer + +**status :** Current status, see section on load balancer status within +load balancer create + +**created :** When the load balancer was created + +**updated :** When the load balancer was last updated + +Request Data +~~~~~~~~~~~~ + +None required. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~~~~~~ + +None required. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 200 | OK | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~~~~~~ + +The response body contains a list of load balancers for the tenant +making the request. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------------+ +| HTTP Status Code | Description | ++====================+================+ +| 400 | Bad Request | ++--------------------+----------------+ +| 401 | Unauthorized | ++--------------------+----------------+ +| 404 | Not Found | ++--------------------+----------------+ +| 405 | Not Allowed | ++--------------------+----------------+ +| 500 | LBaaS Fault | ++--------------------+----------------+ + +Example +~~~~~~~ + +**Curl Request** + +:: + + curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers + +**Response** + +:: + + { + "loadBalancers":[ + { + "name":"lb-site1", + "id":"71", + "protocol":"HTTP", + "port":"80", + "algorithm":"LEAST_CONNECTIONS", + "status":"ACTIVE", + "created":"2010-11-30T03:23:42Z", + "updated":"2010-11-30T03:23:44Z" + }, + { + "name":"lb-site2", + "id":"166", + "protocol":"TCP", + "port":"9123", + "algorithm":"ROUND_ROBIN", + "status":"ACTIVE", + "created":"2010-11-30T03:23:42Z", + "updated":"2010-11-30T03:23:44Z" + } + ] + } + +.. _api-lb-status: + +Get Load Balancer Details +------------------------- + +Operation +~~~~~~~~~ + ++-----------------+--------------------------------+----------+--------------------------------------------------+ +| Resource | Operation | Method | Path | ++=================+================================+==========+==================================================+ +| Load Balancer | Get a specific load balancer | GET | {baseURI}/{ver}/loadbalancers/{loadbalancerId} | ++-----------------+--------------------------------+----------+--------------------------------------------------+ + +Description +~~~~~~~~~~~ + +This operation provides detailed description for a specific load +balancer configured and associated with your account. This operation is +not capable of returning details for a load balancer which has been +deleted. Details include load balancer virtual IP and node information. + +Request Data +~~~~~~~~~~~~ + +None required. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +None required. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 200 | OK | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~ + +The response body contains the load balancer requested or 404, if not +found. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------------+ +| HTTP Status Code | Description | ++====================+================+ +| 400 | Bad Request | ++--------------------+----------------+ +| 401 | Unauthorized | ++--------------------+----------------+ +| 404 | Not Found | ++--------------------+----------------+ +| 405 | Not Allowed | ++--------------------+----------------+ +| 500 | LBaaS Fault | ++--------------------+----------------+ + +Example +~~~~~~~ + +**Curl Request** + +:: + + curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/2000 + +**Response** + +:: + + { + "id": "2000", + "name":"sample-loadbalancer", + "protocol":"HTTP", + "port": "80", + "algorithm":"ROUND_ROBIN", + "status":"ACTIVE", + "created":"2010-11-30T03:23:42Z", + "updated":"2010-11-30T03:23:44Z", + "virtualIps":[ + { + "id": "1000", + "address":"192.168.1.1", + "type":"PUBLIC", + "ipVersion":"IPV4" + } + ], + "nodes": [ + { + "id": "1041", + "address":"10.1.1.1", + "port": "80", + "condition":"ENABLED", + "status":"ONLINE" + }, + { + "id": "1411", + "address":"10.1.1.2", + "port": "80", + "condition":"ENABLED", + "status":"ONLINE" + } + ], + } + +.. _api-lb-create: + +Create a New Load Balancer +-------------------------- + +Operation +~~~~~~~~~ + ++-----------------+------------------------------+----------+---------------------------------+ +| Resource | Operation | Method | Path | ++=================+==============================+==========+=================================+ +| Load Balancer | Create a new load balancer | POST | {baseURI}/{ver}/loadbalancers | ++-----------------+------------------------------+----------+---------------------------------+ + +Description +~~~~~~~~~~~ + +This operation provisions a new load balancer based on the configuration +defined in the request object. Once the request is validated and +progress has started on the provisioning process, a response object will +be returned. The object will contain a unique identifier and status of +the request. + +If the status returned is set to 'BUILD', then using the identifier of +the load balancer, the caller can check on the progress of the creation +operation by performing a GET on loadbalancers/{loadbalancerId}. When +the status of the load balancer returned changes to 'ACTIVE', then the +load balancer has been successfully provisioned and is now operational. + +**Load Balancer Status Values** + ++-------------------+----------------------------------------------------------------+ +| Status Name | Description | ++===================+================================================================+ +| BUILD | Load balancer is in a building state and not yet operational | ++-------------------+----------------------------------------------------------------+ +| ACTIVE | Load balancer is in an operational state | ++-------------------+----------------------------------------------------------------+ +| PENDING\_UPDATE | Load balancer is in the process of an update | ++-------------------+----------------------------------------------------------------+ +| ERROR | Load balancer is in an error state and not operational | ++-------------------+----------------------------------------------------------------+ + +The caller of this operation must specify at least the following +attributes of the load balancer: + +\*name + +\*at least one node + +If the request cannot be fulfilled due to insufficient or invalid data, +an HTTP 400 (Bad Request) error response will be returned with +information regarding the nature of the failure in the body of the +response. Failures in the validation process are non-recoverable and +require the caller to correct the cause of the failure and POST the +request again. + +By default, the system will create a load balancer with protocol set to +HTTP, port set to 80 (or 443 if protocol is TCP), and assign a public +IPV4 address to the load balancer. The default algorithm used is set to +ROUND\_ROBIN. + +A load balancer name has a max length that can be determined by querying +limits. + +Users may configure all documented features of the load balancer at +creation time by simply providing the additional elements or attributes +in the request. This document provides an overview of all the features +the load balancing service supports. + +If you have at least one load balancer, you may create subsequent load +balancers that share a single virtual IP by issuing a POST and supplying +a virtual IP ID instead of a type. Additionally, this feature is highly +desirable if you wish to load balance both an unsecured and secure +protocol using one IP address. For example, this method makes it +possible to use the same load balancing configuration to support an HTTP +and an TCP load balancer. Load balancers sharing a virtual IP must +utilize a unique port. + +Request Data +~~~~~~~~~~~~ + +The caller is required to provide a request data with the POST which +includes the appropriate information to create a new load balancer. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- **X-Auth-Token** +- **Accept: application/json** +- **Content-Type: application/json** + +Request Body +~~~~~~~~~~~~ + +The request body must follow the correct format for new load balancer +creation, examples.... + +**Request body example to create a load balancer with two nodes** + +:: + + { + "name": "a-new-loadbalancer", + "nodes": [ + { + "address": "10.1.1.1", + "port": "80" + }, + { + "address": "10.1.1.2", + "port": "81" + } + ] + } + +**Request body example to create a load balancer using existing load +balancer virtual IP** + +:: + + { + "name":"a-new-loadbalancer", + "port":"83", + "protocol":"HTTP", + "virtualIps": [ + { + "id":"39" + } + ], + "nodes": [ + { + "address":"10.1.1.1", + "port":"80", + "condition":"ENABLED" + } + ] + } + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 202 | Accepted | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~ + +The response body contains the load balancer requested or appropriate +error. + +**Create Load Balancer (Required Attributes with Shared IP) Response: +JSON** + +:: + + { + "name": "a-new-loadbalancer", + "id": "144", + "protocol": "HTTP", + "port": "83", + "algorithm": "ROUND_ROBIN", + "status": "BUILD", + "created": "2011-04-13T14:18:07Z", + "updated":"2011-04-13T14:18:07Z", + "virtualIps": [ + { + "address": "3ffe:1900:4545:3:200:f8ff:fe21:67cf", + "id": "39", + "type": "PUBLIC", + "ipVersion": "IPV6" + } + ], + "nodes": [ + { + "address": "10.1.1.1", + "id": "653", + "port": "80", + "status": "ONLINE", + "condition": "ENABLED" + } + ] + } + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+-----------------------+ +| HTTP Status Code | Description | ++====================+=======================+ +| 400 | Bad Request | ++--------------------+-----------------------+ +| 401 | Unauthorized | ++--------------------+-----------------------+ +| 404 | Not Found | ++--------------------+-----------------------+ +| 405 | Not Allowed | ++--------------------+-----------------------+ +| 413 | Over Limit | ++--------------------+-----------------------+ +| 500 | LBaaS Fault | ++--------------------+-----------------------+ +| 503 | Service Unavailable | ++--------------------+-----------------------+ + +Example +~~~~~~~ + +**Contents of Request file lb.json** + +:: + + { + "name": "lb #1", + "protocol":"tcp", + "nodes": [ + { + "address": "15.185.229.153", + "port": "443" + }, + { + "address": "15.185.226.163", + "port": "443" + }, + ], + } + +**Curl Request** + +:: + + curl -X POST -H "X-Auth-Token: TOKEN" --data-binary "@lb.json" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers + +**Response** + +:: + + { + "port":"443", + "id":"10", + "protocol":"tcp", + "updated":"2013-02-10T18:20Z", + "created":"2013-02-10T18:20Z", + "status":"BUILD", + "nodes":[ + { + "port":"443", + "id":"19", + "condition":"ENABLED", + "status":"ONLINE", + "address":"15.185.229.153" + }, + { + "port":"443", + "id":"20", + "condition":"ENABLED", + "status":"ONLINE", + "address":"15.185.226.163" + } + ], + "name":"lb #1", + "virtualIps":[ + { + "id":"5", + "address":"15.185.96.125", + "ipVersion":"IPV_4", + "type":"PUBLIC" + } + ], + "algorithm":"ROUND_ROBIN" + } + +.. _api-lb-modify: + +Update an Existing Load Balancer +-------------------------------- + +Operation +~~~~~~~~~ + ++-----------------+-----------------------------------+----------+--------------------------------------------------+ +| Resource | Operation | Method | Path | ++=================+===================================+==========+==================================================+ +| Load Balancer | Update load balancer attributes | PUT | {baseURI}/{ver}/loadbalancers/{loadbalancerId} | ++-----------------+-----------------------------------+----------+--------------------------------------------------+ + +Description +~~~~~~~~~~~ + +This operation updates the attributes of the specified load balancer. +Upon successful validation of the request, the service will return a 202 +(Accepted) response code. A caller should check that the load balancer +status is ACTIVE to confirm that the update has taken effect. If the +load balancer status is 'PENDING\_UPDATE' then the caller can poll the +load balancer with its ID (using a GET operation) to wait for the +changes to be applied and the load balancer to return to an ACTIVE +status. + +This operation allows the caller to change one or more of the following +attributes: + +\*name + +\*algorithm + +This operation does not return a response body. + +.. note:: + The load balancer ID, status, port and protocol are immutable + attributes and cannot be modified by the caller. Supplying an + unsupported attribute will result in a 400 (badRequest) fault. + +Request Data +~~~~~~~~~~~~ + +Load balancer body with attributes to be updated. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +**Example** + +:: + + { + "name": "newname-loadbalancer", + "algorithm": "LEAST_CONNECTIONS" + } + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 202 | Accepted | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~ + +None. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------------+ +| HTTP Status Code | Description | ++====================+================+ +| 400 | Bad Request | ++--------------------+----------------+ +| 401 | Unauthorized | ++--------------------+----------------+ +| 404 | Not Found | ++--------------------+----------------+ +| 405 | Not Allowed | ++--------------------+----------------+ +| 500 | LBaaS Fault | ++--------------------+----------------+ + +Example +~~~~~~~ + +**Contents of Request file lb.json** + +:: + + { + "name": "newname-loadbalancer", + "algorithm": "LEAST_CONNECTIONS" + } + +**Curl Request** + +:: + + curl -X PUT -H "X-Auth-Token: TOKEN" --data-binary "@lb.json" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100 + +**Response** + +status with no response body. + +.. _api-lb-delete: + +Delete Load Balancer +-------------------- + +Operation +~~~~~~~~~ + ++-----------------+------------------------------------+----------+--------------------------------------------------+ +| Resource | Operation | Method | Path | ++=================+====================================+==========+==================================================+ +| Load Balancer | Delete an existing load balancer | DELETE | {baseURI}/{ver}/loadbalancers/{loadbalancerId} | ++-----------------+------------------------------------+----------+--------------------------------------------------+ + +Description +~~~~~~~~~~~ + +Delete load balancer removes the specified load balancer and its +associated configuration from the account. Any and all configuration +data is immediately purged and is not recoverable. + +This operation does not require a request body. + +Request Data +~~~~~~~~~~~~ + +None required. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +None required. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 202 | Accepted | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~ + +None. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------------+ +| HTTP Status Code | Description | ++====================+================+ +| 400 | Bad Request | ++--------------------+----------------+ +| 401 | Unauthorized | ++--------------------+----------------+ +| 404 | Not Found | ++--------------------+----------------+ +| 405 | Not Allowed | ++--------------------+----------------+ +| 500 | LBaaS Fault | ++--------------------+----------------+ + +Example +~~~~~~~ + +**Curl Example** + +:: + + curl -X DELETE -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100 + +**Response** + +status with no response body. \ No newline at end of file diff --git a/doc/api/rest/logs.rst b/doc/api/rest/logs.rst new file mode 100644 index 00000000..67b03966 --- /dev/null +++ b/doc/api/rest/logs.rst @@ -0,0 +1,70 @@ +.. _api-logs: + +==== +Logs +==== + + +Archive log file to Object Storage +---------------------------------- + +Operation +~~~~~~~~~ + ++----------+------------------------------------+--------+-----------------------------------------------------+ +| Resource | Operation | Method | Path | ++==========+====================================+========+=====================================================+ +| Logs | Archive log file to Object Storage | POST | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/logs | ++----------+------------------------------------+--------+-----------------------------------------------------+ + +Description +~~~~~~~~~~~ + +The operation tells the load balancer to push the current log file into an HP Cloud Object Storage container. The status of the load balancer will be set to 'PENDING_UPDATE' during the operation and back to 'ACTIVE' upon success or failure. A success/failure message can be found in the 'statusDescription' field when getting the load balancer details. + +**Load Balancer Status Values** + ++----------------+---------------+--------------------------------+ +| Status | Name | Description | ++================+===============+================================+ +| ACTIVE | Load balancer | is in an operational state | +| PENDING_UPDATE | Load balancer | is in the process of an update | ++----------------+---------------+--------------------------------+ + +By default with empty POST data the load balancer will upload to the swift account owned by the same tenant as the load balancer in a container called 'lbaaslogs'. To change this the following optional parameters need to be provided in the POST body: + +**objectStoreBasePath** : the object store container to use + +**objectStoreEndpoint** : the object store endpoint to use including tenantID, for example: https://region-b.geo-1.objects.hpcloudsvc.com:443/v1/1234567890123 + +**authToken** : an authentication token to the object store for the load balancer to use + +Request Data +~~~~~~~~~~~~ + +The caller is required to provide a request data with the POST which includes the appropriate information to upload logs. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +The request body must follow the correct format for new load balancer creation, examples.... + +A request that uploads the logs to a different object store + +:: + + { + "objectStoreBasePath": "mylblogs", + "objectStoreEndpoint": "https://region-b.geo-1.objects.hpcloudsvc.com:443/v1/1234567890123", + "authToken": "HPAuth_d17efd" + } \ No newline at end of file diff --git a/doc/api/rest/node.rst b/doc/api/rest/node.rst new file mode 100644 index 00000000..24b6f8e4 --- /dev/null +++ b/doc/api/rest/node.rst @@ -0,0 +1,539 @@ +.._api-node: + +===== +Nodes +===== + + +.. _api-node-list: + +List All Load Balancer Nodes +---------------------------- + +Operation +~~~~~~~~~ + ++------------+-----------------------------------+----------+--------------------------------------------------------+ +| Resource | Operation | Method | Path | ++============+===================================+==========+========================================================+ +| Node | Get list of load balancer nodes | GET | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/nodes | ++------------+-----------------------------------+----------+--------------------------------------------------------+ + +Description +~~~~~~~~~~~ + +List all nodes for a specified load balancer. + +Request Data +~~~~~~~~~~~~ + +None required. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +None required. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 200 | OK | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~ + +The response body contains the load balancer nodes requested or 404, if +not found. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------------+ +| HTTP Status Code | Description | ++====================+================+ +| 400 | Bad Request | ++--------------------+----------------+ +| 401 | Unauthorized | ++--------------------+----------------+ +| 404 | Not Found | ++--------------------+----------------+ +| 405 | Not Allowed | ++--------------------+----------------+ +| 500 | LBaaS Fault | ++--------------------+----------------+ + +Example +~~~~~~~ + +**Curl Example** + +:: + + curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100/nodes + +**Response** + +:: + + { + "nodes" : [ + { + "id":"410", + "address":"10.1.1.1", + "port":"80", + "condition":"ENABLED", + "status":"ONLINE" + }, + { + "id":"236", + "address":"10.1.1.2", + "port":"80", + "condition":"ENABLED", + "status":"ONLINE" + }, + { + "id":"2815", + "address":"10.1.1.3", + "port":"83", + "condition":"DISABLED", + "status":"OFFLINE" + }, + ] + } + +.. _api-node-status: + +Get Load Balancer Node +---------------------- + +Operation +~~~~~~~~~~~~~~ + ++------------+-------------------------------------+----------+-----------------------------------------------------------------+ +| Resource | Operation | Method | Path | ++============+=====================================+==========+=================================================================+ +| Node | Get a specific load balancer node | GET | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/nodes/{nodeId} | ++------------+-------------------------------------+----------+-----------------------------------------------------------------+ + +Description +~~~~~~~~~~~ + +This operation retrieves the configuration of a node. + +Request Data +~~~~~~~~~~~~ + +None required. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~~~~~~ + +None required. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 200 | OK | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~ + +The response body contains the load balancer node requested or 404, if +not found. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------------+ +| HTTP Status Code | Description | ++====================+================+ +| 400 | Bad Request | ++--------------------+----------------+ +| 401 | Unauthorized | ++--------------------+----------------+ +| 404 | Not Found | ++--------------------+----------------+ +| 405 | Not Allowed | ++--------------------+----------------+ +| 500 | LBaaS Fault | ++--------------------+----------------+ + +Example +~~~~~~~ + +**Curl Example** + +:: + + curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100/nodes/410 + +**Response** + +:: + + { + "id":"410", + "address":"10.1.1.2", + "port":"80", + "condition":"ENABLED", + "status":"ONLINE" + } + +.. _api-node-create: + +Create Load Balancer Node +------------------------- + +Operation +~~~~~~~~~ + ++------------+-----------------------------------+----------+--------------------------------------------------------+ +| Resource | Operation | Method | Path | ++============+===================================+==========+========================================================+ +| Node | Create a new load balancer node | POST | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/nodes | ++------------+-----------------------------------+----------+--------------------------------------------------------+ + +Description +~~~~~~~~~~~ + +Add a new node to any existing load balancer. When a node is added, it is +assigned a unique identifier that can be used for mutating operations +such as changing the condition, or removing the node from the load +balancer. When a node is added to a load balancer it is enabled by +default. + +Request Data +~~~~~~~~~~~~ + +The request must contain information regarding the new node to be added. +More than one node can be added at a time. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +The request body defines the attributes of the new node to be created. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 202 | Accepted | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~ + +The response body contains the load balancer requested or 404, if not +found. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------------+ +| HTTP Status Code | Description | ++====================+================+ +| 400 | Bad Request | ++--------------------+----------------+ +| 401 | Unauthorized | ++--------------------+----------------+ +| 404 | Not Found | ++--------------------+----------------+ +| 405 | Not Allowed | ++--------------------+----------------+ +| 413 | Over Limit | ++--------------------+----------------+ +| 500 | LBaaS Fault | ++--------------------+----------------+ + +Example +~~~~~~~ + +**Contents of Request file nodes.json** + +:: + + { + "nodes": [ + { + "address": "10.1.1.1", + "port": "80" + }, + { + "address": "10.2.2.1", + "port": "80" + }, + { + "address": "10.2.2.2", + "port": "88", + "condition": "DISABLED" + } + ] + } + +**Curl Request** + +:: + + curl -X POST -H "X-Auth-Token: TOKEN" --data-binary "@nodes.json" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100/nodes + +**Response** + +:: + + { + "nodes": [ + { + "id": "7298", + "address": "10.1.1.1", + "port": "80", + "condition": "ENABLED", + "status": "ONLINE" + }, + { + "id": "293", + "address": "10.2.2.1", + "port": "80", + "condition": "ENABLED", + "status": "OFFLINE" + }, + { + "id": "183", + "address": "10.2.2.2", + "port": "88", + "condition": "DISABLED", + "status": "OFFLINE" + } + ] + } + +.. _api-node-modify: + +Update Load Balancer Node Condition +----------------------------------- + +Operation +~~~~~~~~~ + ++------------+-------------------------------+----------+-----------------------------------------------------------------+ +| Resource | Operation | Method | Path | ++============+===============================+==========+=================================================================+ +| Node | Update a load balancer node | PUT | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/nodes/{nodeId} | ++------------+-------------------------------+----------+-----------------------------------------------------------------+ + +Description +~~~~~~~~~~~ + +Every node in the load balancer is either enabled or disabled which +determines its role within the load balancer. When the node has +condition='ENABLED' the node is permitted to accept new connections. Its +status will eventually become 'ONLINE' to reflect this configuration. +When the node has condition='DISABLED' the node is not permitted to +accept any new connections. Existing connections to the node are +forcibly terminated. The nodes status changes to OFFLINE once the +configuration has been successfully applied. + +The node IP and port are immutable attributes and cannot be modified +with a PUT request. Supplying an unsupported attribute will result in a +fault. A load balancer supports a maximum number of nodes. The +maximum number of nodes per load balancer is returned when querying the +limits of the load balancer service. + +Request Data +~~~~~~~~~~~~ + +Request data includes the desired condition of the node. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +The request body includes the node 'condition' attribute and its desired +state. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 202 | Accepted | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~ + +None. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------------+ +| HTTP Status Code | Description | ++====================+================+ +| 400 | Bad Request | ++--------------------+----------------+ +| 401 | Unauthorized | ++--------------------+----------------+ +| 404 | Not Found | ++--------------------+----------------+ +| 405 | Not Allowed | ++--------------------+----------------+ +| 500 | LBaaS Fault | ++--------------------+----------------+ + +Example +~~~~~~~ + +**Contents of Request file node.json** + +:: + + { + "condition": "DISABLED" + } + +**Curl Request** + +:: + + curl -X PUT -H "X-Auth-Token: TOKEN" --data-binary "@node.json" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100/nodes/100 + +**Response** + +status with no response body. + +.. _api-node-delete: + +Delete Load Balancer Node +------------------------- + +Operation +~~~~~~~~~~~~~~ + ++------------+-------------------------------+----------+-----------------------------------------------------------------+ +| Resource | Operation | Method | Path | ++============+===============================+==========+=================================================================+ +| Node | Delete a load balancer node | DELETE | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/nodes/{nodeId} | ++------------+-------------------------------+----------+-----------------------------------------------------------------+ + +Description +~~~~~~~~~~~ + +Delete node for a load balancer. + +.. note:: + A load balancer must have at least one node. Attempting to remove the last + node of a load balancer will result in a 401 error. + +Request Data +~~~~~~~~~~~~ + +None required. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +None required. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 202 | Accepted | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~ + +None. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------------+ +| HTTP Status Code | Description | ++====================+================+ +| 400 | Bad Request | ++--------------------+----------------+ +| 401 | Unauthorized | ++--------------------+----------------+ +| 404 | Not Found | ++--------------------+----------------+ +| 405 | Not Allowed | ++--------------------+----------------+ +| 500 | LBaaS Fault | ++--------------------+----------------+ + +Example +~~~~~~~ + +**Curl Request** + +:: + + curl -X DELETE -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100/nodes/100 + +**Response** + +status with no response body. \ No newline at end of file diff --git a/doc/api/rest/protocols.rst b/doc/api/rest/protocols.rst new file mode 100644 index 00000000..26856e64 --- /dev/null +++ b/doc/api/rest/protocols.rst @@ -0,0 +1,107 @@ +.. _api-protocols: + +========= +Protocols +========= + + +Get List of Supported LBaaS Protocols +------------------------------------- + +Operation +~~~~~~~~~ + ++-------------+-----------------------------------+----------+-----------------------------+ +| Resource | Operation | Method | Path | ++=============+===================================+==========+=============================+ +| Protocols | Get list of supported protocols | GET | {baseURI}/{ver}/protocols | ++-------------+-----------------------------------+----------+-----------------------------+ + +Description +~~~~~~~~~~~ + +All load balancers must be configured with the protocol of the service which is +being load balanced. The protocol selection should be based on the protocol of +the back-end nodes. The current specification supports HTTP (port 80) and TCP +(port 443) services. HTTPS traffic is supported currently via the TCP +connection. Support for SSL termination on the load balancer is not +currently supported. + + +Request Data +~~~~~~~~~~~~ + +None required. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +None required. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 200 | OK | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~ + +The response body contains the currently supported protocols and port +numbers. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------------+ +| HTTP Status Code | Description | ++====================+================+ +| 400 | Bad Request | ++--------------------+----------------+ +| 401 | Unauthorized | ++--------------------+----------------+ +| 404 | Not Found | ++--------------------+----------------+ +| 405 | Not Allowed | ++--------------------+----------------+ +| 500 | LBaaS Fault | ++--------------------+----------------+ + +Example +~~~~~~~ + +**Curl Request** + +:: + + curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/protocols + +**Response** + +:: + + { + "protocols": [ + { + "name": "HTTP", + "port": 80 + }, + { + "name": "TCP", + "port": 443 + } + ] + } \ No newline at end of file diff --git a/doc/api/rest/vip.rst b/doc/api/rest/vip.rst new file mode 100644 index 00000000..8024a8a9 --- /dev/null +++ b/doc/api/rest/vip.rst @@ -0,0 +1,101 @@ +.. _api-vips: + +=========== +Virtual IPs +=========== + + +Get List of Virtual IPs +----------------------- + +Operation +~~~~~~~~~ + ++--------------+---------------------------+----------+-------------------------------------------------------------+ +| Resource | Operation | Method | Path | ++==============+===========================+==========+=============================================================+ +| Virtual IP | Get list of virtual IPs | GET | {baseURI}/{ver}/loadbalancers/{loadbalancerId}/virtualips | ++--------------+---------------------------+----------+-------------------------------------------------------------+ + +Description +~~~~~~~~~~~ + +This operation lists all the virtual IP addresses of a load balancer. The +maximum number of VIPs that can be configured when creating a load +balancer can be discovered by querying the limits of the load balancer service. + +Request Data +~~~~~~~~~~~~ + +None required. + +Query Parameters Supported +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +None required. + +Required HTTP Header Values +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**X-Auth-Token** + +Request Body +~~~~~~~~~~~~ + +None required. + +Normal Response Code +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+---------------+ +| HTTP Status Code | Description | ++====================+===============+ +| 200 | OK | ++--------------------+---------------+ + +Response Body +~~~~~~~~~~~~~ + +The response body contains the load balancer VIP list requested or 404, +if not found. + +Error Response Codes +~~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------------+ +| HTTP Status Code | Description | ++====================+================+ +| 400 | Bad Request | ++--------------------+----------------+ +| 401 | Unauthorized | ++--------------------+----------------+ +| 404 | Not Found | ++--------------------+----------------+ +| 405 | Not Allowed | ++--------------------+----------------+ +| 500 | LBaaS Fault | ++--------------------+----------------+ + +Example +~~~~~~~ + +**Curl Request** + +:: + + curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100/virtualips + +**Response** + +:: + + { + "virtualIps": [ + { + "id": "1021", + "address": "206.10.10.210", + "type": "PUBLIC", + "ipVersion": "IPV4" + } + ] + }