Jump to: navigation, search

Neutron/LBaaS/API

< Neutron‎ | LBaaS
Revision as of 21:15, 26 October 2012 by YoucefLaribi (talk)


#!wiki caution
'''Note'''

OpenStack Quantum LBaaS API 1.0

<<TableOfContents()>>

Overview

Intended Audience

Intended Audience

This guide is for software developers who create applications by using the LBaaS API v1.0. To use this information, you should have a general understanding of the OpenStack LBaaS network service, the OpenStack Quantum service, and the integration between the two. You should also have access to a plugin that implements the LBaaS API v2.0.

You should also be familiar with:

  • ReSTful web services
  • HTTP/1.1
  • JSON and XML data 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
Oct,25 2012

Resources

Use the following resources in conjunction with this guide:

Resource

Chapter 1. Overview

The LBaaS project provides a load balancing service to enable OpenStack tenants to load balance traffic to their VMs.

Th capabilities provided by the LBaaS service are:

--- To be continued ---

Glossary

Term

High-Level Task Flow

The high-level task flow for LBaaS configuration is as follows:

  1. The tenant creates a vip.
  2. etc.

The Plugin

Concepts

To use OpenStack LBaaS APIs effectively, you should understand several key concepts:

VIP

A vip is a load balancing configuration object that specifies the virtual IP address and port on which traffic is received, as well as other details such as the load balancing method, protocol, etc. This is the primary entity of configuration in the API.

Pool

A pool is a group of members to which the traffic is load-balanced. The LBaaS service chooses a member of the pool according to the load balancing method to handle the new requests or connections received on the vip address. In the Core LBaaS service, there is only one pool for a vip.

Member

A member is a back-end physical or virtual device providing a service on a specified IP and port. A member belongs to one pool.

Health Monitoring

A health monitor is used to determine whether or not back-end members of a vip are usable for processing a request. There are different types of health monitors supported. A pool can have several health monitors bound to it.

The following types of health monitors are available for use:

  • PING
  • TCP
  • HTTP
  • HTTPS

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. The OpenStack LBaaS service supports two types of persistence:

  • SOURCE IP
  • HTTP COOKIE

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

The LBaaS API v1.0 uses the Keystone Identity Service as the default authentication service. When Keystone is enabled, users that submit requests to the LBaaS service must provide an authentication token in X-Auth-Token request header. You obtain the token by authenticating to the Keystone endpoint. For more information about Keystone, see the OpenStack Identity Developer Guide.

When Keystone is enabled, the tenant_id attribute is not required in create requests because the tenant ID is derived from the authentication token.

The default authorization settings allow only administrative users to create resources on behalf of a different tenant.

LBaaS uses information received from Keystone to authorize user requests. LBaaS handles the following types of authorization policies:

Operation-based policies

Specify access criteria for specific operations, possibly with fine-grained control over specific attributes.

Resource-based policies

Access a specific resource. Permissions might or might not be granted depending on the permissions configured for the resource.

Request/Response Types

The LBaaS API v1.0 supports the JSON data serialization format.

Example 3.1. Request/Response with Headers: JSON

The format for both the request and the response can be specified using the Content-Type header, the Accept header or adding the .json extension to the request URI.

Request:

POST /v1.0/vips HTTP/1.1 Host 127.0.0.1:9696 Content-Type application/json Accept application/json X-Auth-Token:887665443383838 Content-Length 57

{

"vips": [
   {
     "name": "web_vip",
     "network_id" : "2a4017ef-31ff-496a-9294-e96ecc3bc9c9",
     "port" : 80,
     "protocol" : "HTTP",
     "session_persistence" : {"type" : "HTTP_COOKIE"},
     "connection_limit" : 500, 
     "admin_state": "ENABLED"
   }
 ]

}

Response:

HTTP/1.1 201 Created Content-Type application/json Content-Length 204

{

"vips": [
   {
     "id" : "3cd412ef-c6ff-2a6a-9294-7b0ec43b91a"
     "name": "web_vip",
     "network_id" : "2a4017ef-31ff-496a-9294-e96ecc3bc9c9",
     "port" : 80,
     "protocol" : "HTTP",
     "session_persistence" : {"type" : "HTTP_COOKIE"},
     "connection_limit" : 500, 
     "admin_state" : "ENABLED",
     "status" : "ACTIVE"
   }
 ]

}

Filtering and Column Selection

The LBaaS API v1.0 supports filtering based on all top level attributes of a resource. Filters are applicable to all list requests.

For example, the following request returns all networks named foobar:

GET /v1.0/vips?name=foobar When you specify multiple filters, the LBaaS API v1.0 returns only objects that meet all filtering criteria. The operation applies an AND condition among the filters.

Note LBaaS does not offer an OR mechanism for filters.

Alternatively, you can issue a distinct request for each filter and build a response set from the received responses on the client-side.

By default, LBaaS returns all attributes for any show or list call. The LBaaS API v1.0 has a mechanism to limit the set of attributes returned. For example, return id.

You can use the fields query parameter to control the attributes returned from the LBaaS API v1.0.

For example, the following request returns only id,name,network_id,address and port for each vip:

GET /v1.0/vips.json?fields=id&fields=name&fields=network_id&fields=address&fields=port

Synchronous versus Asynchronous Plugin Behavior

The LBaaS API v1.0 presents a logical load balancing configuration consisting of vips, pools, and members. It is up to the LBaaS plugin to communicate with the underlying infrastructure to ensure load balancing is consistent with the logical model. A plugin might perform these operations asynchronously.

When an API client modifies the logical model by issuing an HTTP POST, PUT, or DELETE request, the API call might return before the plugin modifies underlying virtual and physical switching devices. However, an API client is guaranteed that all subsequent API calls properly reflect the changed logical model.

For example, if a client issues an HTTP PUT request to add a member to a pool, there is no guarantee that the member can receive traffic when the HTTP call returns. However, it is guaranteed that a subsequent HTTP GET request to view the members on the pool returns a list that would contain the added member.

You can use the status attribute of the vip, the pool and the member to determine whether the LBaaS plugin has successfully completed the configuration of the resource.

Bulk Create Operations

The LBaaS API v1.0 enables you to create several objects of the same type in the same API request. Bulk create operations use exactly the same API syntax as single create operations except that you specify a list of objects rather than a single object in the request body.

Bulk operations are always performed atomically, meaning that either all or none of the objects in the request body are created. If a particular plugin does not support atomic operations, the LBaaS API v1.0 emulates the atomic behavior so that users can expect the same behavior regardless of the particular plugin running in the background.

LBaaS might be deployed without support for bulk operations and when the client attempts a bulk create operation, a 400 Bad Request error is returned.

For information about how to submit bulk requests to the LBaaS API v1.0, see the section called “Bulk Create Vips”.

Quotas

[tbd]

Notifications

[tbd]

Extensions

The LBaaS API v1.0 is extensible.

The purpose of LBaaS API v1.0 extensions is to:

  • Introduce new features in the API without requiring a version change.
  • Introduce vendor-specific niche functionality.
  • Act as a proving ground for experimental functionalities that might be included in a future version of the API.

To programmatically determine which extensions are available, issue a GET request on the /v1.0/extensions URI.

To query extensions individually by unique alias, issue a GET request on the /v1.0/extensions/alias_name URI. Use this method to easily determine if an extension is available. If the extension is not available, a 404 Not Found response is returned.

You can extend existing core API resources with new actions or extra attributes. Also, you can add new resources as extensions. Extensions usually have tags that prevent conflicts with other extensions that define attributes or resources with the same names, and with core resources and attributes. Because an extension might not be supported by all plugins, the availability of an extension varies with deployments and the specific plugin in use.

Faults

The LBaaS API v1.0 returns an error response if a failure occurs while processing a request. LBaaS uses only standard HTTP error codes. 4xx errors indicate problems in the particular request being sent from the client.

Error Description
400 Bad Request
404 Not Found
409 Conflict
413 Over limit
422 Immutable
500 Internal server error
503 Service unavailable

The response body of the error provides more detailed information on the error.

Users submitting requests to the LBaaS API v1.0 might also receive the following errors:

401 Unauthorized - If invalid credentials are provided.

403 Forbidden - If the user cannot access a specific resource or perform the requested operation.

API Operations

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

VIPs

Use the LBaaS API v1.0 to manage network resources

Verb URI
GET /v1.0/vips/
GET /v1.0/vips/vip_id
POST /v1.0/vips
PUT /v1.0/vips/vip_id
DELETE /v1.0/vips/vip_id

List VIPs

Verb URI Description
GET /v1.0/vips/

Normal Response Code(s): 200

Error Response Code: 401 (unauthorized)

Error Response body:

#!highlight javascript numbers=disable 
{  
  "error" : { 
               "error_code" : 401, 
               "error_message" : "The keystone token provided in the request header is invalid" 
           } 
}


Error Response Code: 500 (internal Service Error)

Error Response body:

#!highlight javascript numbers=disable 
{  
  "error" : { 
               "error_code" : 500, 
               "error_message" : "The LBaaS service has experience an internal error. Please contact support" 
           } 
}


Error Response Code: 503 (Service Unavailable)

Error Response body:

#!highlight javascript numbers=disable 
{  
  "error" : { 
               "error_code" : 503, 
               "error_message" : "The LBaaS service has currently unavailable. Please try later" 
           } 
}


This operation returns the list of all vips associated with your tenant account. If If you have an admin role, then this request returns all the vips of all tenants.

This operation does not require a request body.

This operation returns a response body. It returns a (potentially empty) list, each element in the list is a vip that can contain the following attributes:

  • id
  • tenant_id
  • name
  • network_id
  • address
  • port
  • lbmethod
  • protocol
  • pool_id
  • session_persistence
  • connection_limit
  • admin_state_up
  • status

Example . List vips JSON Request:

#!highlight javascript numbers=disable
GET /v1.0/vips
Host: lbaas-service.cloudX.com:8651
Accept: application/json
X-Auth-Token:887665443383838


JSON Response:

#!highlight javascript numbers=disable
200 OK
Content-Type: application/json
Content-Length: 384

{
  "vips":[
         {
           "id": "db902c0c-d5ff-4753-b465-668ad9656918",
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
           "name": "web_vip",
           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
           "address" : "10.30.176.47",
           "protocol": "HTTP",
           "port": 80,
           "lb_method": "ROUND_ROBIN",
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764", 
           "admin_state_up": true,
           "status": "ACTIVE"
         },
         {
           "id": "36e08a3e-a78f-4b40-a229-1e7e23eee1ab",
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
           "name": "db_vip",
           "network_id": "9cedb85d-0759-4898-8a4b-fa5a5ea10086",
           "address" : "10.30.176.48",
           "protocol": "TCP",
           "port": 3306,
           "lb_method": "LEAST_CONNECTIONS",
           "pool_id" : "41efe233-7591-43c5-9cf7-923964759f9e", 
           "session_persistence" : {"type" : "SOURCE_IP"},
           "connection_limit" : 2000,
           "admin_state_up": true,
           "status": "INACTIVE"
         }
      ]
}


List a vip's Details

Verb URI Description
GET /v1.0/vips/vip_id

Normal Response Code(s): 200

Error Response Code: 401

Error Response body:

#!highlight javascript numbers=disable 
{  
  "error" : { 
               "error_code" : 401, 
               "error_message" : "The keystone token provided in the request header is invalid" 
           } 
}


Error Response Code: 401

Error Response body:

#!highlight javascript numbers=disable 
{  
  "error" : { 
               "error_code" : 401, 
               "error_message" : "You are not authorized to access vip 36e08a3e-a78f-4b40-a229-1e7e23eee1ab" 
           } 
}


Error Response Code: 404

Error Response body:

#!highlight javascript numbers=disable 
{  
  "error" : { 
               "error_code" : 404, 
               "error_message" : "No vip with id 36e08a3e-a78f-4b40-a229-1e7e23eee1ab was found." 
           } 
}


Error Response Code: 500

Error Response body:

#!highlight javascript numbers=disable 
{  
  "error" : { 
               "error_code" : 500, 
               "error_message" : "The LBaaS service has experience an internal error. Please contact support" 
           } 
}


Error Response Code: 503

Error Response body:

#!highlight javascript numbers=disable 
{  
  "error" : { 
               "error_code" : 503, 
               "error_message" : "The LBaaS service has currently unavailable. Please try later" 
           } 
}


This operation returns a vip object associated with your tenant account.

This operation does not require a request body.

This operation returns a response body. The returned element is a vip that can contain the following attributes:

  • id
  • tenant_id
  • name
  • network_id
  • address
  • port
  • lb_method
  • protocol
  • pool_id
  • session_persistence
  • connection_limit
  • admin_state_up
  • status

Example . Retrieve a vip details:

JSON Request:

#!highlight javascript numbers=disable
GET /v1.0/vips/36e08a3e-a78f-4b40-a229-1e7e23eee1ab
Host: lbaas-service.cloudX.com:8651
Accept: application/json
X-Auth-Token:887665443383838


JSON Response:


#!highlight javascript numbers=disable
200 OK
Content-Type: application/json
Content-Length: 156

{
     "vip": {
           "id": "36e08a3e-a78f-4b40-a229-1e7e23eee1ab",
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
           "name": "db_vip",
           "network_id": "9cedb85d-0759-4898-8a4b-fa5a5ea10086",
           "address" : "10.30.176.47",
           "protocol": "TCP",
           "port": 3306,
           "lb_method": "LEAST_CONNECTIONS",
           "pool_id" : "41efe233-7591-43c5-9cf7-923964759f9e", 
           "session_persistence" : {"type" : "SOURCE_IP"},
           "connection_limit" : 2000,
           "admin_state_up": true,
           "status": "INACTIVE"
         }
}

Create a vip

Verb URI Description
POST /v1.0/vips

Normal Response Code(s): 202

Error Response Code(s): 401 (Unauthorized), 404 (Not Found), 409 (Conflict), 413 (Over limit), 500 (Internal server error), 503 (Service Unavailable)

This operation provisions a new vip 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 the status of provisioning the vip.

The status of the vip in the response can take one of the following values: ACTIVE, PENDING_CREATE or ERROR.

If the status returned is set to "PENDING_CREATE", then using the identifier of the vip, the caller can check on the progress of the provisioning operation by performing a GET on vips/vip_id. When the status of the vip returned changes to "ACTIVE", then the vip has been successfully provisioned and is now operational for traffic handling.

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

  • name
  • tenant_id: only if a user has an admin role can he specify a tenant_id different from her's.
  • network_id: The network on which to allocate the vip's address. A tenant can only create vips on networks authorized by policy (e.g. her own networks or shared/provider networks).
  • protocol: the protocol of the vip address.
  • port: the port on which to listen for client traffic that is associated with the vip address.
  • pool_id: the id of the pool that contains the real servers to which traffic is load balanced.

Some attributes will receive default values if not specified in the request:

  • lb_method: the default method is ROUND_ROBIN
  • admin_state_up: The default configuration state for a vip is UP, so the default value for this attribute is true.

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

Users with an admin role can create vips for other tenants by specifying a tenant_id attribute different than their own.

Example 4.6. Create a vip (Required Attributes) Request: JSON

Example . create a vip with a shared address JSON Request:

#!highlight javascript numbers=disable
POST /v1.0/vips
Host: lbaas-service.cloudX.com:8651
Content-Type: application/json
Accept: application/json
X-Auth-Token:887665443383838
Content-Length: 463

{
  "vips":[
         {
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
           "name": "web_vip",
           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
           "protocol": "HTTP",
           "port": 80,
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764"
         }
      ]
}


JSON Response:

#!highlight javascript numbers=disable
202 Accepted
Content-Type: application/json
Content-Length: 213

{
  "vips":[
         {
           "id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
           "name": "web_vip",
           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
           "address" : "10.30.176.47",
           "protocol": "HTTPS",
           "port": 443,
           "lb_method": "ROUND_ROBIN",
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764", 
           "admin_state_up": true,
           "status": "PENDING_CREATE"
         }
      ]
}


A user can supply an address field if she owns the network on which the vip will be created. If an address is not specified in the payload, then the LBaaS service will allocate one from the network ID.

Once an address is allocated to the user, the user can create other vip objects using the same address but with different ports.

Example . create a vip with an address shared with another vip JSON Request:

#!highlight javascript numbers=disable
POST /v1.0/vips
Host: lbaas-service.cloudX.com:8651
Content-Type: application/json
Accept: application/json
X-Auth-Token:887665443383838
Content-Length: 234

{
  "vips":[
         {
           "name": "ssl_vip",
           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
           "address" : "10.30.176.47",
           "protocol": "HTTPS",
           "port": 443,
           "pool_id" : "91c20e53-96cd-4476-8efc-627f398773bb"
         }
      ]
}


JSON Response:

#!highlight javascript numbers=disable
202 Accepted
Content-Type: application/json
Content-Length: 282

{
  "vips":[
         {
           "id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
           "name": "ssl_vip",
           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
           "address" : "10.30.176.47",
           "protocol": "HTTPS",
           "port": 443,
           "lb_method": "ROUND_ROBIN",
           "pool_id" : "91c20e53-96cd-4476-8efc-627f398773bb", 
           "admin_state_up": true,
           "status": "PENDING_CREATE"
         }
      ]
}


Update vip Attributes

Verb URI Description
PUT /1.0/vips/vip_id

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 vip. Upon successful validation of the request, the service will return a 202 (Accepted) response code. A caller should check that the vip status has changed to ACTIVE to confirm that the update has taken effect. If the vip status is "PENDING_UPDATE" then the caller can poll the vip with its ID (using a GET operation) to wait for the changes to be applied.

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

  • name
  • pool_id
  • lb_method
  • session_persistence
  • connection_limit
  • admin_state_up

This operation returns the updated vip object. The status of the vip in the response can take one of the following values: ACTIVE, PENDING_UPDATE or ERROR.


#!wiki caution
Note

The load balancer's ID, status, network_id, address, port and protocol are immutable attributes and cannot be modified once a vip is created. Supplying an unsupported attribute will result in a 400 (badRequest) fault.


Example . updating a vip JSON Request:

#!highlight javascript numbers=disable
PUT /v1.0/vips/02b1fef7-16f5-4917-bf19-c40a9af805ed
Host: lbaas-service.cloudX.com:8651
Content-Type: application/json
Accept: application/json
X-Auth-Token:887665443383838
Content-Length: 75

{
  "vip": {
           "name": "ssl_vip_1",
           "lb_method": "LEAST_CONNECTIONS",
           "session_persistence": { "type": "HTTP_COOKIE" } 
         }
}


JSON Response:

#!highlight javascript numbers=disable
202 Accepted
Content-Type: application/json
Content-Length: 282

{
  "vip": {
           "id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
           "name": "ssl_vip_1",
           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
           "address" : "10.30.176.47",
           "protocol": "HTTPS",
           "port": 443,
           "lb_method": "LEAST_CONNECTIONS",
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764", 
           "session_persistence": { "type": "HTTP_COOKIE" },
           "admin_state_up": true,
           "status": "PENDING_UPDATE"
         }
}


Table 4.1. vip Statuses

Name
ACTIVE
PENDING_CREATE
PENDING_UPDATE
PENDING_DELETE
INACTIVE
ERROR

Remove a vip

Verb URI Description
DELETE /v1.0/vips/vip_id Remove a vip 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 vip function removes the specified vip 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.

Example . Deleting a vip JSON Request:

#!highlight javascript numbers=disable
DELETE /v1.0/vips/02b1fef7-16f5-4917-bf19-c40a9af805ed
Host: lbaas-service.cloudX.com:8651
Accept: application/json
X-Auth-Token:887665443383838


JSON Response:

#!highlight javascript numbers=disable
202 Accepted


Pools

A pool is a container of a set of members to which the traffic is load-balanced. The pool construct is a way to share several configuration attributes between members that belong to the same pool. For example health monitors are configured on the pool, and all members of the same pool, will be monitored using these health monitors.

Each vip object can be associated with one pool. A pool cannot be used by more than one vip.

List Pools

Verb URI Description
GET /v1.0/pools

List all pools of a tenant.

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 pools Request: JSON Request:

#!highlight javascript numbers=disable
GET /v1.0/pools
Host: lbaas-service.cloudX.com:8651
Accept: application/json
X-Auth-Token:887665443383838


Example. List pools Response: JSON

#!highlight javascript numbers=disable
200 OK
Content-Type: application/json
Content-Length: 628

{
  "pools" : [
              {
                "id":"cfc6589d-f949-4c66-99d2-c2da56ef3764",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "vip_id": "db902c0c-d5ff-4753-b465-668ad9656918",
                "name": "web_pool",
                "protocol": "HTTP",
                "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
                "members" : [ 
                              "c57f581b-c834-408f-93fa-30543cf30618",  
                              "f2e37304-e3c1-4f96-9201-dd57a16adb75", 
                              "cd701b32-7f55-4e8b-94a0-756cd85a684d" 
                            ],
                "health_monitors" : [
                                     "954171e2-8816-4d59-a9d5-c85310b4508d"
                                    ],
                "admin_state_up" : true,
                "status" : "ACTIVE"
              },
              {
                "id":"91c20e53-96cd-4476-8efc-627f398773bb",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "vip_id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
                "protocol": "HTTPS",
                "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
                "members" : [ 
                              "fcbf4e80-2fc7-4c7a-8a2e-8ea929620df9",  
                              "6ea4761c-f571-4ec8-a6ae-6a4baf7e49d", 
                              "26c49527-999c-4ef5-9484-5c065414d3db" 
                            ],
                "health_monitors" : [
                                     "3b4ee887-fff5-4e45-ac55-c34ee599061a"
                                   ],
                "admin_state_up" : true,
                "status" : "ACTIVE"
              },
              {
                "id":"41efe233-7591-43c5-9cf7-923964759f9e",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "vip_id": "36e08a3e-a78f-4b40-a229-1e7e23eee1ab",
                "protocol": "TCP",
                "network_id" : "ddc3ab81-1dac-4be3-a340-c7b7b5d89beb",
                "members" : [ 
                              "a24a6159-fc0f-4f42-ab10-5fe8763fef6e",  
                              "8c65956d-8f3c-41a4-abc3-5311eb3b4ba9" 
                            ],
                "health_monitors" : [
                                     "65479d91-36f4-4651-89c2-2daee22a3c78",
                                     "441d3298-bf31-4c3b-8433-7e93a7a3db16"
                                   ],
                "admin_state_up" : true,
                "status" : "ACTIVE"
              }
            ]
}

Retrieve a pool

Verb URI Description
GET /v1.0/pools/pool_id

This operation retrieves the configuration of a pool.

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 pool

JSON Request:

#!highlight javascript numbers=disable
GET /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764
Host: lbaas-service.cloudX.com:8651
Accept: application/json
X-Auth-Token:887665443383838


Example. List pools Response: JSON

#!highlight javascript numbers=disable
200 OK
Content-Type: application/json
Content-Length: 628

{
  "pool" : {
         "id":"cfc6589d-f949-4c66-99d2-c2da56ef3764",
         "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
         "vip_id": "db902c0c-d5ff-4753-b465-668ad9656918",
         "name": "web_pool",
         "protocol": "HTTP",
         "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
         "members" : [ 
                      "c57f581b-c834-408f-93fa-30543cf30618",  
                      "f2e37304-e3c1-4f96-9201-dd57a16adb75", 
                      "cd701b32-7f55-4e8b-94a0-756cd85a684d" 
                     ],
         "health_monitors" : [
                               "954171e2-8816-4d59-a9d5-c85310b4508d"
                             ],
         "admin_state_up" : true,
         "status" : "ACTIVE"
  }
}


Add Pools

Verb URI Description
POST /v1.0/pools Add a new pool

Normal Response Code(s): 202

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

When a pool is added, it is assigned a unique identifier which can be used for querying, changing or deleting it. Optionally, you can also assign the pool to a vip during creation time, by specifying the vip_id attribute.

If a user has an admin role, she can create pools for other tenant by specifying the tenant_id attribute in the request payload.

Example 4.15. Creating a pool

JSON Request:

#!highlight javascript numbers=disable
POST /v1.0/pools
Host: lbaas-service.cloudX.com:8651
Accept: application/json
Content-Type: application/json
X-Auth-Token:887665443383838
Content-Length: 194

{
  "pools" : [
         {
            "name": "web_pool",
            "vip_id": "db902c0c-d5ff-4753-b465-668ad9656918",
            "protocol": "HTTP",
            "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
            "members" : [ 
                          "c57f581b-c834-408f-93fa-30543cf30618",  
                          "f2e37304-e3c1-4f96-9201-dd57a16adb75"
                        ]
        }
   ]
}


JSON Response

#!highlight javascript numbers=disable
202 Accepted
Content-Type: application/json
Content-Length: 275

{
  "pools" : [
           {
            "id":"cfc6589d-f949-4c66-99d2-c2da56ef3764",
            "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
            "vip_id": "db902c0c-d5ff-4753-b465-668ad9656918",
            "name": "web_pool",
            "protocol": "HTTP",
            "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
            "members" : [ 
                          "c57f581b-c834-408f-93fa-30543cf30618",  
                          "f2e37304-e3c1-4f96-9201-dd57a16adb75"
                        ],
            "admin_state_up" : true,
            "status" : "PENDING_CREATE"
          }
        ]
}


Modify Pools

Verb URI
PUT /v1.0/pools/pool_id

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.

Example 4.21. Update name of the pool

JSON Request:

#!highlight javascript numbers=disable
PUT /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764
Host: lbaas-service.cloudX.com:8651
Accept: application/json
Content-Type: application/json
X-Auth-Token:887665443383838
Content-Length: 194

{
  "pool" : {
            "name": "web_pool_1"
           }
}


JSON Response

#!highlight javascript numbers=disable
202 Accepted
Content-Type: application/json
Content-Length: 269

{
  "pool" : {
            "id":"cfc6589d-f949-4c66-99d2-c2da56ef3764",
            "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
            "vip_id": "db902c0c-d5ff-4753-b465-668ad9656918",
            "name": "web_pool_1",
            "protocol": "HTTP",
            "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
            "members" : [ 
                          "c57f581b-c834-408f-93fa-30543cf30618",  
                          "f2e37304-e3c1-4f96-9201-dd57a16adb75"
                        ],
            "admin_state_up" : true,
            "status" : "PENDING_UPDATE"
          }
}


Remove Pools

Verb URI Description
DELETE /pools/pool_id Removes a pool.

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

Attempting to remove a pool that is used in a vip will result in a badRequest (400) error. First remove the pool from the vip, then you can remove the pool.


Example 4.21. Removing a pool

JSON Request:

#!highlight javascript numbers=disable
DELETE /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764
Host: lbaas-service.cloudX.com:8651
Accept: application/json
X-Auth-Token:887665443383838


JSON Response

#!highlight javascript numbers=disable
202 Accepted


#!wiki caution
Note

A pool that is pending to be deleted cannot be updated.


Members

The members of a pool are responsible for servicing the requests received through the vip's virtual IP. The load-balancing method is used to distribute requests or connections between the pool members.

The weight of a member determines the portion of requests or connections it services compared to the other members of the pool. For example, if member A has a weight of 2 and member B has a weight of 1, then member A will service twice as many requests as member B. If the weight attribute is not specified, then the member's weight is implicitly set to "1".

List all members

Verb URI
GET /v1.0/members

List all members of all pools for a tenant.

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: Listing all members

JSON Request:

#!highlight javascript numbers=disable
GET /v1.0/members
Host: lbaas-service.cloudX.com:8651
Accept: application/json
X-Auth-Token:887665443383838


JSON Response:

#!highlight javascript numbers=disable
200 OK
Content-Type: application/json
Content-Length: 917

{
  "members" : [
              {
                "id":"c57f581b-c834-408f-93fa-30543cf30618",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
                "address": "192.168.224.31",
                "port": 8080,
                "weight" : 1,
                "admin_state_up" : true,
                "status" : "ACTIVE"
              },
              {
                "id":"f2e37304-e3c1-4f96-9201-dd57a16adb75",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
                "address": "192.168.224.32",
                "port" : 8081,
                "weight": 2,
                "admin_state_up" : true,
                "status" : "ACTIVE"
              },
              {
                "id":"cd701b32-7f55-4e8b-94a0-756cd85a684d",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
                "address": "192.168.224.35"
                "port": 8080,
                "weight" : 1,
                "admin_state_up" : false,
                "status" : "INACTIVE"
              },
              {
                "id":"fcbf4e80-2fc7-4c7a-8a2e-8ea929620df9",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "91c20e53-96cd-4476-8efc-627f398773bb",
                "address": "192.168.137.61",
                "port": 8443,
                "weight" : 1,
                "admin_state_up" : true,
                "status" : "ACTIVE"
              },
              {
                "id":"6ea4761c-f571-4ec8-a6ae-6a4baf7e49d",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "91c20e53-96cd-4476-8efc-627f398773bb",
                "address": "192.168.137.62",
                "port": 8443,
                "weight" : 1,
                "admin_state_up" : true,
                "status" : "ACTIVE"
              },
              {
                "id":"26c49527-999c-4ef5-9484-5c065414d3db",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "91c20e53-96cd-4476-8efc-627f398773bb",
                "address": "192.168.137.63",
                "port": 8443,
                "weight" : 1,
                "admin_state_up" : true,
                "status" : "ACTIVE"
              },
              {
                "id":"a24a6159-fc0f-4f42-ab10-5fe8763fef6e",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "41efe233-7591-43c5-9cf7-923964759f9e",
                "address": "192.168.200.114",
                "port": 3306,
                "weight" : 1,
                "admin_state_up" : true,
                "status" : "ACTIVE"
              },
              {
                "id":"8c65956d-8f3c-41a4-abc3-5311eb3b4ba9",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "41efe233-7591-43c5-9cf7-923964759f9e",
                "address": "192.168.200.132",
                "port": 3306,
                "weight" : 1,
                "admin_state_up" : true,
                "status" : "INACTIVE"
              }
            ]
}


List members of a pool

Verb URI
GET /v1.0/pools/pool_id/members

List all members of a specific pool.

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: Listing all members

JSON Request:

#!highlight javascript numbers=disable
GET /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764/members
Host: lbaas-service.cloudX.com:8651
Accept: application/json
X-Auth-Token:887665443383838


JSON Response:

#!highlight javascript numbers=disable
200 OK
Content-Type: application/json
Content-Length: 917

{
  "members" : [
              {
                "id":"c57f581b-c834-408f-93fa-30543cf30618",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
                "address": "192.168.224.31",
                "port": 8080,
                "weight" : 1,
                "admin_state_up" : true,
                "status" : "ACTIVE"
              },
              {
                "id":"f2e37304-e3c1-4f96-9201-dd57a16adb75",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
                "address": "192.168.224.32",
                "port" : 8081,
                "weight": 2,
                "admin_state_up" : true,
                "status" : "ACTIVE"
              },
              {
                "id":"cd701b32-7f55-4e8b-94a0-756cd85a684d",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
                "address": "192.168.224.35"
                "port": 8080,
                "weight" : 1,
                "admin_state_up" : false,
                "status" : "INACTIVE"
              }
            ]
}


Retrieve a member

Verb URI Description
GET /members/member_id

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. Retrieve the configuration of a member

JSON Request:

#!highlight javascript numbers=disable
GET /v1.0/members/c57f581b-c834-408f-93fa-30543cf30618
Host: lbaas-service.cloudX.com:8651
Accept: application/json
X-Auth-Token:887665443383838


JSON Response:

#!highlight javascript numbers=disable
200 OK
Content-Type: application/json
Content-Length: 917

{
  "member" :  {
                "id":"c57f581b-c834-408f-93fa-30543cf30618",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
                "address": "192.168.224.31",
                "port": 8080,
                "weight" : 1,
                "admin_state_up" : true,
                "status" : "ACTIVE"
              }
}


Add members

Verb URI Description
POST /v1.0/members Add members to pools.

Normal Response Code(s): 202

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

When a member is added, it is assigned a unique identifier that can be used for mutating operations such as changing the admin_state or the weight of a member, or removing the member from the pool.


#!wiki caution
Note:

When a member is added to a load balancer, it is enabled by default (admin_state_up = true).


Example 4.17. Add members

In this example, we add the first 2 members to one pool and the third member to a second pool.

JSON Request:

#!highlight javascript numbers=disable
POST /v1.0/members
Host: lbaas-service.cloudX.com:8651
Accept: application/json
Content-Type: application/json
X-Auth-Token:887665443383838
Content-Length: 826

{
  "members" : [
              {
                "address": "192.168.224.31",
                "port": 8080,
                "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764"
              },
              {
                "address": "192.168.224.32",
                "port" : 8081,
                "weight" : 2,
                "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764"
              },
              {
                "address": "192.168.137.61",
                "port": 8443,
                "pool_id": "91c20e53-96cd-4476-8efc-627f398773bb"
              }
            ]
}


JSON Response:

#!highlight javascript numbers=disable
200 OK
Content-Type: application/json
Content-Length: 917

{
  "members" : [
              {
                "id":"c57f581b-c834-408f-93fa-30543cf30618",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
                "address": "192.168.224.31",
                "port": 8080,
                "weight" : 1,
                "admin_state_up" : true,
                "status" : "PENDING_CREATE"
              },
              {
                "id":"f2e37304-e3c1-4f96-9201-dd57a16adb75",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
                "address": "192.168.224.32",
                "port" : 8081,
                "weight" : 2,
                "admin_state_up" : true,
                "status" : "PENDING_CREATE"
              },
              {
                "id":"fcbf4e80-2fc7-4c7a-8a2e-8ea929620df9",
                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
                "pool_id": "91c20e53-96cd-4476-8efc-627f398773bb",
                "address": "192.168.137.61",
                "port": 8443,
                "weight" : 1,
                "admin_state_up" : true,
                "status" : "PENDING_CREATE"
              }
            ]
}


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.