Revision as of 08:22, 26 May 2011

OpenStack LoadBalancers API 1.1

Chapter 1. Overview

~+~-

1.1. Intended Audience

~+~-

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 isfamiliar with:

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

-~+~

1.2. Document Change History

~+~-

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

Apr. 19, 2011 • Added details to support initial GA release. Mar. 2, 2011 • Revised code samples and formatting to address initial beta feedback. Feb. 23, 2011 • Initial release for public beta.

^l Chapter 2. Concepts

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

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

2.2. Virtual IP A virtual IP is an Internet Protocol (IP) address configured on the load balancer for use by clientsconnecting 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.

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

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

2.4.1. Passive Health Monitor By default, all load balancing configurations utilize a passive health monitor, which is the defaultmonitoring and does not require configuration from the user. If the passive health monitoring determinesthat a node is down, unreachable or malfunctioning, it puts the node in an OFFLINE state and stopssending traffic to it.

2.4.2. Active Health Monitor Active health monitoring is a technique that is configured by users. It uses synthetic transactionsexecuted at periodic intervals to determine the condition of a node. When active monitoring isconfigured, 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 thenodes of the load balancer

The active health monitor can use 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 toOFFLINEand the node will not receive traffic. If, after running a subsequent test, the probe detectsthat the node has recovered, then the node's status is changed to ONLINEand it is capable of servicingrequests.

2

^l Concepts

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

2.6. Connection Logging The connection logging feature allows for retrieving access logs (for HTTP-based protocol traffic) orconnection and transfer logs (for all other traffic)

3

^l Chapter 3. General API Information

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

3.1. Authentication Load Balancing API will use the standard defined by OpenStack for authentication. Once this isfinalized, this section will describe how users can authenticate and obtain a token from the OpenStackAuthentication 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 fordetailed information

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

3.3. Request/Response Types The Cloud Load Balancers API supports both the JSON and XML data serialization formats. Therequest format is specified using the Content-Typeheader and is required for operations that havea request body. The response format can be specified in requests using either the Acceptheader or adding an .xmlor .jsonextension to the request URI. Note that it is possible for a response to beserialized using a format different from the request. If no response format is specified, JSON is thedefault. If conflicting formats are specified using both an Acceptheader and a query extension, thequery 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

3.4. Content Compression Request and response body data may be encoded with gzip compression to accelerate interactiveperformance of API calls and responses. This is controlled using the Accept-Encodingheader in the request from the client and indicated by the Content-Encodingheader 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

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

4

^l General API Information

Note

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

3.6. Paginated Collections 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.

3.7. Limits 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 We specify rate limits in terms of both a human-readable wild-card URI and a machine-processableregular expression. The regular expression boundary matcher '^{' takes effect after the root URI path. Forexample, the regular expression}/v1.1/1234/loadbalancerswould match the bolded portionof the following URI: https://loadbalancers.api.openstack.org/v1.1/1234/ loadbalancers.

Table 3.3. Default Rate Limits

Verb URI RegEx Default Limit GET /v1.1/* ^/1.1/.* 5/second POST /v1.1/* ^/1.1/.* 2/second POST /v1.1/* ^/1.1/.* 25/minute PUT /v1.1/* ^/1.1/.* 5/second DELETE /v1.1/* ^/1.1/.* 2/second

Rate limits are applied in order relative to the verb, going from least to most specific. For example, although the threshold for POST to /v1.1/* is 25 per minute, one cannot POST to /v1.1/* more than2 times per second because the rate limit for any POST is 2 per second. In the event you exceed 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 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 Applications can programmatically determine current account limits using the /limitsURI as follows:

Verb

URI

Description

GET

/limits

Return the current limits 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 does not require a request body.

Example 3.1. List Limits Response: XML

</rate> </rates> <absolute>

6

^l General API Information

Example 3.2. List Limits Response: JSON

"limits" : { "rate" : { "values": [

{ "uri" : "/v1.1/*", "regex" : "^/1.1/-.*", "limit" : [

{ "verb" : "GET", "value" : 600000, "remaining" : 426852, "unit" : "HOUR", "next-available" : "2011-02-22T19:32:43.835Z"

] }

] }, "absolute" : {

"values" : { "maxNodesPerLoadBalancer" : 5, "maxVIPsperLoadBalancer" : 2

} } }

3.8. Faults 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 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.

7

^l General API Information

Example 3.3. Fault Response, badRequest

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

code="400"> <message>Validation fault</message> <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 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.

Example 3.4. Fault Response, immutableEntity

<immutableEntity code="422" xmlns="http://docs.openstack.org/

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/

loadbalancers/api/v1.1"> <message>Object not Found</message> </itemNotFound>

3.8.5. loadBalancerFault The loadBalancerFaultfault shall be returned in the event that an error occurred during aloadbalancer operation.

Example 3.6. Fault Response, loadBalancerFault

<loadBalancerFault code="500" xmlns="http://docs.openstack.org/

loadbalancers/api/v1.1"> <message>Load Balancer has experienced an internal error</message> </loadBalancerFault>

8

^l General API Information

3.8.6. outOfVirtualIps 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/

loadbalancers/api/v1.1"> <message> Out of virtual IPs. Please contact support so they can allocatemore virtual IPs. </message> </outOfVirtualips>

3.8.7. 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/loadbalancers/

api/v1.1"> <message>Your account is currently over the limit so your requestcould not be processed.</message> </overLimit>

3.8.8. serviceUnavailable 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.

Example 3.9. Fault Response, serviceUnavailable

<serviceUnavailable code="500" xmlns="http://docs.openstack.org/

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

^l General API Information

Example 3.10. Fault Response, unauthorized

<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 This fault is returned when an operation is requested on an item that does not support the operation reword.

Example 3.11. Fault Response, unprocessableEntity

<unprocessableEntity code="422" xmlns="http://docs.openstack.org/

loadbalancers/api/v1.1"> <message>The Object at the specified URI is unprocessable.</ message> </unprocessableEntity>

10

^l Chapter 4. API Operations

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

4.1. Load Balancers 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), 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 url. A deleted loadbalancer is immutable and irrecoverable. Only a limited set of attributes will be returned in the responseobject:

• id • name • algorithm • protocol • port • created • updated This operation does not require a request body.

11

^l API Operations

Example 4.1. List Load Balancers Response: XML

<?xml version=-"1.0" ?> <loadBalancers xmlns="http:/-/docs.openstack.org/loadbalancers/api/v1.1">

<virtualIp id="403" address="206.55.130.1" ipVersion="IPV4"

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

</loadBalancer>

<virtualIp id="401" address="206.55.130.2" ipVersion="IPV4"

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

</loadBalancer> </loadBalancers>

12

^l API Operations

Example 4.2. List Load Balancers Response: JSON

{ "loadBalancers":[

{ "name":"lb-site1", "id":"71", "protocol":"HTTP", "port":"80", "algorithm":"RANDOM", "status":"ACTIVE", "virtualIps":[

{ "id":"403", "address":"206.55.130.1", "type":"PUBLIC", "ipVersion":"IPV4"

], "created":{

"time":"2010-11-30T03:23:42Z" }, "updated":{

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

}, {

"name":"lb-site2", "id":"166", "protocol":"HTTP", "port":"80", "algorithm":"RANDOM", "status":"ACTIVE", "virtualIps":[

{ "id":"401", "address":"206.55.130.2", "type":"PUBLIC", "ipVersion":"IPV4"

], "created":{

"time":"2010-11-30T03:23:42Z" }, "updated":{

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

4.1.2. List Load Balancer Details 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), badRequest (400), overLimit (413)

13

^l 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.

Example 4.3. List Load Balancer Details Request: XML

</virtualIps> <nodes>

</nodes> <sessionPersistence persistenceType="HTTP_COOKIE"/> <connectionThrottle

maxConnectionRate="50"

rateInterval="60" /> <cluster name="c1.dfw1" /> <created time="2010-11-30T03:23:42Z" /> <updated time="2010-11-30T03:23:44Z" />

</loadBalancer>

14

^l API Operations

Example 4.4. List Load Balancers Details Response: JSON

{

"loadBalancer":{ "id": 2000, "name":"sample-loadbalancer", "protocol":"HTTP", "port": 80, "algorithm":"ROUND_ROBIN", "status":"ACTIVE", "connectionLogging":{

"enabled":"true" }, "virtualIps":[

{ "id": 1000, "address":"206.10.10.210", "type":"PUBLIC", "ipVersion":"IPV4"

], "nodes":[

{ "id": 1041, "address":"10.1.1.1", "port": 80, "condition":"ENABLED", "status":"ONLINE"

},

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

], "sessionPersistence":{

"persistenceType":"HTTP_COOKIE" }, "connectionThrottle":{

"maxRequestRate": 50,

"rateInterval": 60 }, "cluster":{

"name":"c1.dfw1" }, "created":{

"time":"2010-11-30T03:23:42Z" }, "updated":{

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

15

^l API Operations

4.1.3. Create Load Balancer Verb URI Description Representation POST /loadbalancers Create a new load balancer with the configuration defined by the request. XML, JSON 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 willbe returned. The object will contain a unique identifier and status of the request.

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 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 • protocol • port • At least one VirtualIp • At least one node If the request cannot be fulfilled due to insufficient or invalid data, an HTTP400 (Bad Request) 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.

Note

A load balancer's name has a max length that can be queried when querying limits.

Note

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.

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

16

^l API Operations

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

{

"loadBalancer": { "name": "a-new-loadbalancer", "port": "80", "protocol": "HTTP", "virtualIps": [

{ "type": "PUBLIC"

], "nodes": [

{ "address": "10.1.1.1", "port": "80", "condition": "ENABLED"

] } }

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

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

17

^l API Operations

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

{

"loadBalancer":{ "name":"a-new-loadbalancer", "port":"80", "protocol":"HTTP", "virtualIps":[

{ "id":"39"

], "nodes":[

{ "address":"10.1.1.1", "port":"80", "condition":"ENABLED"

] } }

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

</virtualIps> <nodes>

</nodes> <cluster name="ztm-n03.staging1.lbaas.demo.net" /> <created time="2011-02-08T21:19:55Z" /> <updated time="2011-02-08T21:19:55Z" /> <connectionLogging enabled="false" />

</loadBalancer>

18

^l API Operations

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

{

"loadBalancer": {

"name": "a-new-loadbalancer", "id": 144, "protocol": "HTTP", "port": 83, "algorithm": "ROUND_ROBIN", "status": "BUILD", "cluster": {

"name": "ztm-n01.staging1.lbaas.demo.net" }, "nodes": [

{ "address": "10.1.1.1", "id": 653, "port": 80, "status": "ONLINE", "condition": "ENABLED"

], "virtualIps": [

{ "address": "206.10.10.210", "id": 39, "type": "PUBLIC", "ipVersion": "IPV4"

} ], "created": {

"time": "2011-04-13T14:18:07Z" }, "updated": {

"time": "2011-04-13T14:18:07Z" }, "connectionLogging": {

"enabled": false } } }

4.1.4. Update Load Balancer Attributes 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), 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

19

^l API Operations

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

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

• name • algorithm This operation does not return a response body.

Note

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

Example 4.11. Update Load Balancer Attributes Request: XML

Example 4.12. Update Load Balancer Attributes Request: JSON

{"loadBalancer":{ "name": "sample-loadbalancer", "algorithm": "ROUND_ROBIN" }

}

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

Name Description 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

^l API Operations

Name

Description

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

4.1.5. Remove Load Balancer 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 configurationfrom 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.

4.2. Nodes The nodes defined by the load balancer are responsible for servicing the requests received through theload balancer's virtual IP. By default, the load balancer employs a basic health check that ensures thenode is listening on its defined port. The node is checked at the time of addition and at regular intervalsas defined by the load balancer health check configuration. If a back-end node is not listening on its portor does not meet the conditions of the defined active health check for the load balancer, then the loadbalancer will not forward connections and its status will be listed as OFFLINE. Only nodes that are in an ONLINEstatus 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 the node using the weight attribute of the node element. 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 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), badRequest (400), overLimit (413) This operation does not require a request body.

21

^l API Operations

Example 4.13. List Node Response: XML

Example 4.14. List Node Response: JSON

{"node": { "id":"410", "address":"10.1.1.1", "port":80, "condition":"ENABLED", "status":"ONLINE"

}

Example 4.15. List Nodes Response: XML

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

</nodes>

22

^l API Operations

Example 4.16. List Nodes Response: JSON

{ "nodes": [

{ "address": "10.1.1.1", "id": 650, "port": 80, "status": "ONLINE", "condition": "ENABLED"

},

{ "address": "10.2.2.1", "id": 183, "port": 80, "status": "ONLINE", "condition": "ENABLED"

},

{ "address": "10.2.2.2", "id": 184, "port": 88, "status": "ONLINE", "condition": "ENABLED"

] }

4.2.2. 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)

This operation does not require a request body.

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.17. Add Nodes Request: XML

</nodes>

23

^l API Operations

Example 4.18. Add Nodes Request: JSON

{"nodes": [

{ "address": "10.1.1.1", "port": 80, "condition": "ENABLED"

},

{ "address": "10.2.2.1", "port": 80, "condition": "ENABLED"

},

{ "address": "10.2.2.2", "port": 88, "condition": "ENABLED", "weight": 10

] }

Example 4.19. Add Nodes Response: XML

</nodes>

24

^l API Operations

Example 4.20. Add Nodes Response: JSON

{"nodes": [

{ "address": "10.2.2.3", "id": 185, "port": 80, "status": "ONLINE", "condition": "ENABLED"

},

{ "address": "10.2.2.4", "id": 186, "port": 80, "status": "ONLINE", "condition": "ENABLED"

] }

4.2.3. Modify Nodes Verb

URI

Description PUT

/loadbalancers/loadBalancerId/nodes/nodeId

Modify the configuration of a node on the loadbalancer.

Normal Response Code(s): 202

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

This operation does not require a request body.

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. Aload balancer supports a maximum number of nodes. The maximum number of nodes perloadbalancer is a queryable limit.

Every node in the load balancer has an associated condition which determines its role within the loadbalancer.

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

25

^l API Operations

Example 4.22. Update Node Condition Request: JSON

{"node":{ "condition": "ENABLED" } }

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

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

Name Description 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 Verb

URI

Description

GET

/loadbalancers/loadBalancerId/virtualips

List all virtual IPs associated with a load balancer.

Normal Response Code(s): 200, 202

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413) This request does not require a request body.

Note

The number of VIPs that can be configured when creating a load balancer is a queryablelimit.

26

^l API Operations

Example 4.23. List Virtual IPs Response: XML

</virtualIps>

Example 4.24. List Virtual IPs Response: JSON

{"virtualIps": [

{ "id": "1000", "address": "206.10.10.210", "type": "PUBLIC" }

] }

4.4. Usage Reports 4.4.1. 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 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.

Example 4.25. Report Load Balancer Usage Response: XML

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

Example 4.28. Monitor Connections Request: JSON

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

}

Example 4.29. Monitor Connections Response: XML

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

30

^l API Operations

Example 4.34. List Session Persistence Configuration Response: JSON

{ "sessionPersistence":{ "persistenceType":"HTTP_COOKIE" } }

Example 4.35. Set Session Persistence Type Request: XML

Example 4.36. Set Session Persistence Type 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

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), 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

31

^l API Operations

Example 4.38. List Connection Logging Configuration Response: JSON

{ "connectionLogging": { "enabled": "true" } }

Example 4.39. Enable Connection Logging Request: XML

Example 4.40. Enable Connection Logging Request: JSON

{ "connectionLogging":{ "enabled":"true" } }

4.7.2. 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 throttlingconfigurations.

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.

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.

Note

Whent the rate is exceeded, the load balancer returns a serviceUnavailable (503) for HTTP/ HTTPS loadbalancers and refuses connections for TCP loadbalancers.

• maxRequestRate: Maximum number of requests allowed from a single IP address in the definedrateInterval. Setting a value of 0 allows an unlimited connection rate. • rateInterval: Frequency (in seconds) at which the maxRequestRateis assessed. For example, a maxRequestRateof 30 with a rateIntervalof 60 would allow a maximum of 30 connections per minute for a single IP address. This value must be specified between 1 and 3600. 32

^l API Operations

Example 4.41. List Connection Throttling Configuration Response: XML

Example 4.42. List Connection Throttling Configuration Response: JSON

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

}

Example 4.43. Update Connection Throttling Configuration Request: XML

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>

Example 4.46. List Load Balancing Protocols Response: JSON

{"protocols": [

{ "name": "HTTP", "port": "80"

},

{ "name": "HTTPS", "port": "443"

}, { "name": "TCP" } ] }

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

Name Description LEAST_CONNECTIONS The node with the lowest number of connections will receive requests. Weights can be defined as part of the node configuration. 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.

4.9.1. List Load Balancing Algorithms Verb

URI

Description

GET

/loadbalancers/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.

34

^l API Operations

Example 4.47. List Load Balancing Algorithms Response: XML

</algorithms>

Example 4.48. List Load Balancing Algorithms Response: JSON

{"algorithms": [ {

"name": "LEAST_CONNECTIONS" }, {

"name": "ROUND_ROBIN" } ] }

35

^l Chapter 5. API Extensions

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

36

@@ Line 18: / Line 18: @@
 * JSON and/or XML serialization formats
-~+~-
+-~+~
 === 1.2. Document Change History ===
@@ Line 25: / Line 25: @@
 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 ====
-~+~-
+<span style="font-size: larger"><span style="font-size: smaller">Apr. 19, 2011 • Added details to support initial GA release. </span></span>
+<span style="font-size: larger"><span style="font-size: smaller">Mar. 2, 2011 • Revised code samples and formatting to address initial beta feedback. </span></span>
-Apr. 19, 2011 • Added details to support initial GA release.
+<span style="font-size: larger"><span style="font-size: smaller">Feb. 23, 2011 • Initial release for public beta. </span></span>
-Mar. 2, 2011 • Revised code samples and formatting to address initial beta feedback.
-Feb. 23, 2011 • Initial release for public beta.
 ^l

Difference between revisions of "Atlas-LB"

Revision as of 08:22, 26 May 2011

OpenStack LoadBalancers API 1.1

Chapter 1. Overview

1.1. Intended Audience

1.2. Document Change History

Revision Date Summary of Changes