Atlas-LB

Note
 * 1) !wiki caution

If you want to discuss changes to this spec or found an error, please contact uma.goring AT rackspace.com or youcef.laribi AT citrix.com

= OpenStack LoadBalancers API 1.1 =

Intended Audience
This guide is intended for software developers who want to create applications using the OpenStack Load Balancers API. It assumes the reader has a general understanding of load balancing concepts and is familiar with:


 * ReSTful web services
 * HTTP/1.1 conventions
 * JSON and/or XML serialization formats

Document Change History
This version of the Developer Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Concepts
To use OpenStack Load Balancers API effectively, you should understand several key concepts:

Load Balancer
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.

Virtual IP
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 balanced. Incoming connections and requests are distributed to back-end nodes based on the configuration of the load balancer.

Node
A node is a back-end device providing a service on a specified IP and port.

Health Monitoring
A health monitor is a feature of each load balancer. It is used to determine whether or not a back-end node of the load balancer is usable for processing a request. The load balancing service supports two health monitoring modes: passive and active.

Passive Health Monitoring
By default, all load balancing configurations utilize passive health monitoring, which is the default monitoring and does not require any configuration from the user. If the passive health monitoring determines that a node is down, unreachable or malfunctioning, it puts the node in an OFFLINE state and stops sending traffic to it.

Active Health Monitoring
Active health monitoring is a technique that is explicitly configured by users. It uses synthetic transactions executed at periodic intervals to determine the condition of a node. When active monitoring is activated, it takes over the monitoring of the nodes, and passive monitoring is disabled. Conversely, when active monitoring is removed by the user, passive monitoring is re-enabled for the nodes of the load balancer. This guarantees that the nodes health is always monitored.

When configuring active health monitoring, a user can choose between using one of three types of probes:


 * CONNECT
 * HTTP
 * HTTPS

These probes are executed at configured intervals; in the event of a failure, the node status changes to OFFLINE and the node will not receive traffic. If, after running a subsequent test, the probe detects that the node has recovered, then the node's status is changed to ONLINE and it is capable of servicing requests.

Session Persistence
Session persistence is a feature of the load balancing service. It attempts to force subsequent connections or requests in the same session to be redirected to the same node as long as it is online.

General API Information
Sections in this chapter describe operations and guidelines that are common to all OpenStack APIs, and are not specific to the Load Balancing API.

Authentication
This API uses the standard defined by OpenStack for authentication. This is currently a work in progress. Once this is finalized, this section will describe how users can authenticate and obtain a token from the OpenStack Authentication service, and how they can present this token in the Load Balancing API.

Refer to current status of OpenStack Authentication at http://wiki.openstack.org/openstack-authn and to OpenStack project KeyStone for detailed information.

Service Access/Endpoints
Your service provider will publish the endpoints that you can use to connect to the LB service it operates.

Request/Response Types
The Cloud Load Balancers API supports both the JSON and XML data serialization formats. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using either the Accept header or adding an .xml or .json extension to the request URI. Note that it is possible for a response to be serialized using a format different from the request. If no response format is specified, JSON is the default. If conflicting formats are specified using both an Accept header and a query extension, the query extension takes precedence.

'''Table 3.1. JSON and XML Response Formats '''

Content Compression
Request and response body data may be encoded with gzip compression to accelerate interactive performance of API calls and responses. This is controlled using the Accept-Encoding header in the request from the client and indicated by the Content-Encoding header in the server response.

Unless the header is explicitly set, encoding defaults to disabled.

'''Table 3.2. Encoding Headers'''

Persistent Connections
By default, the API supports persistent connections via HTTP/1.1 keep-alives. All connections will be kept alive unless the connection header is set to close.

#!wiki caution Note

The server may close the connection at any time and clients should not rely on this behavior.

Paginated Collections
To reduce load on the service, list operations will return a maximum of 100 items at a time. To navigate the collection, the limit and marker parameters (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. Note that list operations never return 404 (itemNotFound) faults.

Limits
Accounts may be preconfigured with a set of thresholds (or limits) to manage capacity and prevent abuse of the system. The system recognizes two kinds of limits: rate limits and absolute limits. Rate limits are thresholds that are reset after a certain amount of time passes. Absolute limits are fixed.

Rate Limits
We specify rate limits in terms of both a human-readable wild-card URI and a machine-processable regular expression. The regular expression boundary matcher '^' takes effect after the root URI path. For example, the regular expression/v1.1/1234/loadbalancers would match the bold portion of the following URI:  .

'''Table 3.3. Default Rate Limits'''

Rate limits are applied in order relative to the verb, going from least to most specific. For example, although the threshold for POST to /v1.1/* is 25 per minute, one cannot POST to /v1.1/* more than 2 times per second because the rate limit for any POST is 2 per second. In the event you exceed the thresholds established for your account, a 413 (Rate Control) HTTP response will be returned with a Retry-After header to notify the client when they can attempt to try again.

Absolute Limits
Absolute limits are specified as name/value pairs. Then name of the absolute limit uniquely identifies the limit within a deployment. For example maxNodesPerLoadbalancer identifies the total number of nodes that may be associated with a given load balancer.

The following table shows some of these limits and example values:

Determining Limits Programmatically
Applications can programmatically determine current account limits using the /limits URI as follows:

Normal Response Code(s): 200

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

This operation does not require a request body.

'''Example 3.1. List Limits Response: XML '''

#!highlight xml numbers=disable   

 

''' Example 3.2. List Limits Response: JSON '''

#!highlight javascript numbers=disable {   "limits" : {           "rate" : { "values": [ {                                   "uri" : "/v1.1/*", "regex" : "^/1./.*", "limit" : [ {                                                "verb" : "GET", "value" : 600000, "remaining" : 426852, "unit" : "HOUR", "next-available" : "2011-02-22T19:32:43.835Z" }                                             ]                                  }

]                    },            "absolute" : { "values" : { "maxNodesPerLoadBalancer" : "5", "maxVIPsPerLoadBalancer" : "1" }                        }          } }

Faults
API calls that return an error return one of the following fault objects. All fault objects extend from the base fault, serviceFault, for easier exception handling for languages that support it.

serviceFault
The serviceFault and by extension all other faults include message and detail elements which contain strings describing the nature of the fault as well as a code attribute representing the HTTP response code for convenience. The code attribute of the fault is for the convenience of the caller so that they may retrieve the response code from the HTTP response headers or directly from the fault object if they choose. The caller should not expect the serviceFault to be returned directly but should instead expect only one of the child faults to be returned.

badRequest
This fault indicates that the data in the request object is invalid; for example, a string was used in a parameter that was expecting an integer. The fault will wrap validation errors.

'''Example 3.3. Fault Response, badRequest'''

#!highlight xml numbers=disable  Validation fault The object is not valid  Node IP address is invalid. Please specify a valid IP address.  

immutableEntity
This fault is returned when a user attempts to modify an item that is not currently in a state that allows modification. For example, load balancers in a status of BUILD,PENDING_UPDATE or DELETED may not be modified.

''' Example 3.4. Fault Response, immutableEntity '''

#!highlight xml numbers=disable  The object at the specified URI is immutable and cannot be modified. 

itemNotFound
'''Example 3.5. Fault Response, itemNotFound '''

#!highlight xml numbers=disable  Object not Found 

loadBalancerFault
The loadBalancerFault fault shall be returned in the event that an unpexpected error occurred during a loadbalancer operation.

''' Example 3.6. Fault Response, loadBalancerFault '''

#!highlight xml numbers=disable  Load Balancer has experienced an internal error 

outOfVirtualIps
This fault indicates that there are no virtual IPs left to assign to a new load balancer. In practice, this fault should not occur, as virtual IPs will be ordered as capacity is required.

''' Example 3.7. Fault Response, outOfVirtualIps '''

#!highlight xml numbers=disable  Out of virtual IPs. Please contact support so they can allocate more virtual IPs. </outOfVirtualIps>

overLimit
This fault is returned when the user has exceeded a currently allocated limit.

''' Example 3.8. Fault Response, overLimit '''

#!highlight xml numbers=disable <overLimit code="413" xmlns="http://docs.openstack.org/atlas/api/v1.1"> Load balancer cannot be created. You have reached your maximum number of load balancers. </overLimit>

serviceUnavailable
This fault is returned when the service is unavailable, such as when the service is undergoing maintenance. Note that this does not necessarily mean that the currently configured load balancers are unable to process traffic; it simply means that the API is currently unable to service requests.

''' Example 3.9. Fault Response, serviceUnavailable '''

#!highlight xml numbers=disable <serviceUnavailable code="500" xmlns="http://docs.openstack.org/atlas/api/v1.1"> The Load balancing service is currently not available </serviceUnavailable>

unauthorized
This fault is returned when the user is not authorized to perform an attempted operation.

''' Example 3.10. Fault Response, unauthorized '''

#!highlight xml numbers=disable <unauthorized code="401" xmlns="http://docs.openstack.org/atlas/api/v1.1"> You are not authorized to execute this operation.

unprocessableEntity
This fault is returned when an entity cannot be processed due to semantic errors.

'''Example 3.11. Fault Response, unprocessableEntity'''

#!highlight xml numbers=disable <unprocessableEntity code="422" xmlns="http://docs.openstack.org/atlas/api/v1.1"> The Object at the specified URI is unprocessable. </unprocessableEntity>

API Operations
This chapter explains specific API operations. For ideas relevant to all API operations, see the "General API Information" chapter.

List Load Balancers
Normal Response Code(s): 200

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

This operation provides a list of all load balancers configured and associated with your account.

To view deleted load balancers, add "?status=DELETED" to the end of the GET URI. A deleted loadbalancer is immutable and irrecoverable.

This operation returns the following attributes for each load balancer:


 * id
 * name
 * algorithm
 * protocol
 * port
 * status
 * created
 * updated

This operation does not require a request body.

'''Example 4.1. List Load Balancers Response: XML '''

#!highlight xml numbers=disable <?xml version="1.0" ?> <loadBalancers xmlns="http://docs.openstack.org/atlas/api/v1.1"> <loadBalancer id="71" name="lb-site1" status="ACTIVE" protocol="HTTP" port="80" algorithm="LEAST_CONNECTIONS" created="2010-12-13T15:38:27-06:00" updated="2010-12-13T15:38:38-06:00" > </loadBalancer>

<loadBalancer id="166" name="lb-site2" status="ACTIVE" protocol="HTTP" port="80" algorithm="ROUND_ROBIN" created="2010-12-13T15:38:27-06:00" updated="2010-12-13T15:38:38-06:00" > </loadBalancer> </loadBalancers>

'''Example 4.2. List Load Balancers Response: JSON'''

#!highlight javascript numbers=disable { "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" }     ] }

List Load Balancer Details
Normal Response Code(s): 200

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

This operation provides detailed output 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.

This operation does not require a request body.

'''Example 4.3. List Load Balancer Details Response: XML'''

#!highlight xml numbers=disable <loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1" 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> <virtualIp id="1000" address="2001:cdba:0000:0000:0000:0000:3257:9652" type="PUBLIC" ipVersion="IPV6" /> </virtualIps>

<node id="1041" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" /> <node id="1411" address="10.1.1.2" port="80" condition="ENABLED" status="ONLINE" />

<sessionPersistence persistenceType="HTTP_COOKIE"/>

<connectionThrottle maxRequestRate="50" rateInterval="60" />

</loadBalancer>

'''Example 4.4. List Load Balancers Details Response: JSON'''

#!highlight javascript numbers=disable {     "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":"2001:cdba:0000:0000:0000:0000:3257:9652", "type":"PUBLIC", "ipVersion":"IPV6" }                  ],

"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" }                    ],       "sessionPersistence":{ "persistenceType":"HTTP_COOKIE" },      "connectionThrottle":{ "maxRequestRate": "50", "rateInterval": "60" } }

Create Load Balancer
Normal Response Code(s): 202

Error Response Code(s): loadbalancerFault (500), serviceUnavailable (503), unauthorized (401),badRequest (400), overLimit (413)

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.

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.

#!wiki caution Note

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 IPV6 address to the loadbalancer. The default algorithm used is set to ROUND_ROBIN.

#!wiki caution Note

A load balancer's name has a max length that can be queried when 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.

#!wiki caution Note

Users may request either an IPv4 or IPV6 address by specifying the version in the create request. For example to request a public IPV6 virtual IP address for the load balancer, use the following virtualIP element in the request:

<virtualIp type="PUBLIC" ipVersion="IPV6"/>

If the version attribute is not specified, then an IPv6 IP address is allocated by default.

'''Example 4.5. Create Load Balancer (Required Attributes) Request: XML'''

#!highlight xml numbers=disable <loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1" name="a-new-loadbalancer"> <node address="10.1.1.1" port="80" /> <node address="10.1.1.2" port="81" /> </loadBalancer>

'''Example 4.6. Create Load Balancer (Required Attributes) Request: JSON '''

#!highlight javascript numbers=disable {   "name": "a-new-loadbalancer", "nodes":     [ {                     "address": "10.1.1.1", "port": "80" },                   {                      "address": "10.1.1.2", "port": "81" }                  ] }

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.

#!wiki caution Note

Load balancers sharing a virtual IP must utilize a unique port.

'''Example 4.7. Create Load Balancer (Required Attributes with Shared IP) Request: XML '''

#!hightlight xml <loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1" name="a-new-loadbalancer" port="83" protocol="HTTP"> <virtualIps> <virtualIp id="39"/> </virtualIps>

<node address="10.1.1.1" port="80" condition="ENABLED" /> </loadBalancer>

'''Example 4.8. Create Load Balancer (Required Attributes with Shared IP) Request: JSON '''

#!highlight javascript numbers=disable {  "name":"a-new-loadbalancer", "port":"83", "protocol":"HTTP", "virtualIps": [ {                     "id":"39" }                ],   "nodes":      [ {                     "address":"10.1.1.1", "port":"80", "condition":"ENABLED" }                ] }

''' Example 4.9. Create Load Balancer (Required Attributes with Shared IP) Response: XML '''

#!highlight xml numbers=disable <loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1" id="144" name="a-new-loadbalancer" algorithm="ROUND_ROBIN" protocol="HTTP" port="83" status="BUILD" created="2011-02-08T21:19:55Z" updated="2011-02-08T21:19:55Z" >

<virtualIps> <virtualIp id="39" address="3ffe:1900:4545:3:200:f8ff:fe21:67cf" ipVersion="IPV6" type="PUBLIC" /> </virtualIps>

<node id="653" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" /> </loadBalancer>

'''Example 4.10. Create Load Balancer (Required Attributes with Shared IP) Response: JSON '''

#!highlight javascript numbers=disable {   "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" }                 ] }

Update Load Balancer Attributes
Normal Response Code(s): 202

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

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.

#!wiki caution Note

The load balancer's 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.

'''Example 4.11. Update Load Balancer Attributes Request: XML '''

#!highlight xml numbers=disable <loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1" name="newname-loadbalancer" algorithm="LEAST_CONNECTIONS" />

'''Example 4.12. Update Load Balancer Attributes Request: JSON '''

#!highlight javascript numbers=disable {  "name": "newname-loadbalancer", "algorithm": "LEAST_CONNECTIONS" }

'''Table 4.1. Load Balancer Statuses'''

Note that a load balancer whose status is SUSPENDED is not operational and traffic to it is rejected and will not be forwarded to back-end nodes.

Remove Load Balancer
Normal Response Code(s): 202

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

The remove load balancer function 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.

This operation does not return a response body.

Deleted load balancers are still displayed for a number of days after deletion when listing load balancers of an account. Their status is changed to DELETED.The updated date of a DELETED load balancer reflects the time/date of its deletion.

Nodes
The nodes defined by the load balancer are responsible for servicing the requests received through the load balancer's virtual IP. By default, the load balancer employs a basic health check that ensures the node is 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 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.

The status of the node can be determined by passive or active health monitoring.

The caller can assign the relevant weights to nodes using the weight attribute of the node element.

The weight of a node determines the portion of requests or connections it services compared to the other nodes of the load balancer. For example, if node A has a weight of 2 and node B has a weight of 1, then the loadbalancer will forward twice as many requests to node A than to node B. If the weight attribute is not specified, then the node's weight is implicitly set to "1".

List Nodes
List all nodes of a load balancer.

Normal Response Code(s): 200

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

This operation does not require a request body.

'''Example 4.13. List Nodes Response: XML '''

#!highlight xml numbers=disable <node id="410" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" /> <node id="236" address="10.1.1.2" port="80" condition="ENABLED" status="ONLINE" /> <node id="2815" address="10.1.1.3" port="83" condition="DISABLED" status="OFFLINE" />

'''Example 4.14. List Node Response: JSON'''

#!highlight javascript numbers=disable { "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" },           ] }

Retrieve a Node
This operation retrieves the configuration of a node.

Normal Response Code(s): 200

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

This operation does not require a request body.

'''Example 4.15. Retrieve the configuration of a node Response: XML '''

#!highlight xml numbers=disable <node id="236" address="10.1.1.2" port="80" condition="ENABLED" status="ONLINE" />

'''Example 4.16. Retrieve a node Response: JSON'''

#!highlight javascript numbers=disable { "id":"236", "address":"10.1.1.2", "port":"80", "condition":"ENABLED", "status":"ONLINE" }

Add Nodes
Normal Response Code(s): 202

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

When a node is added, it is assigned a unique identifier that can be used for mutating operations such as changing the condition or the weight of a node, or removing the node from the load balancer.

Every load balancer is dual-homed on both the public Internet and the internal network; as a result, nodes can either be internal private addresses or addresses on the public Internet.

#!wiki caution Note:

When a node is added to a load balancer, it is enabled by default.

'''Example 4.17. Add Nodes Request: XML'''

#!highlight xml numbers=disable <nodes xmlns="http://docs.openstack.org/atlas/api/v1.1"> <node address="10.1.1.1" port="80" /> <node address="10.2.2.1" port="80" weight="2" /> <node address="10.2.2.2" port="88" condition="DISABLED" weight="2" />

'''Example 4.18. Add Nodes Request: JSON'''

#!highlight javascript numbers=disable { "nodes": [ {              "address": "10.1.1.1", "port": "80" },            {               "address": "10.2.2.1", "port": "80", "weight": "2" },            {               "address": "10.2.2.2", "port": "88", "condition": "DISABLED", "weight": "2" }          ] }

'''Example 4.19. Add Nodes Response: XML'''

#!highlight xml numbers=disable <nodes xmlns="http://docs.openstack.org/atlas/api/v1.1"> <node id="7298" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" /> <node id="293" address="10.2.2.1" port="80" weight="2" condition="ENABLED" status="OFFLINE" /> <node id="183" address="10.2.2.2" port="88" weight="2" condition="DISABLED" status="OFFLINE" />

'''Example 4.20. Add Nodes Response: JSON'''

#!highlight javascript numbers=disable { "nodes": [ {              "id": "7298", "address": "10.1.1.1", "port": "80", "condition": "ENABLED", "status": "ONLINE" },            {               "id": "293", "address": "10.2.2.1", "port": "80", "weight": "2", "condition": "ENABLED", "status": "OFFLINE" },            {               "id": "183", "address": "10.2.2.4", "port": "88", "weight": "2", "condition": "DISABLED", "status": "OFFLINE" }          ] }

Modify Nodes
Normal Response Code(s): 202

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

This operation does not return a response body.

#!wiki caution Note

The node's IP and port are immutable attributes and cannot be modified with a PUT request. Supplying an unsupported attribute will result in a 400 (badRequest) 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.

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 regardless of session persistence configuration. Existing connections to the node are forcibly terminated. The node's status changes to OFFLINE once the configuration has been successfully applied.

'''Example 4.21. Disable a node Request: XML'''

#!highlight xml numbers=disable <node condition="DISABLED" />

'''Example 4.22. Disable a node Request: JSON'''

#!highlight javascript numbers=disable { "condition": "DISABLED" }

Even if a node is configured with condition="ENABLED", its status may remain as OFFLINE if there is a configuration or operational error of the node or its load balancer.

Remove Nodes
Normal Response Code(s): 200, 202

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

This operation does not require a request body.

This operation does not return a response body.

#!wiki caution Note

A load balancer must have at least one node. Attempting to remove the last node of a loadbalancer will result in a badRequest (400) error.

Virtual IPs
A virtual IP (VIP) makes a load balancer accessible by clients. The load balancing service supports either a public VIP, routable on the public Internet, or a private address, routable only within the region in which the load balancer resides.

'''Table 4.3. Virtual IP Types'''

List Virtual IPs
Normal Response Code(s): 200

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

This operation lists all the virtual IP addresses of a load balancer.

This request does not require a request body.

#!wiki caution Note

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.

'''Example 4.23. List Virtual IPs Response: XML'''

#!highlight xml numbers=disable <virtualIps xmlns="http://docs.openstack.org/atlas/api/v1.1"> <virtualIp id="1021" address="206.10.10.210" type="PUBLIC" ipVersion="IPV4"/> </virtualIps>

'''Example 4.24. List Virtual IPs Response: JSON'''

#!highlight javascript numbers=disable { "virtualIps": [ {                  "id": "1021", "address": "206.10.10.210", "type": "PUBLIC", "ipVersion": "IPV4" }               ] }

List Usage
Normal Response Code(s): 200

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

This operation does not require a request body.

The load balancer usage reports provide a set of usage counters. This list will contain at least the transferBytesIn and transferBytesOut usage counters that represent respectively the amount of traffic in bytes received by the load balancer from clients requests, and the amount fo traffic sent from the nodes as responses to clients.

'''Example 4.25. Report Load Balancer Usage Response: XML'''

#!highlight xml numbers=disable <loadBalancerUsageRecords xmlns="http://docs.openstack.org/atlas/api/v1.1"> <loadBalancerUsageRecord id="394"  transferBytesIn="2819204" transferBytesOut="84923069" /> <loadBalancerUsageRecord id="473" transferBytesIn="0" transferBytesOut="0" /> </loadBalancerUsageRecords>

'''Example 4.26. Report Load Balancer Usage Response: JSON'''

#!highlight javascript numbers=disable { "loadBalancerUsageRecords": [ {                                 "id": "394", "transferBytesIn": "2819204", "transferBytesOut": "84923069" },                               {                                  "id": "473", "transferBytesIn": "0", "transferBytesOut": "0" }                             ] }

Monitors
Normal Response Code(s): 200, 202

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

In addition to the default passive monitoring, the load balancing service includes an active health monitoring operation which periodically checks your back-end nodes to ensure they are responding correctly.

Active health monitoring provides 3 types of health monitors. The caller can configure one health monitor on the load blancer.

The health monitor has a type attribute to signify which of the 3 types it is. The 3 types available in this specification are described below.

'''Table 4.4. Health Monitor Types'''

Monitor CONNECT
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.
 * 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 must be less than the delay value.
 * attemptsBeforeDeactivation: Number of permissible monitor failures before removing a node from rotation. Must be a number between 1 and 10.

'''Example 4.27. Monitor CONNECT Request: XML'''

#!highlight xml numbers=disable <healthMonitor xmlns="http://docs.openstack.org/atlas/api/v1.1" type="CONNECT" delay="20" timeout="10" attemptsBeforeDeactivation="3" />

'''Example 4.28. Monitor CONNECT Request: JSON'''

#!highlight javascript numbers=disable { "type": "CONNECT", "delay": "20", "timeout": "10", "attemptsBeforeDeactivation": "3" }

'''Example 4.29. Monitor Connections Response: XML'''

#!highlight xml numbers=disable <healthMonitor xmlns="http://docs.openstack.org/atlas/api/v1.1" type="CONNECT" delay="10" timeout="10" attemptsBeforeDeactivation="3" />

'''Example 4.30. Monitor Connections Response: JSON'''

#!highlight javascript numbers=disable { "type": "CONNECT", "delay": "20", "timeout": "10", "attemptsBeforeDeactivation": "3" }

Monitor HTTP and HTTPS
The HTTP and HTTPS monitor is more intelligent than the CONNECT monitor. It is capable of processing an HTTP or HTTPS 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.

'''Example 4.31. Monitor HTTP Response: XML'''

#!highlight xml numbers=disable <healthMonitor xmlns="http://docs.openstack.org/atlas/api/v1.1" type="HTTP" delay="10" timeout="3" attemptsBeforeDeactivation="2" path="/" />

'''Example 4.32. Monitor HTTPS Response: XML'''

#!highlight xml numbers=disable <healthMonitor xmlns="http://docs.openstack.org/atlas/api/v1.1" type="HTTPS" delay="10" timeout="3" attemptsBeforeDeactivation="3" path="/healthcheck" />

'''Example 4.33. Monitor HTTPS Response: JSON'''

#!highlight javascript numbers=disable {  "type": "HTTPS", "delay": "10", "timeout": "3", "attemptsBeforeDeactivation": "3", "path": "/healthcheck" }

If a load balancer has no health monitoring configuration, then the LB service will return an empty response when retrieving (GET request) a health monitoring configuration.

Manage Session Persistence
Normal Response Code(s): 200, 202

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

Session persistence is a feature of the load balancing service which forces multiple requests from clients to be directed to the same node. This is common with many web applications that do not inherently share application state between back-end servers.

'''Table 4.5. Session Persistence Modes'''

'''Example 4.34. List Session Persistence Configuration Response: XML'''

#!highlight xml numbers=disable <sessionPersistence xmlns="http://docs.openstack.org/atlas/api/v1.1" persistenceType="HTTP_COOKIE" />

'''Example 4.35. List Session Persistence Configuration Response: JSON'''

#!highlight javascript numbers=disable {  "persistenceType":"HTTP_COOKIE" }

'''Example 4.36. Set Session Persistence Type Request: XML'''

#!highlight xml numbers=disable <sessionPersistence xmlns="http://docs.openstack.org/atlas/api/v1.1" persistenceType="HTTP_COOKIE" />

'''Example 4.37. Set Session Persistence Type Request: JSON'''

#!highlight javascript numbers=disable {   "persistenceType":"HTTP_COOKIE" }

Throttle Connections
Normal Response Code(s): 200, 202

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

The connection throttling feature imposes limits on the number of connections per client IP address to help mitigate malicious or abusive traffic to your applications. The following properties can be configured based on the traffic patterns for your sites.


 * maxRequestRate: Maximum number of HTTP requests (or TCP connections) allowed from a single IP address in the defined rateInterval. Setting a value of 0 allows an unlimited connection or request rate.
 * rateInterval: Frequency (in seconds) at which the maxRequestRate is assessed. For example, a maxRequestRate of 30 with a rateInterval of 60 would allow a maximum of 30 HTTP requests or TCP connections per minute from a single IP address. This attribute must have a value between 1 and 3600.

#!wiki caution Note

When the rate is exceeded, the load balancer returns a serviceUnavailable (503) error to new requests for HTTP/HTTPS loadbalancers. For TCP loadbalancers, new connections are refused.

'''Example 4.42. List Connection Throttling Configuration Response: XML'''

#!highlight xml numbers=disable <connectionThrottle xmlns="http://docs.openstack.org/atlas/api/v1.1" maxRequestRate="50" rateInterval="60" />

'''Example 4.43. List Connection Throttling Configuration Response: JSON'''

#!highlight javascript numbers=disable {   "maxRequestRate": "50", "rateInterval": "60" }

'''Example 4.44. Update Connection Throttling Configuration Request: XML'''

#!highlight xml numbers=disable <connectionThrottle xmlns="http://docs.openstack.org/atlas/api/v1.1" maxRequestRate="40" />

'''Example 4.45. Update Connection Throttling Configuration Request: JSON'''

#!highlight javascript numbers=disable {  "maxRequestRate": "40" }

List Load Balancing Protocols
Normal Response Code(s): 200

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

This operation does not require a request body.

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.

'''Example 4.46. List Load Balancing Protocols Response: XML'''

#!highlight xml numbers=disable <protocols xmlns="http://docs.openstack.org/atlas/api/v1.1"> <protocol name="HTTP" port="80" /> <protocol name="HTTPS" port="443" /> <protocol name="TCP" port="*" />

'''Example 4.47. List Load Balancing Protocols Response: JSON'''

#!highlight javascript numbers=disable { "protocols": [ {                "name": "HTTP", "port": "80" },              {                 "name": "HTTPS", "port": "443" },              {                 "name": "TCP", "port": "*" }             ] }

Algorithms
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.

'''Table 4.6. Load Balancing Algorithms'''

List Load Balancing Algorithms
Normal Response Code(s): 200

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

This operation does not require a request body.

'''Example 4.48. List Load Balancing Algorithms Response: XML'''

#!highlight xml numbers=disable <algorithms xmlns="http://docs.openstack.org/atlas/api/v1.1"> <algorithm name="ROUND_ROBIN" /> <algorithm name="LEAST_CONNECTIONS" />

'''Example 4.49. List Load Balancing Algorithms Response: JSON'''

#!highlight javascript numbers=disable {  "algorithms": [ {                   "name": "ROUND_ROBIN" },                 {                    "name": "LEAST_CONNECTIONS" }                ] }

API Extensions
Implementations of this API specifications are free to augment this core API with extensions as they see appropriate (e.g. support for new LB algorithms or protocols).

All client applications written to this core specification however must be supported by extended implementations. Therefore, an application using this API should not receive payloads or values not specified in this specification nor should it need to specify extra information in requests not described in this specification.

For a detailed description of how to develop and use Extension APIs in OpenStack services, refer to OpenStack Compute API 1.1 documentation on the OpenStack website.