= [[OpenStack]] [[LoadBalancers]] API 1.1 =

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

This version of the Developer Guide replaces and obsoletes all previous versions. The most recentchanges are described in the table below:  

| May 18, 2011  

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

=== Health Monitor ===

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

==== Passive Health Monitor ====

By default, all load balancing configurations utilize a passive health monitor, which is the default monitoring and does not require 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 Monitor ====

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

The active health monitor can use one of three types of probes:  

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

 

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

Load Balancing API will use the standard defined by [[OpenStack]] for authentication. 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 using the Load Balancing API.

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

Your service provider will publish the endpoints that you can use to connect to their LB service.

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

 

 

 

 

 

 

 

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

|-

 

 

 

 

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

Accounts may be preconfigured set of thresholds (or limits) to manage capacity and prevent abuse ofthe 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.

| '''Verb'''

| '''URI'''

| '''RegEx'''

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

| '''Name'''

| '''Value'''

| maxLoadBalancers

| 20

| maxNodesPerLoadBalancer

| 5

| maxVIPsperLoadBalancer

| 2

| maxDaysForDeletedLoadBalancers

| 15

| maxLoadBalancerNameLength

| 15

Applications can programmatically determine current account limits using the /limitsURI as  follows:

 

| '''Verb'''

| '''URI'''

| GET

| /limits

<limits xmlns="http://docs.openstack.org/common/api/v1.1">

   <rates>

           <limit  verb="GET"  value="600000"

                   remaining="426852"  unit="HOUR"      

       </rate>  

   </rates>  

   <absolute>  

       <limit name="maxNodesPerLoadBalancer" value="5"/>

       <limit name="maxVIPsperLoadBalancer" value="2"/>

   </absolute>  

     "limits" :  

                                   {

                                     "uri" : "/v1.1/*",

                                     "regex" : "^/1./.*",  

                                               {

                                                 "verb" : "GET",

                                                 "value" : 600000,

                                                 "remaining" : 426852,

                                                 "unit" : "HOUR",

                                               ]  

                                 ]  

                     },  

                           "values" : {  

                                         "maxNodesPerLoadBalancer" : 5,

                                         "maxVIPsperLoadBalancer" : 2

                         }  

           }  

 

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

The serviceFault and by extension all other faults include message and detailelements 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 xmlns="http://docs.openstack.org/loadbalancers/api/v1.1" code="400">

   <message>Validation fault</message>  

       <message>Node ip is invalid. Please specify a valid ip.</message>

   </validationErrors>  

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 PENDING_UPDATE,BUILD, or DELETED may not be modified.  

<immutableEntity code="422" xmlns="http://docs.openstack.org/loadbalancers/api/v1.1">  

   <message>The object at the specified URI is immutable and can not be overwritten.</message> </immutableEntity>

<itemNotFound code="404" xmlns="http://docs.openstack.org/loadbalancers/api/v1.1">  

   <message>Object not Found</message>  

<loadBalancerFault code="500" xmlns="http://docs.openstack.org/loadbalancers/api/v1.1">  

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. If you do experience this fault, contact support so that we may make more IPs available.  

<outOfVirtualIps code="500" xmlns="http://docs.openstack.org/loadbalancers/api/v1.1">

   <message>  

       Out of virtual IPs. Please contact support so they can allocate more virtual IPs.  

   </message>  

</outOfVirtualips>

<overLimit code="413" xmlns="http://docs.openstack.org/loadbalancers/api/v1.1">

     Your account is currently over the limit so your requestcould not be processed.

   </message>  

<serviceUnavailable code="500" xmlns="http://docs.openstack.org/loadbalancers/api/v1.1">

   <message>The Load balancing service is currently not available</message>

<unauthorized code="401" xmlns="http://docs.openstack.org/loadbalancers/api/v1.1">  

     <message>You are not authorized to execute this operation.</message>

This fault is returned when an operation is requested on an item that was unabled to be followed due to semantic errors.  

<unprocessableEntity code="422" xmlns="http://docs.openstack.org/loadbalancers/api/v1.1">

   <message>The Object at the specified URI is unprocessable.</message>  

</unprocessableEntity>  

 

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

| Verb

| URI

| Description

| GET

| /loadbalancers

| List all load balancers configured for theaccount.

'''Normal Response Code(s)''': 200  

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 url. A deleted loadbalancer is immutable and irrecoverable.

* id  

* name  

* created  

This operation does not require a request body.  

<?xml version="1.0" ?>  

<loadBalancers xmlns="http://docs.openstack.org/loadbalancers/api/v1.1">  

   <loadBalancer id="71" name="lb-site1" status="ACTIVE"  

                 protocol="HTTP" port="80" algorithm="RANDOM">

 

    <created time="2010-12-13T15:38:27-06:00" />

    <updated time="2010-12-13T15:38:38-06:00" />  

   <loadBalancer id="166" name="lb-site2" status="ACTIVE"  

                 protocol="HTTP" port="80" algorithm="RANDOM">

 

    <created time="2010-12-13T15:38:27-06:00" />

    <updated time="2010-12-13T15:38:38-06:00" />  

</loadBalancers>  

{  

         {  

           "name":"lb-site1",  

           "id":"71",  

           "protocol":"HTTP",  

           "port":"80",  

           "algorithm":"ROUND_ROBIN",  

           "status":"ACTIVE",

                      ],

           "created": {

                        "time":"2010-11-30T03:23:42Z"  

                      },

           "updated": {

                        "time":"2010-11-30T03:23:44Z"

         {  

           "name":"lb-site2",  

           "id":"166",  

           "protocol":"TCP",  

           "port":"9123",  

           "algorithm":"LEAST_CONNECTIONS",  

           "status":"ACTIVE",

                      ],

           "created":  {

                        "time":"2010-11-30T03:23:42Z"  

                      },

           "updated":  {

                        "time":"2010-11-30T03:23:44Z"  

}  

| Verb

| URI

| Description

| GET

| /loadbalancers/''loadBalancerId''

| List details of the specified load balancer.

'''Normal Response Code(s)''': 200  

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.  

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.1"

   id="2000"  

   protocol="HTTP"  

   port="80"  

   algorithm="ROUND_ROBIN"  

   status="ACTIVE">  

     <virtualIp id="1000" address="206.10.10.210" type="PUBLIC" ipVersion="IPV4" />  

   <nodes>  

     <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"/>

 

  <connectionLogging enabled="false" />  

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

</loadBalancer>  

{  

  "loadBalancer": {

                    "id": 2000,  

                    "name":"sample-loadbalancer",  

                    "protocol":"HTTP",  

                    "port": 80,  

                    "algorithm":"ROUND_ROBIN",  

                    "status":"ACTIVE",  

 

                    "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  

                                    "name":"c1.dfw1"  

                  }            

| Verb

| URI

| Description

| POST

| /loadbalancers

| Create a new load balancer with the configuration defined by the request.

'''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  

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.  

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.  

Note  

If the version attribute is not specified, then an IPv4 IP address is allocated.

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.1"  

               name="a-new-loadbalancer" port="80" protocol="HTTP">  

 

    <nodes>  

       <node address="10.1.1.1" port="80" condition="DISABLED"/>  

       <node address="10.1.1.2" port="81" />  

</loadBalancer>  

{  

                    "name": "a-new-loadbalancer",  

                    "nodes":      [

                                  {  

                                    "address": "10.1.1.1",  

                                    "port": "80",

                                  },

                                  {  

                                    "address": "10.1.1.2",  

                                    "port": "81"

                                  }

                                  ]

}  

Note  

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

Example 4.7. Create Load Balancer (Required Attributes with Shared IP)

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.1"  

port="80"  

protocol="HTTP">  

<virtualIps>

 

 

"loadBalancer":{

"name":"a-new-loadbalancer",  

"port":"80",  

"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

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.1"

id="144"  

name="a-new-loadbalancer"  

algorithm="ROUND_ROBIN"  

protocol="HTTP"

status="BUILD">  

<virtualIps>

<virtualIp

id="39"  

address="206.10.10.210"  

ipVersion="IPV4"  

type="PUBLIC" />

 

"name": "a-new-loadbalancer",  

"id": 144,  

"protocol": "HTTP",

"port": 83,

"algorithm": "ROUND_ROBIN",

"status": "BUILD",  

"cluster": {

 

"name": "ztm-n01.staging1.lbaas.demo.net"

},

"nodes": [

 

{  

"address": "10.1.1.1",  

"id": 653,

"port": 80,

"status": "ONLINE",  

"condition": "ENABLED"

 

}

],

"virtualIps": [

 

{  

"address": "206.10.10.210",  

"id": 39,  

"type": "PUBLIC",

"ipVersion": "IPV4"

 

"time": "2011-04-13T14:18:07Z"

},

"time": "2011-04-13T14:18:07Z"

"enabled": false

4.1.4. Update Load Balancer Attributes

PUT /loadbalancers/loadBalancerIdUpdate the properties of a loadbalancer.  

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

This operation allows the caller to change one or more of the following attributes:

This operation does not return a response body.  

The load balancer's ID, status, port and protocol are immutable attributes and cannotbe modified by the caller. Supplying an unsupported attribute will result in a 400(badRequest) fault.  

Example 4.11. Update Load Balancer Attributes Request: XML

 

{"loadBalancer":{

"name": "sample-loadbalancer",  

"algorithm": "ROUND_ROBIN"  

}  

The load balancer's status attribute reflects the current configuration status of the device. This status isimmutable by the caller and is updated automatically based on state changes within the service. Whena load balancer is first created, it may be placed into a BUILDstatus while the configuration is beinggenerated and applied based on the request. Once the configuration is applied and finalized, it will be in

an ACTIVEstatus. In the event of a configuration change or update, the status of the load balancer maychange to PENDING_UPDATEto signify configuration changes are in progress but have not yet beenfinalized. Load balancers in a SUSPENDEDstatus reject traffic and will not forward requests to back-

end nodes.  

Table 4.1. Load Balancer Statuses

DELETED Load balancers in DELETEDstatus can be displayed for a certain number of days after deletion.

The number of days is queryable.  

4.1.5. Remove Load Balancer

/loadbalancers/loadBalancerId  

Remove a load balancer from the account.  

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 configurationfrom the account. Any and all configuration data is immediately purged and is not recoverable.  

This operation does not require a request body.  

4.2. Nodes

The nodes defined by the load balancer are responsible for servicing the requests received through theload balancer's virtual IP. By default, the load balancer employs a basic health check that ensures thenode is listening on its defined port. The node is checked at the time of addition and at regular intervalsas defined by the load balancer health check configuration. If a back-end node is not listening on its portor does not meet the conditions of the defined active health check for the load balancer, then the loadbalancer will not forward connections and its status will be listed as OFFLINE. Only nodes that are in

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

4.2.1. List Nodes

GET /loadbalancers/loadBalancerId/nodes/nodeId

This operation does not require a request body.  

Example 4.13. List Node Response: XML

address="10.1.1.1"

{"node": {

"id":"410",

"address":"10.1.1.1",

"port":80,

"condition":"ENABLED",

"status":"ONLINE"

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<nodes xmlns="http://docs.openstack.org/loadbalancers/api/v1.1">

id="650"

address="10.1.1.1"

port="80"

condition="ENABLED"

status="ONLINE"/>

id="183"