Jump to: navigation, search

Difference between revisions of "Atlas-LB"

m (added to neutron)
 
(112 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
__NOTOC__
 
−
= [[OpenStack]] [[LoadBalancers]] API 1.1 =
 
  
−
<<[[TableOfContents]]()>>
+
<!-- #acl [[YoucefLaribi]]:read,write,delete,revert,admin [[UmaGoring]]:read,write,delete,revert,admin Uma.Goring:read,write,delete,revert,admin All:read -->
  
−
== Overview ==
+
<pre><nowiki>#!wiki caution
 +
'''Note'''
  
−
=== Intended Audience ===
+
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
 +
</nowiki></pre>
  
−
~+~-
+
= OpenStack LoadBalancers API 1.1 =
 +
__TOC__
  
−
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:  
+
== Overview ==
 +
=== 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  
+
* ReSTful web services
 
* HTTP/1.1 conventions
 
* HTTP/1.1 conventions
−
* JSON and/or XML serialization formats  
+
* JSON and/or XML serialization formats
−
 
 
−
-~+~
 
  
 
=== Document Change History ===
 
=== 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:
−
~+~-
 
−
 
 
−
This version of the Developer Guide replaces and obsoletes all previous versions. The most recentchanges are described in the table below:  
 
−
 
 
−
-~+~
 
  
 
==== Revision Date Summary of Changes ====
 
==== Revision Date Summary of Changes ====
−
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
−
| '''Revision Date'''
+
| '''Revision Date'''  
 
|-
 
|-
−
| May 18, 2011
+
| Feb 9, 2012
 +
|-
 +
| Jan. 24, 2012
 +
|-
 +
| May 27, 2011  
 
|-
 
|-
 
| Apr. 19, 2011  
 
| Apr. 19, 2011  
Line 38: Line 37:
 
|}
 
|}
  
−
-~+~
 
−
 
−
^l
 
 
== Concepts ==
 
== Concepts ==
−
 
+
To use OpenStack Load Balancers API effectively, you should understand several key concepts:
−
~+~-
 
−
To use [[OpenStack]] Load Balancers API effectively, you should understand several key concepts:  
 
−
-~+~
 
  
 
=== Load Balancer ===
 
=== 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.
−
~+~-
 
−
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 ===
 
=== 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.
−
~+~-
 
−
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 ===
 
=== 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 on a specified IP and port.  
 
−
-~+~
 
  
−
=== Health Monitor ===
+
=== 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.
−
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 ====
+
==== Passive Health Monitoring ====
−
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.  
+
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 Monitor ====
+
==== 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.
−
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.  
 
−
-~+~
 
  
−
~+~-
+
When configuring active health monitoring, a user can choose between using one of three types of probes:
−
The active health monitor can use one of three types of probes:  
 
−
-~+~
 
  
−
* CONNECT  
+
* CONNECT
−
* HTTP
+
* HTTP
−
* HTTPS  
+
* 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.
−
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 ===
−
~+~-
+
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.
−
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.  
 
−
-~+~
 
−
 
 
−
=== Connection Logging ===
 
−
~+~-
 
−
The connection logging feature allows for retrieving access logs (for HTTP-based protocol traffic) or connection and transfer logs (for all other traffic)
 
−
-~+~
 
  
−
^l
 
 
== General API Information ==
 
== 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.
−
Sections in this chapter describe operations and guidelines that are common to all [[OpenStack]] APIs, not specific to the Load Balancing API.  
 
−
-~+~
 
  
 
=== Authentication ===
 
=== 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.
−
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 and to OpenStack project [[KeyStone]] for detailed information.
−
Refer to current status of [[OpenStack]] Authentication at http://wiki.openstack.org/openstack-authn for detailed information  
 
−
-~+~
 
  
 
=== Service Access/Endpoints ===
 
=== Service Access/Endpoints ===
−
~+~-
+
Your service provider will publish the endpoints that you can use to connect to the LB service it operates.
−
Your service provider will publish the endpoints that you can use to connect to their LB service.  
 
−
-~+~
 
  
 
=== Request/Response Types ===
 
=== 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.
−
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 '''
 
'''Table 3.1. JSON and XML Response Formats '''
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
−
| '''Format'''
+
| '''Format'''  
−
| '''Accept Header'''
+
| '''Accept Header'''  
−
| '''Query Extension'''
+
| '''Query Extension'''  
 
|-
 
|-
−
| JSON
+
| JSON  
−
| application/json
+
| application/json  
−
| .json
+
| .json  
 
|-
 
|-
−
| XML
+
| XML  
−
| application/xml
+
| application/xml  
−
| .xml
+
| .xml  
 
|}
 
|}
  
 
=== Content Compression ===
 
=== 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.
 
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.
−
Unless the header is explicitly set, encoding defaults to disabled.  
 
−
-~+~
 
  
 
'''Table 3.2. Encoding Headers'''
 
'''Table 3.2. Encoding Headers'''
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
−
| '''Header'''
+
| '''Header'''  
−
| '''Type'''
+
| '''Type'''  
−
| '''Name'''
+
| '''Name'''  
 
|-
 
|-
−
| HTTP/1.1
+
| HTTP/1.1  
−
| Request
+
| Request  
−
| Accept-Encoding
+
| Accept-Encoding  
 
|-
 
|-
−
| HTTP/1.1
+
| HTTP/1.1  
−
| Response
+
| Response  
−
| Content-Encoding
+
| Content-Encoding  
 
|}
 
|}
  
 
=== Persistent Connections ===
 
=== 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.
−
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.  
 
−
-~+~
 
  
−
== General API Information ==
 
  
−
Sections in this chapter describe operations and guidelines that are common to all [[OpenStack]] APIs, not specific to the Load Balancing API.
+
<pre><nowiki>#!wiki caution
 +
'''Note'''
  
−
=== Authentication ===
+
The server may close the connection at any time and clients should not rely on this behavior.
−
~+~-
+
</nowiki></pre>
−
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
 
−
-~+~
 
  
−
=== Service Access/Endpoints ===
+
=== Paginated Collections ===
−
Your service provider will publish the endpoints that you can use to connect to their LB service.
+
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.
−
3. 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
 
−
Format Accept Header Query Extension Default
 
−
JSON application/json .json Yes
 
−
XML application/xml .xml No
 
−
4. 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
 
−
Header Type Name Value
 
−
HTTP/1.1 Request Accept-Encoding gzip
 
−
HTTP/1.1 Response Content-Encoding gzip
 
−
5. Persistent Connections
 
−
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.
 
  
−
Note
+
=== 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.
  
−
The server may close the connection at any time and clients should not rely on thisbehavior.  
+
==== 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: <code><nowiki>https://loadbalancers.api.openstack.org</nowiki></code>'''<code><nowiki>/v1.1/1234/loadbalancers</nowiki></code>'''.
  
−
3.6. Paginated Collections
+
'''Table 3.3. Default Rate Limits'''
−
To reduce load on the service, list operations will return a maximum of 100 items at a time. To navigatethe collection, the limitand markerparameters (for example, ?limit=50&marker=1) canbe set in the URI. If a marker beyond the end of a list is given, an empty list is returned. Note that listoperations never return 404 (itemNotFound) faults.  
+
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Verb'''
 +
| '''URI'''
 +
| '''RegEx'''
 +
|-
 +
| GET
 +
| /v1.1/*
 +
| ^/1.1/.*
 +
|-
 +
| POST
 +
| /v1.1/*
 +
| ^/1.1/.*
 +
|-
 +
| POST
 +
| /v1.1/*
 +
| ^/1.1/.*
 +
|-
 +
| PUT
 +
| /v1.1/*
 +
| ^/1.1/.*
 +
|-
 +
| DELETE
 +
| /v1.1/*
 +
| ^/1.1/.*
 +
|}
  
−
3.7. 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.
−
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 arethresholds that are reset after a certain amount of time passes. Absolute limits are fixed.  
 
  
−
3.7.1. Rate Limits  
+
==== Absolute Limits ====
−
We specify rate limits in terms of both a human-readable wild-card URI and a machine-processableregular expression. The regular expression boundary matcher '<sup>' takes effect after the root URI path. Forexample, the regular expression </sup>/v1.1/1234/loadbalancerswould match the bolded portionof the following URI: https://loadbalancers.api.openstack.org/v1.1/1234/
+
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.
−
loadbalancers.  
 
  
−
Table 3.3. Default Rate Limits
+
The following table shows some of these limits and example values:
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Name'''
 +
| '''Value'''
 +
|-
 +
| maxLoadBalancers
 +
| 20
 +
|-
 +
| maxNodesPerLoadBalancer
 +
| 5
 +
|-
 +
| maxVIPsPerLoadBalancer
 +
| 1
 +
|-
 +
| maxDaysKeptForDeletedLoadBalancers
 +
| 15
 +
|-
 +
| maxLoadBalancerNameLength
 +
| 15
 +
|}
  
−
Verb URI [[RegEx]] Default Limit
+
==== Determining Limits Programmatically ====
−
GET /v1.1/* ^/1.1/.* 5/second
+
Applications can programmatically determine current account limits using the /limits URI as  follows:
−
POST /v1.1/* ^/1.1/.* 2/second
+
{| border="1" cellpadding="2" cellspacing="0"
−
POST /v1.1/* ^/1.1/.* 25/minute
+
| '''Verb'''
−
PUT /v1.1/* ^/1.1/.* 5/second
+
| '''URI'''
−
DELETE /v1.1/* ^/1.1/.* 2/second
+
|-
−
 
+
| GET
−
Rate limits are applied in order relative to the verb, going from least to most specific. For example,
+
| /limits  
−
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 thethresholds established for your account, a 413 (Rate Control) HTTP response will be returned with aRetry-Afterheader to notify the client when they can attempt to try again.
+
|}
−
 
 
−
3.7.2. Absolute Limits
 
−
Absolute limits are specified as name/value pairs. Then name of the absolute limit uniquely identifiesthe limit within a deployment. For example maxNodesPerLoadbalanceridentifies 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:
 
−
 
 
−
Name Value Description
 
−
maxLoadBalancers 20 Maximum loadbalancers that
 
−
can be created for this account
 
−
 
 
−
5
 
−
 
 
−
^l
 
−
General API Information
 
  
−
Name Value Description
+
'''Normal Response Code(s)''': 200
−
maxNodesPerLoadBalancer 5 Maximum nodes allowed
 
−
per load balancer
 
−
maxVIPsperLoadBalancer 2 Maximum VIPs allowed
 
−
per load balancer
 
−
maxDaysForDeletedLoadBalancers 15 The maximum number of daysthat deleted loadbalancers
 
−
can be queried by the user
 
−
maxLoadBalancerNameLength 15 Maximum length of a load balancer name
 
  
−
3.7.3. Determining Limits Programmatically
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
−
Applications can programmatically determine current account limits using the /limitsURI as
 
−
follows:  
 
  
−
Verb
+
This operation does not require a request body.
  
−
URI
+
'''Example 3.1. List Limits Response: XML '''
  
−
Description
 
  
−
GET  
+
<pre><nowiki>#!highlight xml numbers=disable
 +
<limits xmlns="http://docs.openstack.org/common/api/v1.1">
 +
  <rates>
 +
      <rate uri="/v1.1/*" regex="^/1.1/.*">
 +
          <limit  verb="GET"  value="600000"
 +
                  remaining="426852"  unit="HOUR"
 +
                  next-available="2011-02-22T19:32:43.835Z"/>
 +
      </rate>
 +
  </rates>
  
−
/limits  
+
  <absolute>
 +
      <limit name="maxNodesPerLoadBalancer" value="5"/>
 +
      <limit name="maxVIPsPerLoadBalancer" value="1"/>
 +
  </absolute>
 +
</limits>
 +
</nowiki></pre>
  
−
Return the current limits for the account.  
+
''' Example 3.2. List Limits Response: JSON '''
  
−
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
 
−
 
−
<limits xmlns="http:/-/docs.openstack.org/common/api/v1.1">
 
−
<rates>
 
−
<rate uri="/v1.1/*" regex="^/1.1/-.*">
 
−
 
−
<limit
 
−
verb="GET"
 
−
value="600000"
 
−
remaining="426852"
 
−
unit="HOUR"
 
−
next-available="2011-02-22T19:32:43.835Z"/>
 
−
 
−
</rate>
 
−
</rates>
 
−
<absolute>
 
−
 
−
<limit name="maxNodesPerLoadBalancer" value="5"/>
 
−
<limit name="maxVIPsperLoadBalancer" value="2"/>
 
−
</absolute>
 
−
</limits>
 
−
 
−
6
 
−
 
−
^l
 
−
General API Information
 
−
 
−
Example 3.2. List Limits Response: JSON
 
  
 +
<pre><nowiki>#!highlight javascript numbers=disable
 
  {
 
  {
−
"limits" : {
+
    "limits" :
−
"rate" : {
+
          {
−
"values": [
+
            "rate" : {
−
 
+
                      "values": [
−
{  
+
                                  {
−
"uri" : "/v1.1/*",  
+
                                    "uri" : "/v1.1/*",
−
"regex" : "^/1.1/-.*",  
+
                                    "regex" : "^/1./.*",
−
"limit" : [
+
                                    "limit" : [
−
 
+
                                              {
−
{  
+
                                                "verb" : "GET",
−
"verb" : "GET",  
+
                                                "value" : 600000,
−
"value" : 600000,  
+
                                                "remaining" : 426852,
−
"remaining" : 426852,  
+
                                                "unit" : "HOUR",
−
"unit" : "HOUR",  
+
                                                "next-available" : "2011-02-22T19:32:43.835Z"
−
"next-available" : "2011-02-22T19:32:43.835Z"
+
                                              }
 +
                                              ]
 +
                                  }
  
−
}
+
                                ]
−
]
+
                    },
 +
            "absolute" : {
 +
                          "values" : {
 +
                                        "maxNodesPerLoadBalancer" : "5",
 +
                                        "maxVIPsPerLoadBalancer" : "1"
 +
                                      }
 +
                        }
 +
          }
 
}
 
}
 +
</nowiki></pre>
  
−
]
+
=== 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.
−
"absolute" : {
 
  
−
"values" : {
+
==== serviceFault ====
−
"maxNodesPerLoadBalancer" : 5,
+
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.
−
"maxVIPsperLoadBalancer" : 2
 
  
−
}
+
==== 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.
−
}
 
−
}
 
  
−
3.8. Faults
+
'''Example 3.3. Fault Response, badRequest'''
−
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.
 
  
−
3.8.1. serviceFault
 
−
The serviceFaultand by extension all other faults include messageand detailelements which
 
−
contain strings describing the nature of the fault as well as a codeattribute representing the HTTPresponse code for convenience. The codeattribute 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 faultobject if they choose. The caller should not expect the serviceFaultto be returned directly butshould instead expect only one of the child faults to be returned.
 
  
−
3.8.2. badRequest
+
<pre><nowiki>#!highlight xml numbers=disable
−
This fault indicates that the data in the request object is invalid; for example, a string was used in aparameter that was expecting an integer. The fault will wrap validation errors.  
+
<badRequest xmlns="http://docs.openstack.org/atlas/api/v1.1" code="400">
 +
  <message>Validation fault</message>
 +
  <details>The object is not valid</details>
 +
  <validationErrors>
 +
      <message>Node IP address is invalid. Please specify a valid IP address.</message>
 +
  </validationErrors>
 +
</badRequest>
 +
</nowiki></pre>
  
−
7
+
==== 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.
  
−
^l
+
''' Example 3.4. Fault Response, immutableEntity '''
−
General API Information
 
  
−
Example 3.3. Fault Response, badRequest
 
  
−
<badRequest xmlns="http://docs.openstack.org/loadbalancers/api/v1.1"
+
<pre><nowiki>#!highlight xml numbers=disable
 +
<immutableEntity code="422" xmlns="http://docs.openstack.org/atlas/api/v1.1">
 +
  <message>The object at the specified URI is immutable and cannot be modified.
 +
  </message>
 +
</immutableEntity>
 +
</nowiki></pre>
  
−
code="400">
+
==== itemNotFound ====
−
<message>Validation fault</message>
+
'''Example 3.5. Fault Response, itemNotFound '''
−
<details>The object is not valid</details>
 
  
−
<validationErrors>
 
−
<message>Node ip is invalid. Please specify a valid ip.</
 
−
message>
 
−
</validationErrors>
 
−
</badRequest>
 
  
−
3.8.3. immutableEntity
+
<pre><nowiki>#!highlight xml numbers=disable
−
This fault is returned when a user attempts to modify an item that is not currently in a state that allowsmodification. For example, load balancers in a status of PENDING_UPDATE,BUILD, or DELETEDmaynot be modified.
+
<itemNotFound code="404" xmlns="http://docs.openstack.org/atlas/api/v1.1">
 +
  <message>Object not Found</message>
 +
</itemNotFound>
 +
</nowiki></pre>
  
−
Example 3.4. Fault Response, immutableEntity
+
==== loadBalancerFault ====
 +
The loadBalancerFault fault shall be returned in the event that an unpexpected error occurred during a loadbalancer operation.
  
−
<immutableEntity code="422" xmlns="http://docs.openstack.org/
+
''' Example 3.6. Fault Response, loadBalancerFault '''
−
loadbalancers/api/v1.1">
 
−
<message>The object at the specified URI is immutable and can notbe overwritten.</message>
 
−
</immutableEntity>
 
  
−
3.8.4. itemNotFound
 
−
Example 3.5. Fault Response, itemNotFound
 
  
−
<itemNotFound code="404" xmlns="http://docs.openstack.org/
+
<pre><nowiki>#!highlight xml numbers=disable
−
loadbalancers/api/v1.1">
+
<loadBalancerFault code="500" xmlns="http://docs.openstack.org/atlas/api/v1.1">
−
<message>Object not Found</message>
+
  <message>Load Balancer has experienced an internal error</message>
−
</itemNotFound>  
+
</loadBalancerFault>
 +
</nowiki></pre>
  
−
3.8.5. loadBalancerFault
+
==== outOfVirtualIps ====
−
The loadBalancerFaultfault shall be returned in the event that an error occurred during aloadbalancer operation.  
+
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.6. Fault Response, loadBalancerFault
+
''' Example 3.7. Fault Response, outOfVirtualIps '''
  
−
<loadBalancerFault code="500" xmlns="http://docs.openstack.org/
 
−
loadbalancers/api/v1.1">
 
−
<message>Load Balancer has experienced an internal error</message>
 
−
</loadBalancerFault>
 
  
−
8
+
<pre><nowiki>#!highlight xml numbers=disable
 +
<outOfVirtualIps code="500" xmlns="http://docs.openstack.org/atlas/api/v1.1">
 +
  <message>
 +
      Out of virtual IPs. Please contact support so they can allocate more virtual IPs.
 +
  </message>
 +
</outOfVirtualIps>
 +
</nowiki></pre>
  
−
^l
+
==== overLimit ====
−
General API Information
+
This fault is returned when the user has exceeded a currently allocated limit.
  
−
3.8.6. outOfVirtualIps
+
''' Example 3.8. Fault Response, overLimit '''
−
This fault indicates that there are no virtual IPs left to assign to a new load balancer. In practice, thisfault should not occur, as virtual IPs will be ordered as capacity is required. If you do experience thisfault, contact support so that we may make more IPs available.
 
  
−
Example 3.7. Fault Response, outOfVirtualIps
 
  
−
<outOfVirtualIps code="500" xmlns="http://docs.openstack.org/
+
<pre><nowiki>#!highlight xml numbers=disable
−
loadbalancers/api/v1.1">  
+
<overLimit code="413" xmlns="http://docs.openstack.org/atlas/api/v1.1">
−
<message>
+
  <message>
−
Out of virtual IPs. Please contact support so they can allocatemore virtual IPs.  
+
    Load balancer cannot be created. You have reached your maximum number of load balancers.
−
</message>
+
  </message>
−
</outOfVirtualips>  
+
</overLimit>
 +
</nowiki></pre>
  
−
3.8.7. overLimit
+
==== serviceUnavailable ====
−
This fault is returned when the user has exceeded a currently allocated limit.  
+
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.8. Fault Response, overLimit
+
''' Example 3.9. Fault Response, serviceUnavailable '''
  
−
<overLimit code="413" xmlns="http://docs.openstack.org/loadbalancers/
 
−
api/v1.1">
 
−
<message>Your account is currently over the limit so your requestcould not be processed.</message>
 
−
</overLimit>
 
  
−
3.8.8. serviceUnavailable
+
<pre><nowiki>#!highlight xml numbers=disable
−
This fault is returned when the service is unavailable, such as when the service is undergoingmaintenance. Note that this does not necessarily mean that the currently configured loadbalancers areunable to process traffic; it simply means that the API is currently unable to service requests.
+
<serviceUnavailable code="500" xmlns="http://docs.openstack.org/atlas/api/v1.1">
 +
  <message>The Load balancing service is currently not available</message>
 +
</serviceUnavailable>
 +
</nowiki></pre>
  
−
Example 3.9. Fault Response, serviceUnavailable
+
==== unauthorized ====
 +
This fault is returned when the user is not authorized to perform an attempted operation.
  
−
<serviceUnavailable code="500" xmlns="http://docs.openstack.org/
+
''' Example 3.10. Fault Response, unauthorized '''
−
loadbalancers/api/v1.1">
 
−
<message>The Load balancing service is currently not available</
 
−
message>
 
−
</serviceUnavailable>
 
  
−
3.8.9. unauthorized
 
−
This fault is returned when the user is not authorized to perform an attempted operation.
 
  
−
9
+
<pre><nowiki>#!highlight xml numbers=disable
 +
<unauthorized code="401" xmlns="http://docs.openstack.org/atlas/api/v1.1">
 +
    <message>You are not authorized to execute this operation.</message>
 +
</unauthorized>
 +
</nowiki></pre>
  
−
^l
+
==== unprocessableEntity ====
−
General API Information
+
This fault is returned when an entity cannot be processed due to semantic errors.
  
−
Example 3.10. Fault Response, unauthorized
+
'''Example 3.11. Fault Response, unprocessableEntity'''
  
−
<unauthorized code="401" xmlns="http://docs.openstack.org/
 
−
loadbalancers/api/v1.1">
 
−
<message>You are not authorized to execute this operation.</
 
−
message>
 
−
</unauthorized>
 
  
−
3.8.10. unprocessableEntity
+
<pre><nowiki>#!highlight xml numbers=disable
−
This fault is returned when an operation is requested on an item that does not support the operation reword.  
+
<unprocessableEntity code="422" xmlns="http://docs.openstack.org/atlas/api/v1.1">
 +
  <message>The Object at the specified URI is unprocessable.</message>
 +
</unprocessableEntity>
 +
</nowiki></pre>
  
−
Example 3.11. Fault Response, unprocessableEntity
+
== API Operations ==
 +
This chapter explains specific API operations. For ideas relevant to all API operations, see the "General API Information" chapter.
  
−
<unprocessableEntity code="422" xmlns="http://docs.openstack.org/
+
=== Load Balancers ===
−
loadbalancers/api/v1.1">
+
==== List Load Balancers ====
−
<message>The Object at the specified URI is unprocessable.</
+
{| border="1" cellpadding="2" cellspacing="0"
−
message>
+
| Verb
−
</unprocessableEntity>
+
| URI
 +
| Description
 +
|-
 +
| GET
 +
| /loadbalancers  
 +
| List all load balancers configured for the account.  
 +
|}
  
−
10
+
'''Normal Response Code(s)''': 200
  
−
^l
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
−
Chapter 4. API Operations
 
  
−
This chapter explains specific API operations. For ideas relevant to all API operations, see the "GeneralAPI Information" chapter.  
+
This operation provides a list of all load balancers configured and associated with your account.
  
−
4.1. Load Balancers
+
To view deleted load balancers, add "?status=DELETED" to the end of the  GET URI. A deleted loadbalancer is immutable and irrecoverable.
−
4.1.1. List Load Balancers
 
−
Verb URI Description Representation
 
−
GET /loadbalancers List all load balancers configured for theaccount.  
 
−
XML, JSON
 
−
Normal Response Code(s): 200
 
  
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
+
This operation returns the following attributes for each load balancer:
−
badRequest (400), overLimit (413)
 
  
−
This operation provides a list of all load balancers configured and associated with your account.
+
* id
 +
* name
 +
* algorithm
 +
* protocol
 +
* port
 +
* status
 +
* created
 +
* updated
  
−
To view deleted load balancers, add "?status=DELETED" to the end of the get url. A deleted loadbalancer is immutable and irrecoverable. Only a limited set of attributes will be returned in the responseobject:
+
This operation does not require a request body.
  
−
• id
+
'''Example 4.1. List Load Balancers Response: XML '''
−
• name
 
−
• algorithm
 
−
• protocol
 
−
• port
 
−
• created
 
−
• updated
 
−
This operation does not require a request body.  
 
  
−
11
 
  
−
^l
+
<pre><nowiki>#!highlight xml numbers=disable
−
API Operations
+
<?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>
  
−
Example 4.1. List Load Balancers Response: XML
+
  <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>
 +
</nowiki></pre>
  
−
<?xml version=-"1.0" ?>
+
'''Example 4.2. List Load Balancers Response: JSON'''
−
<loadBalancers xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1">
 
  
−
<loadBalancer id="71" name="lb-site1" status="ACTIVE"
 
−
protocol="HTTP" port="80" algorithm="RANDOM">
 
−
<virtualIps>
 
  
−
<virtualIp id="403" address="206.55.130.1" ipVersion="IPV4"  
+
<pre><nowiki>#!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"
 +
        }
 +
      ]
 +
}
 +
</nowiki></pre>
  
−
type="PUBLIC" />
+
==== List Load Balancer Details ====
−
</virtualIps>
+
{| border="1" cellpadding="2" cellspacing="0"
−
<created time="2010-12-13T15:38:27-06:00" />
+
| Verb
−
<updated time="2010-12-13T15:38:38-06:00" />
+
| URI
 +
| Description
 +
|-
 +
| GET
 +
| /loadbalancers/''loadBalancerId''
 +
| List details of the specified load balancer.
 +
|}
  
−
</loadBalancer>
+
'''Normal Response Code(s)''': 200
  
−
<loadBalancer id="166" name="lb-site2" status="ACTIVE"
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
−
protocol="HTTP" port="80" algorithm="RANDOM">
 
−
<virtualIps>
 
  
−
<virtualIp id="401" address="206.55.130.2" ipVersion="IPV4"
+
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.
  
−
type="PUBLIC" />
+
This operation does not require a request body.
−
</virtualIps>
 
−
<created time="2010-12-13T15:38:27-06:00" />
 
−
<updated time="2010-12-13T15:38:38-06:00" />
 
  
−
</loadBalancer>
+
'''Example 4.3. List Load Balancer Details Response: XML'''
−
</loadBalancers>
 
  
−
12
 
  
−
^l
+
<pre><nowiki>#!highlight xml numbers=disable
−
API Operations
+
<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">
  
−
Example 4.2. List Load Balancers Response: JSON
+
  <virtualIps>
 +
    <virtualIp id="1000" address="2001:cdba:0000:0000:0000:0000:3257:9652" type="PUBLIC" ipVersion="IPV6" />
 +
  </virtualIps>
  
−
{
+
  <nodes>
−
"loadBalancers":[
+
    <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" />
 +
  </nodes>
  
−
{
+
  <sessionPersistence persistenceType="HTTP_COOKIE"/>
−
"name":"lb-site1",
 
−
"id":"71",
 
−
"protocol":"HTTP",
 
−
"port":"80",
 
−
"algorithm":"RANDOM",
 
−
"status":"ACTIVE",
 
−
"virtualIps":[
 
  
−
{
+
  <connectionThrottle maxRequestRate="50" rateInterval="60" />
−
"id":"403",
 
−
"address":"206.55.130.1",
 
−
"type":"PUBLIC",
 
−
"ipVersion":"IPV4"
 
  
−
}
+
</loadBalancer>
−
],
+
</nowiki></pre>
−
"created":{
 
  
−
"time":"2010-11-30T03:23:42Z"
+
'''Example 4.4. List Load Balancers Details Response: JSON'''
−
},
 
−
"updated":{
 
  
−
"time":"2010-11-30T03:23:44Z"
 
  
−
}
+
<pre><nowiki>#!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"
 +
                    }
 +
                  ],
  
−
"name":"lb-site2",  
+
      "nodes":     [
−
"id":"166",  
+
                      {
−
"protocol":"HTTP",  
+
                        "id": "1041",
−
"port":"80",  
+
                        "address":"10.1.1.1",
−
"algorithm":"RANDOM",  
+
                        "port": "80",
−
"status":"ACTIVE",  
+
                        "condition":"ENABLED",
−
"virtualIps":[
+
                        "status":"ONLINE"
 +
                      },
 +
                      {
 +
                        "id": "1411",
 +
                        "address":"10.1.1.2",
 +
                        "port": "80",
 +
                        "condition":"ENABLED",
 +
                        "status":"ONLINE"
 +
                      }
 +
                    ],
 +
      "sessionPersistence":{
 +
                              "persistenceType":"HTTP_COOKIE"
 +
                            },
 +
      "connectionThrottle":{
 +
                              "maxRequestRate": "50",
 +
                              "rateInterval": "60"
 +
                            }
 +
}
 +
</nowiki></pre>
  
−
{  
+
==== Create Load Balancer ====
−
"id":"401",
+
{| border="1" cellpadding="2" cellspacing="0"
−
"address":"206.55.130.2",
+
| Verb
−
"type":"PUBLIC",
+
| URI
−
"ipVersion":"IPV4"
+
| Description
 +
|-
 +
| POST
 +
| /loadbalancers
 +
| Create a new load balancer with the configuration defined by the request.  
 +
|}
  
−
}
+
'''Normal Response Code(s)''': 202
−
],
 
−
"created":{
 
  
−
"time":"2010-11-30T03:23:42Z"
+
'''Error Response Code(s)''': loadbalancerFault (500), serviceUnavailable (503), unauthorized (401),badRequest (400), overLimit (413)
−
},
 
−
"updated":{
 
  
−
"time":"2010-11-30T03:23:44Z"
+
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.
−
}
 
−
}
 
−
]
 
−
}
 
  
−
4.1.2. List Load Balancer Details
+
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.
−
Verb URI Description Representations
 
−
GET /loadbalancers/loadBalancerId List details of the specified load balancer. JSON, XML
 
−
Normal Response Code(s): 200
 
  
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
+
The caller of this operation must specify at least the following attributes of the load balancer:
−
badRequest (400), overLimit (413)
 
  
−
13
+
* name
 +
* At least one node
  
−
^l
+
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.
−
API Operations
 
  
−
This operation provides detailed output for a specific load balancer configured and associated with youraccount. This operation is not capable of returning details for a load balancer which has been deleted.
 
  
−
This operation does not require a request body.
+
<pre><nowiki>#!wiki caution
 +
Note
  
−
Example 4.3. List Load Balancer Details Request: XML
+
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.
 +
</nowiki></pre>
  
−
<loadBalancer xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1"
 
−
id="2000"
 
−
name="sample-loadbalancer"
 
−
protocol="HTTP"
 
−
port="80"
 
−
algorithm="ROUND_ROBIN"
 
−
status="ACTIVE">
 
−
<connectionLogging enabled="false" />
 
−
<virtualIps>
 
  
−
<virtualIp
+
<pre><nowiki>#!wiki caution
−
id="1000"
+
Note
−
address="206.10.10.210"
 
−
type="PUBLIC"
 
−
ipVersion="IPV4" />
 
  
−
</virtualIps>
+
A load balancer's name has a max length that can be queried when querying limits.
−
<nodes>  
+
</nowiki></pre>
  
−
<node
+
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.
−
nodeId="1041"
 
−
address="10.1.1.1"
 
−
port="80"
 
−
condition="ENABLED"
 
−
status="ONLINE" />
 
  
−
<node
 
−
nodeId="1411"
 
−
address="10.1.1.2"
 
−
port="80"
 
−
condition="ENABLED"
 
−
status="ONLINE" />
 
  
−
</nodes>
+
<pre><nowiki>#!wiki caution
−
<sessionPersistence persistenceType="HTTP_COOKIE"/>  
+
Note
−
<connectionThrottle
 
  
−
maxConnectionRate="50"
+
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:
  
−
rateInterval="60" />
+
<virtualIp type="PUBLIC" ipVersion="IPV6"/>
−
<cluster name="c1.dfw1" />
 
−
<created time="2010-11-30T03:23:42Z" />
 
−
<updated time="2010-11-30T03:23:44Z" />  
 
  
−
</loadBalancer>  
+
If the version attribute is not specified, then an IPv6 IP address is allocated by default.
 +
</nowiki></pre>
  
−
14
+
'''Example 4.5. Create Load Balancer (Required Attributes) Request: XML'''
  
−
^l
 
−
API Operations
 
  
−
Example 4.4. List Load Balancers Details Response: JSON
+
<pre><nowiki>#!highlight xml numbers=disable
 +
<loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1"
 +
              name="a-new-loadbalancer">
 +
      <nodes>
 +
      <node address="10.1.1.1" port="80" />
 +
      <node address="10.1.1.2" port="81" />
 +
    </nodes>
 +
</loadBalancer>
 +
</nowiki></pre>
  
−
{
+
'''Example 4.6. Create Load Balancer (Required Attributes) Request: JSON '''
  
−
"loadBalancer":{
 
−
"id": 2000,
 
−
"name":"sample-loadbalancer",
 
−
"protocol":"HTTP",
 
−
"port": 80,
 
−
"algorithm":"ROUND_ROBIN",
 
−
"status":"ACTIVE",
 
−
"connectionLogging":{
 
  
−
"enabled":"true"  
+
<pre><nowiki>#!highlight javascript numbers=disable
−
},
+
{
−
"virtualIps":[
+
    "name": "a-new-loadbalancer",
 +
    "nodes":      [
 +
                    {
 +
                      "address": "10.1.1.1",
 +
                      "port": "80"
 +
                    },
 +
                    {
 +
                      "address": "10.1.1.2",
 +
                      "port": "81"
 +
                    }
 +
                  ]
 +
}
 +
</nowiki></pre>
  
−
{
+
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.
−
"id": 1000,  
 
−
"address":"206.10.10.210",
 
−
"type":"PUBLIC",
 
−
"ipVersion":"IPV4"
 
  
−
}
 
−
],
 
−
"nodes":[
 
  
−
{
+
<pre><nowiki>#!wiki caution
−
"id": 1041,
+
Note
−
"address":"10.1.1.1",
 
−
"port": 80,
 
−
"condition":"ENABLED",
 
−
"status":"ONLINE"
 
  
−
},
+
Load balancers sharing a virtual IP must utilize a unique port.
 +
</nowiki></pre>
  
−
{
+
'''Example 4.7. Create Load Balancer (Required Attributes with Shared IP) Request: XML '''
−
"id": 1411,
 
−
"address":"10.1.1.2",
 
−
"port": 80,
 
−
"condition":"ENABLED",
 
−
"status":"ONLINE"
 
  
−
}
 
−
],
 
−
"sessionPersistence":{
 
  
−
"persistenceType":"HTTP_COOKIE"  
+
<pre><nowiki>#!hightlight xml
−
},
+
<loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1"
−
"connectionThrottle":{
+
              name="a-new-loadbalancer" port="83" protocol="HTTP">
 +
      <virtualIps>
 +
        <virtualIp id="39"/>
 +
      </virtualIps>
  
−
"maxRequestRate": 50,
+
      <nodes>
 +
        <node address="10.1.1.1" port="80" condition="ENABLED" />
 +
      </nodes>
 +
</loadBalancer>
 +
</nowiki></pre>
  
−
"rateInterval": 60
+
'''Example 4.8. Create Load Balancer (Required Attributes with Shared IP) Request: JSON '''
−
},
 
−
"cluster":{
 
  
−
"name":"c1.dfw1"
 
−
},
 
−
"created":{
 
  
−
"time":"2010-11-30T03:23:42Z"  
+
<pre><nowiki>#!highlight javascript numbers=disable
−
},
+
{
−
"updated":{
+
  "name":"a-new-loadbalancer",
−
 
+
  "port":"83",
−
"time":"2010-11-30T03:23:44Z"  
+
  "protocol":"HTTP",
 +
  "virtualIps": [
 +
                  {
 +
                      "id":"39"
 +
                  }
 +
                ],
 +
  "nodes":     [
 +
                  {
 +
                      "address":"10.1.1.1",
 +
                      "port":"80",
 +
                      "condition":"ENABLED"
 +
                  }
 +
                ]
 
}
 
}
−
}
+
</nowiki></pre>
−
}
 
  
−
15
+
''' Example 4.9. Create Load Balancer (Required Attributes with Shared IP) Response: XML '''
  
−
^l
 
−
API Operations
 
  
−
4.1.3. Create Load Balancer
+
<pre><nowiki>#!highlight xml numbers=disable
−
Verb URI Description Representation
+
<loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1"
−
POST /loadbalancers Create a new load balancer with the
+
              id="144" name="a-new-loadbalancer" algorithm="ROUND_ROBIN"
−
configuration defined by the request.
+
              protocol="HTTP"
−
XML, JSON
+
              port="83"
−
Normal Response Code(s): 202
+
              status="BUILD"
 +
              created="2011-02-08T21:19:55Z"
 +
              updated="2011-02-08T21:19:55Z" >
  
−
Error Response Code(s): loadbalancerFault ( 500), serviceUnavailable (503), unauthorized (401),
+
    <virtualIps>
−
badRequest (400), overLimit (413)
+
      <virtualIp id="39" address="3ffe:1900:4545:3:200:f8ff:fe21:67cf" ipVersion="IPV6" type="PUBLIC" />
 +
    </virtualIps>
  
−
This operation provisions a new load balancer based on the configuration defined in the request object.
+
    <nodes>
−
Once the request is validated and progress has started on the provisioning process, a response object willbe returned. The object will contain a unique identifier and status of the request.
+
      <node id="653" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" />
 +
    </nodes>
 +
</loadBalancer>
 +
</nowiki></pre>
  
−
If the status returned is set to "BUILD Using the identifier, the caller can check on the progress ofthe operation by performing a GET on loadbalancers/id. When the status of the loadBalancer
+
'''Example 4.10. Create Load Balancer (Required Attributes with Shared IP) Response: JSON '''
−
changes to "ACTIVE", then the loadbalancer has been successfully provisioned and is operational.  
 
  
−
The caller of this operation must specify at least the following attributes of the loadbalancer:
 
  
−
• name  
+
<pre><nowiki>#!highlight javascript numbers=disable
−
• protocol
+
{
−
• port
+
    "name": "a-new-loadbalancer",
−
• At least one [[VirtualIp]]
+
    "id": "144",
−
• At least one node
+
    "protocol": "HTTP",
−
If the request cannot be fulfilled due to insufficient or invalid data, an HTTP400 (Bad Request)
+
    "port": "83",
−
error response will be returned with information regarding the nature of the failure in the body of theresponse. Failures in the validation process are non-recoverable and require the caller to correct thecause of the failure and POST the request again.  
+
    "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"
 +
                    }
 +
                  ]
 +
}
 +
</nowiki></pre>
  
−
Note
+
==== Update Load Balancer Attributes ====
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Verb'''
 +
| '''URI'''
 +
| '''Description'''
 +
|-
 +
| PUT
 +
| /loadbalancers/''loadBalancerId''
 +
| Update the properties of a loadbalancer.
 +
|}
  
−
A load balancer's name has a max length that can be queried when querying limits.
+
'''Normal Response Code(s)''': 202
  
−
Note
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
−
Users may configure all documented features of the load balancer at creation time bysimply providing the additional elements or attributes in the request. This documentprovides an overview of all the features the load balancing service supports.  
+
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.
  
−
Example 4.5. Create Load Balancer (Required Attributes) Request: XML
+
This operation allows the caller to change one or more of the following attributes:
  
−
<loadBalancer xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1"
+
* name
−
name="a-new-loadbalancer"
+
* algorithm
−
port="80"
 
−
protocol="HTTP">
 
−
<virtualIps>
 
  
−
<virtualIp type="PUBLIC"/>
+
This operation does not return a response body.
−
</virtualIps>
 
−
<nodes>
 
  
−
<node address="10.1.1.1" port="80" condition="ENABLED"/>
 
−
</nodes>
 
−
</loadBalancer>
 
  
−
16
+
<pre><nowiki>#!wiki caution
 +
Note
  
−
^l
+
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.
−
API Operations
+
</nowiki></pre>
  
−
Example 4.6. Create Load Balancer (Required Attributes) Request: JSON
+
'''Example 4.11. Update Load Balancer Attributes Request: XML '''
  
−
{
 
  
−
"loadBalancer": {
+
<pre><nowiki>#!highlight xml numbers=disable
−
"name": "a-new-loadbalancer",
+
<loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1"
−
"port": "80",
+
              name="newname-loadbalancer" algorithm="LEAST_CONNECTIONS" />
−
"protocol": "HTTP",
+
</nowiki></pre>
−
"virtualIps": [
 
  
−
{
+
'''Example 4.12. Update Load Balancer Attributes Request: JSON '''
−
"type": "PUBLIC"
 
  
−
}
 
−
],
 
−
"nodes": [
 
  
−
{  
+
<pre><nowiki>#!highlight javascript numbers=disable
−
"address": "10.1.1.1",  
+
{
−
"port": "80",
+
  "name": "newname-loadbalancer",
−
"condition": "ENABLED"
+
  "algorithm": "LEAST_CONNECTIONS"
−
 
 
−
}
 
−
]
 
 
}
 
}
−
}
+
</nowiki></pre>
  
−
If you have at least one load balancer, you may create subsequent load balancers that share a singlevirtual IP by issuing a POST and supplying a virtual IP ID instead of a type. Additionally, this featureis highly desirable if you wish to load balance both an unsecured and secure protocol using one IP orDNS name. For example, this method makes it possible to use the same load balancing configuration tosupport HTTPand HTTPS).  
+
'''Table 4.1. Load Balancer Statuses'''
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Name'''
 +
|-
 +
| ACTIVE
 +
|-
 +
| BUILD
 +
|-
 +
| PENDING_UPDATE
 +
|-
 +
| PENDING_DELETE
 +
|-
 +
| DELETED
 +
|-
 +
| SUSPENDED
 +
|-
 +
| ERROR
 +
|}
  
−
Note  
+
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.
  
−
Load balancers sharing a virtual IP must utilize a unique port.  
+
==== Remove Load Balancer ====
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Verb'''
 +
| '''URI'''
 +
| '''Description'''
 +
|-
 +
| DELETE
 +
| /loadbalancers/''loadBalancerId''
 +
| Remove a load balancer from the account.  
 +
|}
  
−
Example 4.7. Create Load Balancer (Required Attributes with Shared IP)
+
'''Normal Response Code(s)''': 202
−
Request: XML
 
  
−
<loadBalancer xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1"
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
−
name="a-new-loadbalancer"
 
−
port="80"
 
−
protocol="HTTP">
 
−
<virtualIps>
 
  
−
<virtualIp id="39"/>
+
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.
−
</virtualIps>
 
−
<nodes>
 
  
−
<node address="10.1.1.1" port="80" condition="ENABLED" />
+
This operation does not require a request body.
−
</nodes>
 
−
</loadBalancer>
 
  
−
17
+
This operation does not return a response body.
  
−
^l
+
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.
−
API Operations
 
  
−
Example 4.8. Create Load Balancer (Required Attributes with Shared IP)
+
=== Nodes ===
−
Request: JSON
+
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.
  
−
"loadBalancer":{
+
The caller can assign the relevant weights to nodes using the weight attribute of the node element.
−
"name":"a-new-loadbalancer",
 
−
"port":"80",
 
−
"protocol":"HTTP",
 
−
"virtualIps":[
 
  
−
{
+
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".
−
"id":"39"
 
  
−
}
+
==== List Nodes ====
−
],
+
{| border="1" cellpadding="2" cellspacing="0"
−
"nodes":[
+
| '''Verb'''
 +
| '''URI'''
 +
| '''Description'''
 +
|-
 +
| GET
 +
| /loadbalancers/''loadBalancerId''/nodes  
 +
| List node(s) configured for the load balancer.
 +
|}
  
−
{
+
List all nodes of a load balancer.
−
"address":"10.1.1.1",
 
−
"port":"80",
 
−
"condition":"ENABLED"
 
  
−
}
+
'''Normal Response Code(s)''': 200
−
]
 
−
}
 
−
}
 
  
−
Example 4.9. Create Load Balancer (Required Attributes with Shared IP)
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
−
Response: XML
 
  
−
<loadBalancer xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1"
+
This operation does not require a request body.
−
id="144"
 
−
name="a-new-loadbalancer"
 
−
algorithm="ROUND_ROBIN"
 
−
protocol="HTTP"
 
−
port="83"
 
−
status="BUILD">
 
−
<virtualIps>
 
  
−
<virtualIp
+
'''Example 4.13. List Nodes Response: XML '''
−
id="39"
 
−
address="206.10.10.210"
 
−
ipVersion="IPV4"
 
−
type="PUBLIC" />
 
−
 
 
−
</virtualIps>
 
−
<nodes>
 
  
−
<node
 
−
id="653"
 
−
address="10.1.1.1"
 
−
port="80"
 
−
condition="ENABLED"
 
−
status="ONLINE" />
 
  
 +
<pre><nowiki>#!highlight xml numbers=disable
 +
<nodes>
 +
  <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" />
 
</nodes>
 
</nodes>
−
<cluster name="ztm-n03.staging1.lbaas.demo.net" />  
+
</nowiki></pre>
−
<created time="2011-02-08T21:19:55Z" />
 
−
<updated time="2011-02-08T21:19:55Z" />
 
−
<connectionLogging enabled="false" />
 
−
 
 
−
</loadBalancer>  
 
  
−
18
+
'''Example 4.14. List Node Response: JSON'''
  
−
^l
 
−
API Operations
 
−
 
−
Example 4.10. Create Load Balancer (Required Attributes with Shared IP)
 
−
Response: JSON
 
  
 +
<pre><nowiki>#!highlight javascript numbers=disable
 
{
 
{
−
 
+
  "nodes" : [
−
"loadBalancer": {
+
              {
−
"name": "a-new-loadbalancer",  
+
                "id":"410",
−
"id": 144,
+
                "address":"10.1.1.1",
−
"protocol": "HTTP",
+
                "port":"80",
−
"port": 83,
+
                "condition":"ENABLED",
−
"algorithm": "ROUND_ROBIN",
+
                "status":"ONLINE"
−
"status": "BUILD",  
+
              },
−
"cluster": {
+
              {
−
 
+
                "id":"236",
−
"name": "ztm-n01.staging1.lbaas.demo.net"
+
                "address":"10.1.1.2",
−
},
+
                "port":"80",
−
"nodes": [
+
                "condition":"ENABLED",
−
 
+
                "status":"ONLINE"
−
{
+
              },
−
"address": "10.1.1.1",  
+
              {
−
"id": 653,
+
                "id":"2815",
−
"port": 80,
+
                "address":"10.1.1.3",
−
"status": "ONLINE",  
+
                "port":"83",
−
"condition": "ENABLED"
+
                "condition":"DISABLED",
−
 
+
                "status":"OFFLINE"
−
}
+
              },
−
],
+
            ]
−
"virtualIps": [
 
−
 
 
−
{
 
−
"address": "206.10.10.210",  
 
−
"id": 39,  
 
−
"type": "PUBLIC",
 
−
"ipVersion": "IPV4"
 
−
 
 
 
}
 
}
−
],
+
</nowiki></pre>
−
"created": {
 
  
−
"time": "2011-04-13T14:18:07Z"
+
==== Retrieve a Node ====
−
},
+
{| border="1" cellpadding="2" cellspacing="0"
−
"updated": {
+
| '''Verb'''
 +
| '''URI'''
 +
| '''Description'''
 +
|-
 +
| GET
 +
| /loadbalancers/''loadBalancerId''/nodes/''nodeId''
 +
| Retrieve the configuration of node ''nodeid'' of loadbalancer ''loadbalancerId''.
 +
|}
  
−
"time": "2011-04-13T14:18:07Z"
+
This operation retrieves the configuration of a node.
−
},
 
−
"connectionLogging": {
 
  
−
"enabled": false
+
'''Normal Response Code(s)''': 200
−
}
 
−
}
 
−
}
 
  
−
4.1.4. Update Load Balancer Attributes
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
−
Verb URI Description Representation
 
−
PUT /loadbalancers/loadBalancerIdUpdate the properties of a loadbalancer.
 
−
XML, JSON
 
−
Normal Response Code(s): 202
 
  
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
+
This operation does not require a request body.
−
badRequest (400), overLimit (413)
 
  
−
This operation updates the attributes of the specified load balancer. Upon successful validation of therequest, the service will return a 202 (Accepted) response code. A caller should check that the loadbalancer status is ACTIVE to confirm that the update has taken effect. If the load balancer status is
+
'''Example 4.15. Retrieve the configuration of a node Response: XML '''
  
−
19
 
  
−
^l
+
<pre><nowiki>#!highlight xml numbers=disable
−
API Operations
+
<node id="236" address="10.1.1.2" port="80" condition="ENABLED" status="ONLINE" />
 +
</nowiki></pre>
  
−
"PENDING_UPDATE" then the caller can poll the load balancer with its ID (using a GET operation) towait for the changes to be applied and the load balancer to return to an ACTIVEstatus.
+
'''Example 4.16. Retrieve a node Response: JSON'''
  
−
This operation allows the caller to change one or more of the following attributes:
 
  
−
• name
+
<pre><nowiki>#!highlight javascript numbers=disable
−
• algorithm
+
{
−
This operation does not return a response body.
+
  "id":"236",
−
 
+
  "address":"10.1.1.2",
−
Note
+
  "port":"80",
−
 
+
  "condition":"ENABLED",
−
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.
+
  "status":"ONLINE"
−
 
 
−
Example 4.11. Update Load Balancer Attributes Request: XML
 
−
 
 
−
<loadBalancer xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1"  
 
−
name="sample-loadbalancer"
 
−
algorithm="ROUND_ROBIN" />
 
−
 
 
−
Example 4.12. Update Load Balancer Attributes Request: JSON
 
−
 
 
−
{"loadBalancer":{
 
−
"name": "sample-loadbalancer",  
 
−
"algorithm": "ROUND_ROBIN"  
 
 
}
 
}
 +
</nowiki></pre>
  
−
}  
+
==== Add Nodes ====
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Verb'''
 +
| '''URI'''
 +
| '''Description'''
 +
|-
 +
| POST
 +
| /loadbalancers/''loadBalancerId''/nodes
 +
| Add a new node to the load balancer.
 +
|}
  
−
Theload balancer's tatus 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
+
'''Normal Response Code(s)''': 202
−
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
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
−
Name Description
+
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.
−
ACTIVE Load balancer is configured properly and ready to serve traffic to incoming requests via theconfigured virtual IPs.
 
−
BUILD Load balancer is being provisioned for the first time and configuration is being applied to bringthe service online. The service will not yet be ready to serve incoming requests.
 
−
PENDING_UPDATE Load balancer is online but configuration changes are being applied to update the service basedon a previous request.
 
−
PENDING_DELETE Load balancer is online but configuration changes are being applied to begin deletion of theservice based on a previous request.
 
−
SUSPENDED Load balancer has been taken offline and disabled.
 
−
ERROR The system encountered an error when attempting to configure the load balancer.  
 
  
−
20
+
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.
  
−
^l
 
−
API Operations
 
  
−
Name
+
<pre><nowiki>#!wiki caution
 +
Note:
  
−
Description
+
When a node is added to a load balancer, it is enabled by default.
 +
</nowiki></pre>
  
−
DELETED Load balancers in DELETEDstatus can be displayed for a certain number of days after deletion.
+
'''Example 4.17. Add Nodes Request: XML'''
−
The number of days is queryable.  
 
  
−
4.1.5. Remove Load Balancer
 
−
Verb
 
  
−
URI
+
<pre><nowiki>#!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" />
 +
</nodes>
 +
</nowiki></pre>
  
−
Description
+
'''Example 4.18. Add Nodes Request: JSON'''
  
−
DELETE
 
  
−
/loadbalancers/loadBalancerId
+
<pre><nowiki>#!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"
 +
            }
 +
          ]
 +
}
 +
</nowiki></pre>
  
−
Remove a load balancer from the account.  
+
'''Example 4.19. Add Nodes Response: XML'''
  
−
Normal Response Code(s): 202
 
  
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
+
<pre><nowiki>#!highlight xml numbers=disable
−
badRequest (400), overLimit (413)
+
<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" />
 +
</nodes>
 +
</nowiki></pre>
  
−
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.  
+
'''Example 4.20. Add Nodes Response: JSON'''
  
−
This operation does not require a request body.
 
  
−
This operation does not return a response body.  
+
<pre><nowiki>#!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"
 +
            }
 +
          ]
 +
}
 +
</nowiki></pre>
  
−
4.2. Nodes
+
==== Modify 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
+
{| border="1" cellpadding="2" cellspacing="0"
−
an ONLINEstatus will receive and be able to service traffic from the load balancer.
+
| Verb
 +
| URI
 +
| Description
 +
|-
 +
| PUT
 +
| /loadbalancers/''loadBalancerId''/nodes/''nodeId''  
 +
| Modify the configuration of a node on the load balancer.  
 +
|}
  
−
The status of the node can be determined by passive or active health monitoring.
+
'''Normal Response Code(s)''': 202
  
−
The caller can assign the relevant weights to the node using the weight attribute of the node element.
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
−
The weight of a node determines the portion of requests it services compared to the other nodes of theload balancer. For exampl, 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 attribure is notspecified, then the node's weight is implicitly set to "1".
 
  
−
4.2.1. List Nodes
+
This operation does not return a response body.
−
Verb URI Description
 
−
GET /loadbalancers/loadBalancerId/nodes List node(s) configured for the load balancer.
 
−
GET /loadbalancers/loadBalancerId/nodes/nodeId
 
−
List details of a specific node.  
 
  
−
Normal Response Code(s): 200
 
  
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
+
<pre><nowiki>#!wiki caution
−
badRequest (400), overLimit (413)
+
Note
−
This operation does not require a request body.
 
  
−
21
+
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.
 +
</nowiki></pre>
  
−
^l
+
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.
−
API Operations
 
  
−
Example 4.13. List Node Response: XML  
+
'''Example 4.21. Disable a node Request: XML'''
  
−
<node
 
−
id="410"
 
−
address="10.1.1.1"
 
−
port="80"
 
−
condition="ENABLED"
 
−
status="ONLINE" />
 
  
−
Example 4.14. List Node Response: JSON
+
<pre><nowiki>#!highlight xml numbers=disable
 +
<node condition="DISABLED" />
 +
</nowiki></pre>
  
−
{"node": {
+
'''Example 4.22. Disable a node Request: JSON'''
−
"id":"410",
 
−
"address":"10.1.1.1",
 
−
"port":80,
 
−
"condition":"ENABLED",
 
−
"status":"ONLINE"
 
  
−
}
 
−
}
 
  
−
Example 4.15. List Nodes Response: XML
+
<pre><nowiki>#!highlight javascript numbers=disable
 +
{
 +
  "condition": "DISABLED"
 +
}
 +
</nowiki></pre>
  
−
<?xml version=-"1.0" encoding=-"UTF-8" standalone=-"yes"?>
+
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.
  
−
<nodes xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1">
+
==== Remove Nodes ====
−
<node
+
{| border="1" cellpadding="2" cellspacing="0"
−
id="650"
+
| '''Verb'''
−
address="10.1.1.1"
+
| '''URI'''
−
port="80"
+
| '''Description'''
−
condition="ENABLED"
+
|-
−
status="ONLINE"/>
+
| DELETE
−
<node
+
| /loadbalancers/''loadBalancerId''/nodes/''nodeId''
−
id="183"  
+
| Remove a node from the load balancer.
−
address="10.2.2.1"  
+
|}
−
port="80"  
 
−
condition="ENABLED"
 
−
status="ONLINE"/>
 
−
<node
 
−
id="184"
 
−
address="10.2.2.2"
 
−
port="88"
 
−
condition="ENABLED"
 
−
status="ONLINE"/>
 
  
−
</nodes>
+
'''Normal Response Code(s)''': 200, 202
  
−
22
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
−
^l
+
This operation does not require a request body.
−
API Operations
 
  
−
Example 4.16. List Nodes Response: JSON
+
This operation does not return a response body.
  
−
{
 
−
"nodes": [
 
  
−
{
+
<pre><nowiki>#!wiki caution
−
"address": "10.1.1.1",
+
Note
−
"id": 650,
 
−
"port": 80,
 
−
"status": "ONLINE",
 
−
"condition": "ENABLED"
 
  
−
},
+
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.
 +
</nowiki></pre>
  
−
{
+
=== Virtual IPs ===
−
"address": "10.2.2.1",  
+
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.
−
"id": 183,  
 
−
"port": 80,  
 
−
"status": "ONLINE",
 
−
"condition": "ENABLED"
 
  
−
},
+
'''Table 4.3. Virtual IP Types'''
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Name'''
 +
|-
 +
| PUBLIC
 +
|-
 +
| INTERNAL
 +
|}
  
−
{  
+
==== List Virtual IPs ====
−
"address": "10.2.2.2",
+
{| border="1" cellpadding="2" cellspacing="0"
−
"id": 184,
+
| '''Verb'''
−
"port": 88,
+
| '''URI'''
−
"status": "ONLINE",
+
| '''Description'''
−
"condition": "ENABLED"
+
|-
 +
| GET
 +
| /loadbalancers/''loadBalancerId''/virtualips
 +
| List all virtual IPs associated with a load balancer.
 +
|}
  
−
}
+
'''Normal Response Code(s): 200'''
−
]
 
−
}
 
  
−
4.2.2. Add Nodes
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
−
Verb
 
  
−
URI
+
This operation lists all the virtual IP addresses of a load balancer.
  
−
Description
+
This request does not require a request body.
  
−
POST
 
  
−
/loadbalancers/loadBalancerId/nodes
+
<pre><nowiki>#!wiki caution
 +
Note
  
−
Add a new node to the 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.
 +
</nowiki></pre>
  
−
Normal Response Code(s): 202
+
'''Example 4.23. List Virtual IPs Response: XML'''
  
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
 
−
badRequest (400), overLimit (413)
 
  
−
This operation does not require a request body.  
+
<pre><nowiki>#!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>
 +
</nowiki></pre>
  
−
When a node is added, it is assigned a unique identifier that can be used for mutating operations suchas changing the condition or removing it. Every load balancer is dual-homed on both the public Internetand internal; as a result, nodes can either be internal private addresses or addresses on the publicInternet.  
+
'''Example 4.24. List Virtual IPs Response: JSON'''
  
−
Example 4.17. Add Nodes Request: XML
 
  
−
<nodes xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1">
+
<pre><nowiki>#!highlight javascript numbers=disable
−
<node address="10.1.1.1" port="80" condition="ENABLED" />
+
{
−
<node address="10.2.2.1" port="80" condition="ENABLED" />
+
  "virtualIps": [
−
<node address="10.2.2.2" port="88" condition="ENABLED" />  
+
                {
 +
                  "id": "1021",
 +
                  "address": "206.10.10.210",
 +
                  "type": "PUBLIC",
 +
                  "ipVersion": "IPV4"
 +
                }
 +
                ]
 +
}
 +
</nowiki></pre>
  
−
</nodes>
+
=== Usage Reports ===
 +
==== List Usage ====
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Name'''
 +
| '''URI'''
 +
| '''Description'''
 +
|-
 +
| GET
 +
| /loadbalancers/''loadBalancerId''/usage
 +
| List current and historical usage.
 +
|}
  
−
23
+
'''Normal Response Code(s): 200'''
  
−
^l
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
−
API Operations
 
  
−
Example 4.18. Add Nodes Request: JSON
+
This operation does not require a request body.
  
−
{"nodes": [
+
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'''
−
"address": "10.1.1.1",
 
−
"port": 80,
 
−
"condition": "ENABLED"
 
  
−
},
 
  
−
{
+
<pre><nowiki>#!highlight xml numbers=disable
−
"address": "10.2.2.1",
+
<loadBalancerUsageRecords xmlns="http://docs.openstack.org/atlas/api/v1.1">
−
"port": 80,
+
  <loadBalancerUsageRecord  id="394" transferBytesIn="2819204"
−
"condition": "ENABLED"
+
                            transferBytesOut="84923069" />
 +
  <loadBalancerUsageRecord  id="473" transferBytesIn="0" transferBytesOut="0" />
 +
</loadBalancerUsageRecords>
 +
</nowiki></pre>
  
−
},
+
'''Example 4.26. Report Load Balancer Usage Response: JSON'''
  
−
{
 
−
"address": "10.2.2.2",
 
−
"port": 88,
 
−
"condition": "ENABLED",
 
−
"weight": 10
 
  
−
}
+
<pre><nowiki>#!highlight javascript numbers=disable
−
]
+
{
−
}  
+
  "loadBalancerUsageRecords": [
 +
                                {
 +
                                  "id": "394",
 +
                                  "transferBytesIn": "2819204",
 +
                                  "transferBytesOut": "84923069"
 +
                                },
 +
                                {
 +
                                  "id": "473",
 +
                                  "transferBytesIn": "0",
 +
                                  "transferBytesOut": "0"
 +
                                }
 +
                              ]
 +
}
 +
</nowiki></pre>
  
−
Example 4.19. Add Nodes Response: XML
+
=== Monitors ===
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Verb'''
 +
| '''URI'''
 +
| '''Description'''
 +
|-
 +
| GET
 +
| /loadbalancers/''loadBalancerId''/healthmonitor
 +
| Retrieve the health monitor configuration, if one exists.  
 +
|-
 +
| PUT
 +
| /loadbalancers/''loadBalancerId''/healthmonitor
 +
| Update the settings for a health monitor.  
 +
|-
 +
| DELETE
 +
| /loadbalancers/loadBalancerId/healthmonitor
 +
| Remove the health monitor.
 +
|}
  
−
<nodes xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1">
+
'''Normal Response Code(s)''': 200, 202
  
−
<node
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
−
address="10.2.2.3"
 
−
id="185"
 
−
port="80"
 
−
condition="ENABLED"
 
−
status="ONLINE" />
 
  
−
<node
+
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.
−
address="10.2.2.4"
 
−
id="186"
 
−
port="80"
 
−
condition="ENABLED"
 
−
status="ONLINE" />
 
  
−
</nodes>
+
Active health monitoring provides 3 types of health monitors. The caller can configure one health monitor on the load blancer.
  
−
24
+
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.
  
−
^l
+
'''Table 4.4. Health Monitor Types'''
−
API Operations
+
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Name'''
 +
|-
 +
| CONNECT
 +
|-
 +
| HTTP
 +
|-
 +
| HTTPS
 +
|}
  
−
Example 4.20. Add Nodes Response: JSON
+
===== Monitor CONNECT =====
 +
The monitor connects to each node on its defined port to ensure that the node is listening properly.
  
−
{"nodes": [
+
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.
−
"address": "10.2.2.3",
+
* '''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.
−
"id": 185,
+
* '''attemptsBeforeDeactivation''': Number of permissible monitor failures before removing a node from rotation. Must be a number between 1 and 10.
−
"port": 80,
 
−
"status": "ONLINE",
 
−
"condition": "ENABLED"
 
  
−
},
+
'''Example 4.27. Monitor CONNECT Request: XML'''
  
−
{
 
−
"address": "10.2.2.4",
 
−
"id": 186,
 
−
"port": 80,
 
−
"status": "ONLINE",
 
−
"condition": "ENABLED"
 
  
−
}
+
<pre><nowiki>#!highlight xml numbers=disable
−
]
+
<healthMonitor xmlns="http://docs.openstack.org/atlas/api/v1.1"
−
}
+
              type="CONNECT" delay="20" timeout="10"
 +
              attemptsBeforeDeactivation="3" />
 +
</nowiki></pre>
  
−
4.2.3. Modify Nodes
+
'''Example 4.28. Monitor CONNECT Request: JSON'''
−
Verb
 
  
−
URI
 
  
−
Description
+
<pre><nowiki>#!highlight javascript numbers=disable
−
PUT
+
{
 +
  "type": "CONNECT",
 +
  "delay": "20",
 +
  "timeout": "10",
 +
  "attemptsBeforeDeactivation": "3"
 +
}
 +
</nowiki></pre>
  
−
/loadbalancers/loadBalancerId/nodes/nodeId
+
'''Example 4.29. Monitor Connections Response: XML'''
  
−
Modify the configuration of a node on the loadbalancer.
 
  
−
Normal Response Code(s): 202
+
<pre><nowiki>#!highlight xml numbers=disable
 +
<healthMonitor xmlns="http://docs.openstack.org/atlas/api/v1.1"
 +
              type="CONNECT" delay="10" timeout="10"
 +
              attemptsBeforeDeactivation="3" />
 +
</nowiki></pre>
  
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
+
'''Example 4.30. Monitor Connections Response: JSON'''
−
badRequest (400), overLimit (413)
 
  
−
This operation does not require a request body.
 
  
−
Note
+
<pre><nowiki>#!highlight javascript numbers=disable
−
 
+
{
−
The node's IP and port are immutable attributes and cannot be modified with a PUT
+
  "type": "CONNECT",
−
request. Supplying an unsupported attribute will result in a 400 (badRequest) fault. Aload balancer supports a maximum number of nodes. The maximum number of nodes perloadbalancer is a queryable limit.
+
  "delay": "20",
−
 
+
  "timeout": "10",
−
Every node in the load balancer has an associated condition which determines its role within the loadbalancer.
+
  "attemptsBeforeDeactivation": "3"
−
 
 
−
Table 4.2. Load Balancer Node Conditions
 
−
 
 
−
Name Description
 
−
ENABLED Node is permitted to accept new connections. Its status will eventually become ONLINE toreflect this configuration.
 
−
DISABLED Node is not permitted to accept any new connections regardless of session persistenceconfiguration. Existing connections are forcibly terminated. The node's status will change toOFFLINE once the configuration has been successfully appplied.
 
−
 
 
−
Example 4.21. Update Node Condition Request: XML
 
−
 
 
−
<node condition="ENABLED" />
 
−
 
 
−
25
 
−
 
 
−
^l
 
−
API Operations
 
−
 
 
−
Example 4.22. Update Node Condition Request: JSON
 
−
 
 
−
{"node":{
 
−
"condition": "ENABLED"  
 
 
}
 
}
−
}
+
</nowiki></pre>
  
−
4.2.4. Remove Nodes
+
===== Monitor HTTP and HTTPS =====
−
Verb
+
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.
  
−
URI
+
* '''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.
  
−
Description
+
'''Example 4.31. Monitor HTTP Response: XML'''
  
−
DELETE
 
  
−
/loadbalancers/loadBalancerId/nodes/nodeId
+
<pre><nowiki>#!highlight xml numbers=disable
 +
<healthMonitor xmlns="http://docs.openstack.org/atlas/api/v1.1"
 +
              type="HTTP" delay="10" timeout="3" attemptsBeforeDeactivation="2"
 +
              path="/"
 +
/>
 +
</nowiki></pre>
  
−
Remove a node from the load balancer.  
+
'''Example 4.32. Monitor HTTPS Response: XML'''
  
−
Normal Response Code(s): 200, 202
 
  
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
+
<pre><nowiki>#!highlight xml numbers=disable
−
badRequest (400), overLimit (413)
+
<healthMonitor xmlns="http://docs.openstack.org/atlas/api/v1.1"
 +
              type="HTTPS" delay="10" timeout="3"
 +
              attemptsBeforeDeactivation="3"
 +
              path="/healthcheck"
 +
/>
 +
</nowiki></pre>
  
−
This operation does not require a request body.  
+
'''Example 4.33. Monitor HTTPS Response: JSON'''
  
−
4.3. Virtual IPs
 
−
A virtual IP (VIP) makes a load balancer accessible by clients. The load balancing service supportseither a public VIP, routable on the public Internet, or a private address, routable only within the regionin which the load balancer resides.
 
  
−
Table 4.3. Virtual IP Types
+
<pre><nowiki>#!highlight javascript numbers=disable
 +
{
 +
  "type": "HTTPS",
 +
  "delay": "10",
 +
  "timeout": "3",
 +
  "attemptsBeforeDeactivation": "3",
 +
  "path": "/healthcheck"
 +
}
 +
</nowiki></pre>
  
−
Name Description
+
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.
−
PUBLIC An address that is routable on the public Internet.
 
−
INTERNAL An address that is routable only on internal network.  
 
  
−
4.3.1. List Virtual IPs
+
=== Sessions ===
−
Verb
+
==== Manage Session Persistence ====
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Verb'''
 +
| '''URI'''
 +
| '''Description'''
 +
|-
 +
| GET
 +
| /loadbalancers/''loadBalancerId''/sessionpersistence
 +
| List session persistence configuration.  
 +
|-
 +
| PUT
 +
| /loadbalancers/''loadBalancerId''/sessionpersistence
 +
| Enable session persistence.  
 +
|-
 +
| DELETE
 +
| /loadbalancers/''loadBalancerId''/sessionpersistence
 +
| Disable session persistence.  
 +
|}
  
−
URI
+
'''Normal Response Code(s)''': 200, 202
  
−
Description
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
−
GET
+
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.
  
−
/loadbalancers/loadBalancerId/virtualips
+
'''Table 4.5. Session Persistence Modes'''
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Name'''
 +
|-
 +
| HTTP_COOKIE
 +
|}
  
−
List all virtual IPs associated with a load balancer.
+
'''Example 4.34. List Session Persistence Configuration Response: XML'''
  
−
Normal Response Code(s): 200, 202
 
  
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
+
<pre><nowiki>#!highlight xml numbers=disable
−
badRequest (400), overLimit (413)
+
<sessionPersistence xmlns="http://docs.openstack.org/atlas/api/v1.1"
−
This request does not require a request body.
+
                    persistenceType="HTTP_COOKIE" />
 +
</nowiki></pre>
  
−
Note
+
'''Example 4.35. List Session Persistence Configuration Response: JSON'''
  
−
The number of VIPs that can be configured when creating a load balancer is a queryablelimit.
 
  
−
26
+
<pre><nowiki>#!highlight javascript numbers=disable
 +
{
 +
  "persistenceType":"HTTP_COOKIE"
 +
}
 +
</nowiki></pre>
  
−
^l
+
'''Example 4.36. Set Session Persistence Type Request: XML'''
−
API Operations
 
  
−
Example 4.23. List Virtual IPs Response: XML
 
  
−
<virtualIps xmlns="http:/-/docs.openstack.org/
+
<pre><nowiki>#!highlight xml numbers=disable
−
loadbalancers/api/v1.1">
+
<sessionPersistence xmlns="http://docs.openstack.org/atlas/api/v1.1"
 +
                    persistenceType="HTTP_COOKIE" />
 +
</nowiki></pre>
  
−
<virtualIp
+
'''Example 4.37. Set Session Persistence Type Request: JSON'''
−
id="1000"
 
−
address="206.10.10.210"
 
−
type="PUBLIC"/>
 
  
−
</virtualIps>
 
  
−
Example 4.24. List Virtual IPs Response: JSON
+
<pre><nowiki>#!highlight javascript numbers=disable
−
 
 
−
{"virtualIps": [
 
 
{
 
{
−
"id": "1000",
+
    "persistenceType":"HTTP_COOKIE"
−
"address": "206.10.10.210",
 
−
"type": "PUBLIC"  
 
 
}
 
}
 +
</nowiki></pre>
  
−
]
+
=== Connections ===
−
}  
+
==== Throttle Connections ====
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Verb'''
 +
| '''URI'''
 +
| '''Description'''
 +
|-
 +
| GET
 +
| /loadbalancers/''loadBalancerId''/connectionthrottle
 +
| List connection throttling configuration.
 +
|-
 +
| PUT
 +
| /loadbalancers/''loadBalancerId''/connectionthrottle
 +
| Update throttling configuration.
 +
|-
 +
| DELETE
 +
| /loadbalancers/''loadBalancerId''/connectionthrottle
 +
| Remove connection throttling configurations.
 +
|}
  
−
4.4. Usage Reports
+
'''Normal Response Code(s)''': 200, 202
−
4.4.1. List Usage
 
−
Name
 
  
−
URI
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
−
Description
+
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.
  
−
GET
+
* '''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.
  
−
/loadbalancers/loadBalancerId/usage
 
  
−
List current and historical usage.
+
<pre><nowiki>#!wiki caution
 +
Note
  
−
Normal Response Code(s): 200
+
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.
 +
</nowiki></pre>
  
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
+
'''Example 4.42. List Connection Throttling Configuration Response: XML'''
−
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 thetransferBytesIn and transferBytesOut usage counters that represent respectively the amount of traffic inbytes received by the load balancer from clients requests, and the amount fo traffic sent from the loadbalancer as responses to clients.  
+
<pre><nowiki>#!highlight xml numbers=disable
 +
<connectionThrottle xmlns="http://docs.openstack.org/atlas/api/v1.1"
 +
                    maxRequestRate="50" rateInterval="60" />
 +
</nowiki></pre>
  
−
Example 4.25. Report Load Balancer Usage Response: XML
+
'''Example 4.43. List Connection Throttling Configuration Response: JSON'''
  
−
<loadBalancerUsage xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1">
 
  
−
<loadBalancerUsageRecord
+
<pre><nowiki>#!highlight javascript numbers=disable
−
id="394"
+
{
−
transferBytesIn="0"
+
    "maxRequestRate": "50",
−
transferBytesOut="0" />
+
    "rateInterval": "60"
−
 
 
−
<loadBalancerUsageRecord
 
−
id="473"
 
−
transferBytesIn="0"
 
−
transferBytesOut="0" />  
 
−
 
 
−
</loadBalancerUsage>  
 
−
 
 
−
27
 
−
 
 
−
^l
 
−
API Operations
 
−
 
 
−
Example 4.26. Report Load Balancer Usage Response: JSON
 
−
 
 
−
{
 
−
"loadBalancerUsageRecords": [
 
−
 
 
−
{
 
−
"id": "394",
 
−
"transferBytesIn": "0",
 
−
"transferBytesOut": "0"
 
−
 
 
−
},
 
−
 
 
−
{
 
−
"id": "473",
 
−
"transferBytesIn": "0",
 
−
"transferBytesOut": "0"
 
−
 
 
−
}
 
−
]
 
−
}
 
−
 
 
−
4.5. Monitors
 
−
In addition to the default passive monitoring, the load balancing service includes an active healthmonitoring operation which periodically checks your back-end nodes to ensure they are respondingcorrectly.
 
−
 
 
−
Active health monitoring provides 3 types of health monitors. The caller can configure one healthmonitor on the load blancer.
 
−
 
 
−
The health monitor has a typeattribute to signify what kind of monitor it is. This specification supports3 types of health monitor.
 
−
 
 
−
Table 4.4. Health Monitor Types
 
−
 
 
−
Name Description
 
−
CONNECT Health monitor is a CONNECT monitor.
 
−
HTTP Health monitor is an HTTP monitor.
 
−
HTTPS Health monitor is an HTTPS monitor.
 
−
 
 
−
4.5.1. Monitor Health
 
−
Verb URI Description
 
−
GET /loadbalancers/loadBalancerId/healthmonitor Retrieve the health monitor configuration, if oneexists.
 
−
PUT /loadbalancers/loadBalancerId/healthmonitor Update the settings for a health monitor.
 
−
DELETE /loadbalancers/loadBalancerId/healthmonitor Remove the health monitor.
 
−
 
 
−
Normal Response Code(s): 200, 202
 
−
 
 
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
 
−
badRequest (400), overLimit (413)
 
−
 
 
−
4.5.1.1. Monitor CONNECT
 
−
The monitor connects to each node on its defined port to ensure that the service is listening properly.
 
−
The CONNECT monitor is the most basic type of health check and does no post-processing or protocolspecific health checks. It includes several configurable properties:
 
−
 
 
−
28
 
−
 
 
−
^l
 
−
API Operations
 
−
 
 
−
•
 
−
delay: This is the minimum time between calls to a monitor.
 
−
•
 
−
timeout: Maximum number of seconds to wait for a connection to be established before timing out.
 
−
The value must be less than the delay value.
 
−
•
 
−
attemptsBeforeDeactivation: Number of permissible monitor failures before removing anode from rotation. (Must be a number between 1 and 10)
 
−
Example 4.27. Monitor Connections Request: XML
 
−
 
 
−
<healthMonitor xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1"
 
−
type="CONNECT"
 
−
delay="20"
 
−
timeout="10"
 
−
attemptsBeforeDeactivation="3" />
 
−
 
 
−
Example 4.28. Monitor Connections Request: JSON
 
−
 
 
−
{"healthMonitor": {
 
−
"type": "CONNECT",
 
−
"delay": 20,
 
−
"timeout": 10,
 
−
"attemptsBeforeDeactivation": 3
 
−
 
 
−
}
 
−
}
 
−
 
 
−
Example 4.29. Monitor Connections Response: XML
 
−
 
 
−
<healthMonitor xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1"
 
−
type="CONNECT"
 
−
delay="10"
 
−
timeout="10"
 
−
attemptsBeforeDeactivation="3" />
 
−
 
 
−
Example 4.30. Monitor Connections Response: JSON
 
−
 
 
−
{"healthMonitor": {
 
−
"type": "CONNECT",  
 
−
"delay": 20,
 
−
"timeout": 10,
 
−
"attemptsBeforeDeactivation": 3
 
−
 
 
−
}
 
−
}
 
−
 
 
−
4.5.1.2. Monitor HTTP and HTTPS
 
−
The HTTP and HTTPS monitor is more intelligent than the connect monitor. It is capable of processingan HTTP or HTTPS response to determine the condition of a node. It supports the same basic propertiesas the CONNECT monitor and includes additional attributes of path that is used to evaluate the HTTP
 
−
response.
 
−
 
 
−
•
 
−
path: The HTTP path used in the request by the monitor. This must be a string beginning with a /
 
−
(forward slash). The monitor expects a response from teh node with an HTTP status code of 200.
 
−
29
 
−
 
 
−
^l
 
−
API Operations
 
−
 
 
−
Example 4.31. Monitor HTTP Response: XML
 
−
 
 
−
<healthMonitor xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1"
 
−
type="HTTP"
 
−
delay="10"
 
−
timeout="3"
 
−
attemptsBeforeDeactivation="2"
 
−
path="/-"
 
−
 
 
−
/>
 
−
 
 
−
Example 4.32. Monitor HTTPS Response: XML
 
−
 
 
−
<healthMonitor xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1"
 
−
type="HTTPS"
 
−
delay="10"
 
−
timeout="3"
 
−
attemptsBeforeDeactivation="2"
 
−
path="/-"
 
−
 
 
−
/>
 
−
 
 
−
4.6. Sessions
 
−
4.6.1. Manage Session Persistence
 
−
Session persistence is a feature of the load balancing service which forces multiple requests from clientsto be directed to the same node. This is common with many web applications that do not inherentlyshare application state between back-end servers.
 
−
 
 
−
Table 4.5. Session Persistence Modes
 
−
 
 
−
Name
 
−
 
 
−
Description
 
−
 
 
−
HTTP_COOKIE A session persistence mechanism that inserts an HTTP cookie and is used to determine thedestination back-end node. This is supported for HTTP load balancing only.
 
−
 
 
−
Verb URI Description
 
−
GET /loadbalancers/loadBalancerId/
 
−
sessionpersistence
 
−
List session persistence configuration.
 
−
PUT /loadbalancers/loadBalancerId/
 
−
sessionpersistence
 
−
Enable session persistence.
 
−
DELETE /loadbalancers/loadBalancerId/
 
−
sessionpersistence
 
−
Disable session persistence.
 
−
 
 
−
Normal Response Code(s): 200, 202
 
−
 
 
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
 
−
badRequest (400), overLimit (413)
 
−
 
 
−
Example 4.33. List Session Persistence Configuration Response: XML
 
−
 
 
−
<sessionPersistence xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1" persistenceType="HTTP_COOKIE"/>
 
−
 
 
−
30
 
−
 
 
−
^l
 
−
API Operations
 
−
 
 
−
Example 4.34. List Session Persistence Configuration Response: JSON
 
−
 
 
−
{
 
−
"sessionPersistence":{
 
−
"persistenceType":"HTTP_COOKIE"  
 
 
}
 
}
−
}
+
</nowiki></pre>
  
−
Example 4.35. Set Session Persistence Type Request: XML  
+
'''Example 4.44. Update Connection Throttling Configuration Request: XML'''
  
−
<sessionPersistence xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1" persistenceType="HTTP_COOKIE"/>
 
  
−
Example 4.36. Set Session Persistence Type Request: JSON
+
<pre><nowiki>#!highlight xml numbers=disable
 +
<connectionThrottle xmlns="http://docs.openstack.org/atlas/api/v1.1"
 +
                    maxRequestRate="40" />
 +
</nowiki></pre>
  
−
{
+
'''Example 4.45. Update Connection Throttling Configuration Request: JSON'''
−
"sessionPersistence":{
 
−
"persistenceType":"HTTP_COOKIE"
 
−
}
 
−
}
 
  
−
4.7. Connections
 
−
4.7.1. Log Connections
 
−
Verb URI Description
 
−
GET /loadbalancers/loadBalancerId/connectionlogging View current configuration of connection logging.
 
−
PUT /loadbalancers/loadBalancerId/connectionlogging Enable or disable connection logging.
 
  
−
Normal Response Code(s): 200, 202
+
<pre><nowiki>#!highlight javascript numbers=disable
−
 
+
{
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
+
  "maxRequestRate": "40"
−
badRequest (400), overLimit (413)
 
−
This operation allows the user to view the current connection logging configuration, enable connection
 
−
 
 
−
logging, or disable connection logging.
 
−
This operation does not require a request body.
 
−
The service provider is responsible for providing an out-of-brand method for users of the service to
 
−
 
 
−
retrieve the access and connection logs of their load balancers.
 
−
 
 
−
Example 4.37. List Connection Logging Configuration Response: XML
 
−
 
 
−
<connectionLogging xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1" enabled="true"/>
 
−
 
 
−
31
 
−
 
 
−
^l
 
−
API Operations
 
−
 
 
−
Example 4.38. List Connection Logging Configuration Response: JSON
 
−
 
 
−
{
 
−
"connectionLogging": {
 
−
"enabled": "true"  
 
 
}
 
}
−
}
+
</nowiki></pre>
  
−
Example 4.39. Enable Connection Logging Request: XML
+
=== Protocols ===
 +
==== List Load Balancing Protocols ====
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Verb'''
 +
| '''URI'''
 +
| '''Description'''
 +
|-
 +
| GET
 +
| /protocols
 +
| List all supported load balancing protocols.  
 +
|}
  
−
<connectionLogging xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1" enabled="true"/>
+
'''Normal Response Code(s)''': 200
  
−
Example 4.40. Enable Connection Logging Request: JSON
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
−
{
+
This operation does not require a request body.
−
"connectionLogging":{
 
−
"enabled":"true"
 
−
}
 
−
}
 
  
−
4.7.2. Throttle Connections
+
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.
−
Verb URI Description
 
−
GET /loadbalancers/loadBalancerId/
 
−
connectionthrottle
 
−
List connection throttling configuration.
 
−
PUT /loadbalancers/loadBalancerId/
 
−
connectionthrottle
 
−
Update throttling configuration.
 
−
DELETE /loadbalancers/loadBalancerId/
 
−
connectionthrottle
 
−
Remove connection throttlingconfigurations.  
 
  
−
Normal Response Code(s): 200, 202
+
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.
  
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
+
'''Example 4.46. List Load Balancing Protocols Response: XML'''
−
badRequest (400), overLimit (413)
 
  
−
This operation does not require a request body.
 
  
−
The connection throttling feature imposes limits on the number of connections per IP address to helpmitigate malicious or abusive traffic to your applications. The following properties can be configuredbased on the traffic patterns for your sites.  
+
<pre><nowiki>#!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="*" />
 +
</protocols>
 +
</nowiki></pre>
  
−
Note
+
'''Example 4.47. List Load Balancing Protocols Response: JSON'''
  
−
Whent the rate is exceeded, the load balancer returns a serviceUnavailable (503) for HTTP/
 
−
HTTPS loadbalancers and refuses connections for TCP loadbalancers.
 
  
−
•
+
<pre><nowiki>#!highlight javascript numbers=disable
−
maxRequestRate: Maximum number of requests allowed from a single IP address in the definedrateInterval. Setting a value of 0 allows an unlimited connection rate.
+
{
−
•
+
  "protocols": [
−
rateInterval: Frequency (in seconds) at which the maxRequestRateis assessed. For
+
              {
−
example, a maxRequestRateof 30 with a rateIntervalof 60 would allow a maximum of 30
+
                "name": "HTTP",
−
connections per minute for a single IP address. This value must be specified between 1 and 3600.
+
                "port": "80"
−
32
+
              },
−
 
+
              {
−
^l
+
                "name": "HTTPS",
−
API Operations
+
                "port": "443"
−
 
+
              },
−
Example 4.41. List Connection Throttling Configuration Response: XML
+
              {
−
 
+
                "name": "TCP",
−
<connectionThrottle xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1"
+
                "port": "*"
−
maxRequestRate="50"
+
              }
−
rateInterval="60" />  
+
              ]
−
 
 
−
Example 4.42. List Connection Throttling Configuration Response: JSON
 
−
 
 
−
{"connectionThrottle":{
 
−
"maxRequestRate": 50,
 
−
"rateInterval": 60
 
−
 
 
−
}
 
−
}
 
−
 
 
−
Example 4.43. Update Connection Throttling Configuration Request: XML
 
−
 
 
−
<connectionThrottle xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1"
 
−
maxRequestRate="50"
 
−
rateInterval="60" />
 
−
 
 
−
Example 4.44. Update Connection Throttling Configuration Request: JSON
 
−
 
 
−
{"connectionThrottle":{
 
−
"maxRequestRate": 50,
 
−
"rateInterval": 60
 
−
 
 
−
  }
 
−
}
 
−
 
 
−
4.8. Protocols
 
−
4.8.1. List Load Balancing Protocols
 
−
Verb URI Description
 
−
GET /loadbalancers/protocols List all supported load balancingprotocols.
 
−
 
 
−
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 define the protocol of the service which is being load balanced. The protocolselection should be based on the protocol of the back-end nodes. When configuring a HTTP or HTTPSload balancer, the default port for the given protocol will be selected unless otherwise specified. ForTCP load balancers, the prot attribute must be provided.
 
−
 
 
−
33
 
−
 
 
−
^l
 
−
API Operations
 
−
 
 
−
Example 4.45. List Load Balancing Protocols Response: XML
 
−
 
 
−
<protocols xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1">
 
−
<protocol name="TCP"/>
 
−
<protocol name="HTTP" port="80" />
 
−
<protocol name="HTTPS" port="443" />
 
−
 
 
−
</protocols>
 
−
 
 
−
Example 4.46. List Load Balancing Protocols Response: JSON
 
−
 
 
−
{"protocols": [
 
−
 
 
−
{  
 
−
"name": "HTTP",  
 
−
"port": "80"
 
−
 
 
−
},
 
−
 
 
−
{  
 
−
"name": "HTTPS",  
 
−
"port": "443"
 
−
 
 
−
},
 
−
{  
 
−
"name": "TCP"  
 
 
}
 
}
−
]
+
</nowiki></pre>
−
}
 
  
−
4.9. Algorithms  
+
=== Algorithms ===
−
All load balancers utilize an algorithm that defines how traffic should be directed between back-
+
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.
−
end nodes. The default algorithm for newly created load balancers is ROUND-ROBIN, which canbe overridden at creation time or changed after the load balancer has been initially provisioned. Thealgorithm name is to be constant within a major revision of the load balancing API, though newalgorithms may be created with a unique algorithm name within a given major revision of the serviceAPI.  
 
  
−
Table 4.6. Load Balancing Algorithms
+
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.
  
−
Name Description
+
'''Table 4.6. Load Balancing Algorithms'''
−
LEAST_CONNECTIONS The node with the lowest number of connections will receive requests.
+
{| border="1" cellpadding="2" cellspacing="0"
−
Weights can be defined as part of the node configuration.
+
| '''Name'''
−
ROUND_ROBIN Connections are routed to each of the back-end servers in turn. This is the
+
|-
−
default algorithm. Weights can be defined as part of the node configuration.
+
| LEAST_CONNECTIONS  
 +
|-
 +
| ROUND_ROBIN  
 +
|}
  
−
4.9.1. List Load Balancing Algorithms  
+
==== List Load Balancing Algorithms ====
−
Verb  
+
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Verb'''
 +
| '''URI'''
 +
| '''Description'''
 +
|-
 +
| GET
 +
| /algorithms
 +
| List all supported load balancing algorithms.
 +
|}
  
−
URI
+
'''Normal Response Code(s)''': 200
  
−
Description
+
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
−
GET
+
This operation does not require a request body.
  
−
/loadbalancers/algorithms
+
'''Example 4.48. List Load Balancing Algorithms Response: XML'''
  
−
List all supported load balancing algorithms.
 
  
−
Normal Response Code(s): 200
+
<pre><nowiki>#!highlight xml numbers=disable
 +
<algorithms xmlns="http://docs.openstack.org/atlas/api/v1.1">
 +
  <algorithm name="ROUND_ROBIN" />
 +
  <algorithm name="LEAST_CONNECTIONS" />
 +
</algorithms>
 +
</nowiki></pre>
  
−
Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401),
+
'''Example 4.49. List Load Balancing Algorithms Response: JSON'''
−
badRequest (400), overLimit (413)
 
−
This operation does not require a request body.
 
  
−
34
 
  
−
^l
+
<pre><nowiki>#!highlight javascript numbers=disable
−
API Operations
+
{
−
 
+
  "algorithms": [
−
Example 4.47. List Load Balancing Algorithms Response: XML
+
                  {
−
 
+
                    "name": "ROUND_ROBIN"
−
<algorithms xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1">
+
                  },
−
<algorithm name="LEAST_CONNECTIONS" />  
+
                  {
−
<algorithm name="ROUND_ROBIN" />
+
                    "name": "LEAST_CONNECTIONS"
−
 
+
                  }
−
</algorithms>
+
                ]
−
 
 
−
Example 4.48. List Load Balancing Algorithms Response: JSON
 
−
 
 
−
{"algorithms": [
 
−
{  
 
−
 
 
−
"name": "LEAST_CONNECTIONS"  
 
−
},
 
−
{  
 
−
 
 
−
"name": "ROUND_ROBIN"  
 
 
}
 
}
−
]
+
</nowiki></pre>
−
}
 
−
 
 
−
35
 
  
−
^l
+
== API Extensions ==
−
Chapter 5. 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).
  
−
Implementations of this API specifications are free to augment this core API with extensions as they seeappropriate to extend Load Balancing features (e.g. support for new LB algorithms)or offer new ones.
+
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.
−
All client applications written to this core specification however (using this core API) must be supportedby extended implementations as specified in this document. Therefore, these applications should notreceive payloads or values not specified in this specification or obtain a different behavior from theservice than expected.  
 
  
−
For a detailed description of how to use Extension APIs in [[OpenStack]] services, refer to [[OpenStackCompute]] API1.1 documentation on the [[OpenStack]] website.  
+
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.
  
−
36
+
[[Category: Neutron]]

Latest revision as of 21:01, 9 January 2015


#!wiki caution
'''Note'''

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

Contents

Overview

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:

Revision Date Summary of Changes

Revision Date
Feb 9, 2012
Jan. 24, 2012
May 27, 2011
Apr. 19, 2011
Feb. 23, 2011

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

Format Accept Header Query Extension
JSON application/json .json
XML application/xml .xml

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

Header Type Name
HTTP/1.1 Request Accept-Encoding
HTTP/1.1 Response Content-Encoding

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: https://loadbalancers.api.openstack.org/v1.1/1234/loadbalancers.

Table 3.3. Default Rate Limits

Verb URI RegEx
GET /v1.1/* ^/1.1/.*
POST /v1.1/* ^/1.1/.*
POST /v1.1/* ^/1.1/.*
PUT /v1.1/* ^/1.1/.*
DELETE /v1.1/* ^/1.1/.*

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:

Name Value
maxLoadBalancers 20
maxNodesPerLoadBalancer 5
maxVIPsPerLoadBalancer 1
maxDaysKeptForDeletedLoadBalancers 15
maxLoadBalancerNameLength 15

Determining Limits Programmatically

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

Verb URI
GET /limits

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
<limits xmlns="http://docs.openstack.org/common/api/v1.1">
   <rates>
      <rate uri="/v1.1/*" regex="^/1.1/.*">
          <limit  verb="GET"  value="600000"
                  remaining="426852"  unit="HOUR"
                  next-available="2011-02-22T19:32:43.835Z"/>
      </rate>
   </rates>

   <absolute>
       <limit name="maxNodesPerLoadBalancer" value="5"/>
       <limit name="maxVIPsPerLoadBalancer" value="1"/>
   </absolute>
</limits>

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
<badRequest xmlns="http://docs.openstack.org/atlas/api/v1.1" code="400">
   <message>Validation fault</message>
   <details>The object is not valid</details>
   <validationErrors>
      <message>Node IP address is invalid. Please specify a valid IP address.</message>
   </validationErrors>
</badRequest>

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
<immutableEntity code="422" xmlns="http://docs.openstack.org/atlas/api/v1.1">
  <message>The object at the specified URI is immutable and cannot be modified.
  </message>
</immutableEntity>

itemNotFound

Example 3.5. Fault Response, itemNotFound 


#!highlight xml numbers=disable
<itemNotFound code="404" xmlns="http://docs.openstack.org/atlas/api/v1.1">
  <message>Object not Found</message>
</itemNotFound>

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
<loadBalancerFault code="500" xmlns="http://docs.openstack.org/atlas/api/v1.1">
  <message>Load Balancer has experienced an internal error</message>
</loadBalancerFault>

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
<outOfVirtualIps code="500" xmlns="http://docs.openstack.org/atlas/api/v1.1">
   <message>
       Out of virtual IPs. Please contact support so they can allocate more virtual IPs.
   </message>
</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">
  <message>
    Load balancer cannot be created. You have reached your maximum number of load balancers.
  </message>
</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">
   <message>The Load balancing service is currently not available</message>
</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">
    <message>You are not authorized to execute this operation.</message>
</unauthorized>

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">
   <message>The Object at the specified URI is unprocessable.</message>
</unprocessableEntity>

API Operations

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

Load Balancers

List Load Balancers

Verb URI Description
GET /loadbalancers List all load balancers configured for the account.

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

Verb URI Description
GET /loadbalancers/loadBalancerId List details of the specified load balancer.

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>

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

   <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

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
  • 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">
      <nodes>
      <node address="10.1.1.1" port="80" />
      <node address="10.1.1.2" port="81" />
    </nodes>
</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>

      <nodes>
         <node address="10.1.1.1" port="80" condition="ENABLED" />
      </nodes>
</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>

    <nodes>
       <node id="653" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" />
    </nodes>
</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

Verb URI Description
PUT /loadbalancers/loadBalancerId Update the properties of a loadbalancer.

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

Name
ACTIVE
BUILD
PENDING_UPDATE
PENDING_DELETE
DELETED
SUSPENDED
ERROR

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

Verb URI Description
DELETE /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 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

Verb URI Description
GET /loadbalancers/loadBalancerId/nodes List node(s) configured for the load balancer.

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

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

Verb URI Description
GET /loadbalancers/loadBalancerId/nodes/nodeId Retrieve the configuration of node nodeid of loadbalancer loadbalancerId.

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

Verb URI Description
POST /loadbalancers/loadBalancerId/nodes Add a new node to the load balancer.

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

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

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

Verb URI Description
PUT /loadbalancers/loadBalancerId/nodes/nodeId Modify the configuration of a node on the load balancer.

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

Verb URI Description
DELETE /loadbalancers/loadBalancerId/nodes/nodeId Remove a node from the load balancer.

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

Name
PUBLIC
INTERNAL

List Virtual IPs

Verb URI Description
GET /loadbalancers/loadBalancerId/virtualips List all virtual IPs associated with 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 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"
                 }
                ]
}

Usage Reports

List Usage

Name URI Description
GET /loadbalancers/loadBalancerId/usage List current and historical 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

Verb URI Description
GET /loadbalancers/loadBalancerId/healthmonitor Retrieve the health monitor configuration, if one exists.
PUT /loadbalancers/loadBalancerId/healthmonitor Update the settings for a health monitor.
DELETE /loadbalancers/loadBalancerId/healthmonitor Remove the health monitor.

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

Name
CONNECT
HTTP
HTTPS
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.

Sessions

Manage Session Persistence

Verb URI Description
GET /loadbalancers/loadBalancerId/sessionpersistence List session persistence configuration.
PUT /loadbalancers/loadBalancerId/sessionpersistence Enable session persistence.
DELETE /loadbalancers/loadBalancerId/sessionpersistence Disable 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

Name
HTTP_COOKIE

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

Connections

Throttle Connections

Verb URI Description
GET /loadbalancers/loadBalancerId/connectionthrottle List connection throttling configuration.
PUT /loadbalancers/loadBalancerId/connectionthrottle Update throttling configuration.
DELETE /loadbalancers/loadBalancerId/connectionthrottle Remove connection throttling configurations.

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

Protocols

List Load Balancing Protocols

Verb URI Description
GET /protocols List all supported 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="*" />
</protocols>

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

Name
LEAST_CONNECTIONS
ROUND_ROBIN

List Load Balancing Algorithms

Verb URI Description
GET /algorithms List all supported 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" />
</algorithms>

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.

Retrieved from "https://wiki.openstack.org/w/index.php?title=Atlas-LB&oldid=71531"