• Atlas-LB

OpenStack LoadBalancers API 1.1

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

Concepts

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

Load Balancer

A load balancer is a logical device. It is used to distribute workloads between multiple back-end systems or services called nodes, based on the criteria defined as part of its configuration.

Virtual IP

A virtual IP is an Internet Protocol (IP) address configured on the load balancer for use by clients connecting to a service that is load balanced. Incoming connections and requests are distributed to back-end nodes based on the configuration of the load balancer.

Node

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

Health Monitoring

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

Passive Health Monitoring

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

Active Health Monitoring

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

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

• CONNECT
• HTTP
• HTTPS

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

Session Persistence

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

General API Information

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

Authentication

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

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

Service Access/Endpoints

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

Request/Response Types

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

Table 3.1. JSON and XML Response Formats

Content Compression

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

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

Table 3.2. Encoding Headers

Persistent Connections

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

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

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

Absolute Limits

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

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

Determining Limits Programmatically

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

Normal Response Code(s): 200

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

This operation does not require a request body.

Example 3.1. List Limits Response: XML

<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

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

<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

<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

<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

<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

<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

<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

<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

<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

<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

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

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

{
  "loadBalancers":[
         {
           "name":"lb-site1",
           "id":"71",
           "protocol":"HTTP",
           "port":"80",
           "algorithm":"LEAST_CONNECTIONS",
           "status":"ACTIVE",
           "created":"2010-11-30T03:23:42Z",
           "updated":"2010-11-30T03:23:44Z"
         },
         {
           "name":"lb-site2",
           "id":"166",
           "protocol":"TCP",
           "port":"9123",
           "algorithm":"ROUND_ROBIN",
           "status":"ACTIVE",
           "created":"2010-11-30T03:23:42Z",
           "updated":"2010-11-30T03:23:44Z"
         }
      ]
}

List Load Balancer Details

Normal Response Code(s): 200

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

This operation provides detailed output for a specific load balancer configured and associated with your account. This operation is not capable of returning details for a load balancer which has been deleted.

This operation does not require a request body.

Example 4.3. List Load Balancer Details Response: XML

<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

{
      "id": "2000",
      "name":"sample-loadbalancer",
      "protocol":"HTTP",
      "port": "80",
      "algorithm":"ROUND_ROBIN",
      "status":"ACTIVE",
      "created":"2010-11-30T03:23:42Z",
      "updated":"2010-11-30T03:23:44Z",
      "virtualIps":[
                    {
                       "id": "1000",
                       "address":"2001:cdba:0000:0000:0000:0000:3257:9652",
                       "type":"PUBLIC",
                       "ipVersion":"IPV6"
                    }
                   ],

       "nodes":     [
                      {
                         "id": "1041",
                         "address":"10.1.1.1",
                         "port": "80",
                         "condition":"ENABLED",
                         "status":"ONLINE"
                       },
                       {
                         "id": "1411",
                         "address":"10.1.1.2",
                         "port": "80",
                         "condition":"ENABLED",
                         "status":"ONLINE"
                       }
                     ],
       "sessionPersistence":{
                              "persistenceType":"HTTP_COOKIE"
                            },
       "connectionThrottle":{
                              "maxRequestRate": "50",
                              "rateInterval": "60"
                            }
}

Create Load Balancer

Normal Response Code(s): 202

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

This operation provisions a new load balancer based on the configuration defined in the request object. Once the request is validated and progress has started on the provisioning process, a response object will be returned. The object will contain a unique identifier and status of the request.

If the status returned is set to "BUILD", then using the identifier of the load balancer, the caller can check on the progress of the creation operation by performing a GET on loadbalancers/loadbalancerid. When the status of the load balancer returned changes to "ACTIVE", then the load balancer has been successfully provisioned and is now operational.

The caller of this operation must specify at least the following attributes of the load balancer:

• name
• At least one node

If the request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 (Bad Request) error response will be returned with information regarding the nature of the failure in the body of the response. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST the request again.

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.

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

<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

{
    "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.

Example 4.7. Create Load Balancer (Required Attributes with Shared IP) Request: 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

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

<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

{
    "name": "a-new-loadbalancer",
    "id": "144",
    "protocol": "HTTP",
    "port": "83",
    "algorithm": "ROUND_ROBIN",
    "status": "BUILD",
    "created": "2011-04-13T14:18:07Z",
    "updated":"2011-04-13T14:18:07Z",
    "virtualIps": [
                    {
                      "address": "3ffe:1900:4545:3:200:f8ff:fe21:67cf",
                      "id": "39",
                      "type": "PUBLIC",
                      "ipVersion": "IPV6"
                    }
                  ],
    "nodes":      [
                    {
                      "address": "10.1.1.1",
                      "id": "653",
                      "port": "80",
                      "status": "ONLINE",
                      "condition": "ENABLED"
                    }
                  ]
}

Update Load Balancer Attributes

Normal Response Code(s): 202

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

This operation updates the attributes of the specified load balancer. Upon successful validation of the request, the service will return a 202 (Accepted) response code. A caller should check that the load balancer status is ACTIVE to confirm that the update has taken effect. If the load balancer status is "PENDING_UPDATE" then the caller can poll the load balancer with its ID (using a GET operation) to wait for the changes to be applied and the load balancer to return to an ACTIVE status.

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

• name
• algorithm

This operation does not return a response body.

Example 4.11. Update Load Balancer Attributes Request: XML

<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

{
   "name": "newname-loadbalancer",
   "algorithm": "LEAST_CONNECTIONS"
}

Table 4.1. Load Balancer Statuses

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

Remove Load Balancer

Normal Response Code(s): 202

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

The remove load balancer function removes the specified load balancer and its associated configuration from the account. Any and all configuration data is immediately purged and is not recoverable.

This operation does not require a request body.

This operation does not return a response body.

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

Nodes

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

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

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

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

List Nodes

List all nodes of a load balancer.

Normal Response Code(s): 200

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

This operation does not require a request body.

Example 4.13. List Nodes Response: XML

<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

{
  "nodes" : [
              {
                "id":"410",
                "address":"10.1.1.1",
                "port":"80",
                "condition":"ENABLED",
                "status":"ONLINE"
              },
              {
                "id":"236",
                "address":"10.1.1.2",
                "port":"80",
                "condition":"ENABLED",
                "status":"ONLINE"
              },
              {
                "id":"2815",
                "address":"10.1.1.3",
                "port":"83",
                "condition":"DISABLED",
                "status":"OFFLINE"
              },
            ]
}

Retrieve a Node

This operation retrieves the configuration of a node.

Normal Response Code(s): 200

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

This operation does not require a request body.

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

<node id="236" address="10.1.1.2" port="80" condition="ENABLED" status="ONLINE" />

Example 4.16. Retrieve a node Response: JSON

{
  "id":"236",
  "address":"10.1.1.2",
  "port":"80",
  "condition":"ENABLED",
  "status":"ONLINE"
}

Add Nodes

Normal Response Code(s): 202

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

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

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

Example 4.17. Add Nodes Request: XML

<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

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

<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

{
  "nodes": [
             {
               "id": "7298",
               "address": "10.1.1.1",
               "port": "80",
               "condition": "ENABLED",
               "status": "ONLINE"
             },
             {
               "id": "293",
               "address": "10.2.2.1",
               "port": "80",
               "weight": "2",
               "condition": "ENABLED",
               "status": "OFFLINE"
             },
             {
               "id": "183",
               "address": "10.2.2.4",
               "port": "88",
               "weight": "2",
               "condition": "DISABLED",
               "status": "OFFLINE"
             }
           ]
}

Modify Nodes

Normal Response Code(s): 202

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

This operation does not return a response body.

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

<node condition="DISABLED" />

Example 4.22. Disable a node Request: JSON

{
  "condition": "DISABLED"
}

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

Remove Nodes

Normal Response Code(s): 200, 202

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

This operation does not require a request body.

This operation does not return a response body.

Virtual IPs

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

Table 4.3. Virtual IP Types

List Virtual IPs

Normal Response Code(s): 200

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

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

This request does not require a request body.

Example 4.23. List Virtual IPs Response: XML

<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

{
  "virtualIps": [
                 {
                   "id": "1021",
                   "address": "206.10.10.210",
                   "type": "PUBLIC",
                   "ipVersion": "IPV4"
                 }
                ]
}

Usage Reports

List Usage

Normal Response Code(s): 200

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

This operation does not require a request body.

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

Example 4.25. Report Load Balancer Usage Response: XML

<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

{
  "loadBalancerUsageRecords": [
                                {
                                  "id": "394",
                                  "transferBytesIn": "2819204",
                                  "transferBytesOut": "84923069"
                                },
                                {
                                  "id": "473",
                                  "transferBytesIn": "0",
                                  "transferBytesOut": "0"
                                }
                              ]
}

Monitors

Normal Response Code(s): 200, 202

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

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

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

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

Table 4.4. Health Monitor Types

Monitor CONNECT

The monitor connects to each node on its defined port to ensure that the node is listening properly.

The CONNECT monitor is the most basic type of health check and does not perform post-processing or protocol specific health checks. It includes several configurable properties:

• delay: This is the minimum time in seconds between regular calls to a monitor.

• timeout: Maximum number of seconds for a monitor to wait for a connection to be established to the node before it times out. The value must be less than the delay value.

• attemptsBeforeDeactivation: Number of permissible monitor failures before removing a node from rotation. Must be a number between 1 and 10.

Example 4.27. Monitor CONNECT Request: XML

<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

{
  "type": "CONNECT",
  "delay": "20",
  "timeout": "10",
  "attemptsBeforeDeactivation": "3"
}

Example 4.29. Monitor Connections Response: XML

<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

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

<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

<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

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

Normal Response Code(s): 200, 202

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

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

Table 4.5. Session Persistence Modes

Example 4.34. List Session Persistence Configuration Response: XML

<sessionPersistence xmlns="http://docs.openstack.org/atlas/api/v1.1"
                    persistenceType="HTTP_COOKIE" />

Example 4.35. List Session Persistence Configuration Response: JSON

{
   "persistenceType":"HTTP_COOKIE"
}

Example 4.36. Set Session Persistence Type Request: XML

<sessionPersistence xmlns="http://docs.openstack.org/atlas/api/v1.1"
                    persistenceType="HTTP_COOKIE" />

Example 4.37. Set Session Persistence Type Request: JSON

{
    "persistenceType":"HTTP_COOKIE"
}

Connections

Throttle Connections

Normal Response Code(s): 200, 202

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

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

• maxRequestRate: Maximum number of HTTP requests (or TCP connections) allowed from a single IP address in the defined rateInterval. Setting a value of 0 allows an unlimited connection or request rate.

• rateInterval: Frequency (in seconds) at which the maxRequestRate is assessed. For example, a maxRequestRate of 30 with a rateInterval of 60 would allow a maximum of 30 HTTP requests or TCP connections per minute from a single IP address. This attribute must have a value between 1 and 3600.

Example 4.42. List Connection Throttling Configuration Response: XML

<connectionThrottle xmlns="http://docs.openstack.org/atlas/api/v1.1"
                    maxRequestRate="50" rateInterval="60" />

Example 4.43. List Connection Throttling Configuration Response: JSON

{
    "maxRequestRate": "50",
    "rateInterval": "60"
}

Example 4.44. Update Connection Throttling Configuration Request: XML

<connectionThrottle xmlns="http://docs.openstack.org/atlas/api/v1.1"
                    maxRequestRate="40" />

Example 4.45. Update Connection Throttling Configuration Request: JSON

{
   "maxRequestRate": "40"
}

Protocols

List Load Balancing Protocols

Normal Response Code(s): 200

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

This operation does not require a request body.

All load balancers must be configured with the protocol of the service which is being load balanced. The protocol selection should be based on the protocol of the back-end nodes. The current specification supports HTTP, HTTPS and TCP services.

When configuring an HTTP or HTTPS load balancer, the default port for the given protocol will be selected unless otherwise specified. For TCP load balancers, the port attribute must be provided.

Example 4.46. List Load Balancing Protocols Response: XML

<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

{
 "protocols": [
               {
                 "name": "HTTP",
                 "port": "80"
               },
               {
                 "name": "HTTPS",
                 "port": "443"
               },
               {
                 "name": "TCP",
                 "port": "*"
               }
              ]
}

Algorithms

All load balancers utilize an algorithm that defines how traffic should be directed between back- end nodes. The default algorithm for newly created load balancers is ROUND_ROBIN, which can be overridden at creation time or changed after the load balancer has been initially provisioned.

The algorithm name is to be constant within a major revision of the load balancing API, though new algorithms may be created with a unique algorithm name within a given major revision of this API.

Table 4.6. Load Balancing Algorithms

List Load Balancing Algorithms

Normal Response Code(s): 200

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

This operation does not require a request body.

Example 4.48. List Load Balancing Algorithms Response: XML

<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

{
   "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.