Latest revision as of 15:54, 21 June 2013

OpenStack LBaaS API 1.0

Overview

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 service, the OpenStack Quantum service, and the integration between the two.

You should also be familiar with:

ReSTful web services
HTTP/1.1
JSON serialization format

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

tbd

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:

 <tbd>

High-Level Task Flow

The high-level task flow for using LBaaS API to configure load balancing is as follows:

The tenant creates a pool, which is initially empty
The tenant create one or several members in the pool
The tenant create one or several health monitors
The tenant associates the health monitors with the pool
The tenant creates a vip with the pool

Concepts

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

VIP

A VIP is the primary load balancing configuration object that specifies the virtual IP address and port on which client traffic is received, as well as other details such as the load balancing method to be use, protocol, etc. This entity is sometimes known in LB products under the name of a "virtual server", a "vserver" or a "listener".

Pool

A load balancing pool is a logical set of devices, such as web servers, that you group together to receive and process traffic. The loadbalancing function chooses a member of the pool according to the configured load balancing method to handle the new requests or connections received on the VIP address. There is only one pool for a VIP.

Pool Member

A pool member represents the application running on backend server.

Health Monitoring

A health monitor is used to determine whether or not back-end members of the VIP's pool are usable for processing a request. A pool can have several health monitors associated with it. There are different types of health monitors supported by the OpenStack LBaaS service:

PING: used to ping the members using ICMP.
TCP: used to connect to the members using TCP.
HTTP: used to send an HTTP request to the member.
HTTPS: used to send a secure HTTP request to the member.

Session Persistence

Session persistence is a feature of the load balancing service. It attempts to force connections or requests in the same session to be processed by the same member as long as it is ative. The OpenStack LBaaS service supports three types of persistence:

SOURCE_IP: With this persistence mode, all connections originating from the same source IP address, will be handled by the same member of the pool.
HTTP_COOKIE: With this persistence mode, the loadbalancer will create a cookie on the first request from a client. Subsequent requests containing the same cookie value will be handled by the same member of the pool.
APP_COOKIE: With this persistence mode, the loadbalancer will rely on a cookie established by the backend application. All requests carrying the same cookie value will be handled by the same member of the pool.

Connection Limits

To control incoming traffic on the VIP address as well as traffic for a specific member of a pool, you can set a connection limit beyond which the load balancing function will refuse client requests or connections. This can be used to thwart DoS attacks and to allow each member to continue to work within its limits.

For HTTP and HTTPS protocols, since several HTTP requests can be multiplexed on the same TCP connection, the connection limit value is interpreted as the maximum number of requests allowed.

Chapter 2. 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.

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.This means that for requests that contain a body, the Content-Type header must be set to the MIME type value "application/json". Also, clients must accept JSON serialized responses by specifying the Accept header with the MIME type value "application/json" or adding ".json" extension to the resource name.

Example:

#!highlight javascript numbers=disable
GET /v1.0/vips.json

or

#!highlight javascript numbers=disable
GET /v1.0/vips
Accept: application/json

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:

#!highlight javascript numbers=disable
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.

#!wiki caution
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:

#!highlight javascript numbers=disable
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, the member or the health monitor 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.

The LBaaS service 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 Members” section.

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. So, make sure that your extension is available on the deployed LBaaS service before making use of its extra features.

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

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.

The response body will contain richer information about the cause of the error. An error response follows the format illustrated by the following example:

#!highlight javascript numbers=disable
409 Conflict
Content-type: application/json
Content-lentgh:78

{
   "errorcode": 409,
   "errormessage": "pool is already used by an existing VIP"
}

Chapter 3. 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 all VIPs

Verb	URI	Description
GET	/v1.0/vips/

Normal Response Code(s): 202

Error Response Code(s): 401 (Unauthorized), 500 (Internal server error), 503 (Service Unavailable)

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
description
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",
           "description": "lb config for the web tier",
           "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"
         }
      ]
}

Retrieve a specific VIP

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

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 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
description
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",
           "description": "lb config for the MYSQL db tier",
           "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 a VIP

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
description
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",
           "description": "this VIP is used for secure web connections",
           "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 all 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 specific 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" : [
                               "f784c3a7-c4e8-44da-bf12-5ff417d27555"
                             ],
         "admin_state_up" : true,
         "status" : "ACTIVE"
  }
}

Create a Pool

Verb	URI
POST	/v1.0/pools

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

Update a Pool

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

Verb

URI

DELETE

/pools/pool_id

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.

Pool 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 all Members of a specific 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 specific 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"
              }
}

Bulk Create 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"
              }
            ]
}

Update a Member

Verb	URI	Description
PUT	/v1.0/members/member_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.

#!wiki caution
Note

The member's address 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 pool supports a
maximum number of nodes. The maximum number of nodes per pool is returned when querying the limits of the LBaaS service.

Every member in the pool is either enabled or disabled which determines its role within the pool using the admin_state_up attribute. When the member has admin_state_up=true, the member is permitted to accept new connections or requests. Its status will eventually become ACTIVE to reflect this configuration. When the member has admin_state_up=false, the member is not permitted to accept any new connections or requests regardless of session persistence configuration. Existing connections to the node are gracefully drained or forcibly terminated. The member's status changes to INACTIVE once the configuration has been successfully applied.

Example 4.21. Disable a member

JSON Request:

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

{
  "member" :  {
                "admin_state_up": false
              }
}

JSON Response:

#!highlight javascript numbers=disable
202 ACCEPTED
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" : false,
                "status" : "PENDING_UPDATE"
             }
}

Remove a Member

Verb	URI	Description
DELETE	/v1.0/members/member_id	Removes a member from 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.

Example 4.21. remove a member from its pool

JSON Request:

#!highlight javascript numbers=disable
DELETE /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
202 Accepted

Health Monitors

Verb	URI
GET	/v1.0/healthmonitors/
GET	/v1.0/healthmonitors/healthmonitor_id
PUT	/v1.0/healthmonitors/healthmonitor_id	Update the settings for a health monitor.
DELETE	/v1.0/healthmonitors/healthmonitor_id	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)

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

PING

TCP

HTTP

HTTPS

The required attributes to specify when creating a health monitor depend on the health monitor type.

Create a PING Health Monitor

The monitor pings the member to ensure that the member is alive.

The PING monitor is the most basic type of health check. The following configurable properties can be specified

delay: This is the minimum time in seconds between regular pings of the member.
timeout: Maximum number of seconds for a monitor to wait for a ping reply before it times out. The value must be less than the delay value.
attemptsBeforeDeactivation: Number of permissible ping failures before changing the member's status to INACTIVE. Must be a number between 1 and 10.

Example 4.27. Monitor PING

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

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

JSON Response:

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

{
    "healthmonitor" :
      {
         "id" : "f784c3a7-c4e8-44da-bf12-5ff417d27555",
         "type" : "PING",
         "delay" : 20,
         "timeout": 10,
         "attemptsBeforeDeactivation": 3,
         "admin_state_up": true,
         "status": "PENDING_CREATE"
      }
}

Create a TCP Health Monitor

A TCP monitor tries to establish a TCP connection to the member to ensure that the member is healthy.

The following configurable properties can be specified for a TCP monitor:

delay: This is the minimum time in seconds between regular connections of the member.
timeout: Maximum number of seconds for a monitor to wait for a connection to be established before it times out. The value must be less than the delay value.
attemptsBeforeDeactivation: Number of permissible connection failures before changing the member's status to INACTIVE. Must be a number between 1 and 10.

Example. Monitor TCP

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

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

JSON Response:

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

{
    "healthmonitor" :
      {
         "id" : "e5069610-744b-42a7-8bd8-ceac1a229cd4",
         "type" : "TCP",
         "delay" : 20,
         "timeout": 10,
         "attemptsBeforeDeactivation": 3,
         "admin_state_up": true,
         "status": "PENDING_CREATE"

      }
}

Create an HTTP or an HTTPS Health Monitor

The HTTP and HTTPS monitor is more intelligent than the TCP 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 TCP 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 used by the monitor to test a member's health. 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. Monitor TCP

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

{
    "healthmonitor" :
      {
         "type" : "HTTP",
         "delay" : 20,
         "timeout": 10,
         "attemptsBeforeDeactivation": 3,
         "path" : "/check",
         "error_codes" : "200-299"
      }
}

JSON Response:

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

{
    "healthmonitor" :
      {
         "id" : "f3eeab00-8367-4524-b662-55e64d4cacb5",
         "type" : "HTTP",
         "delay" : 20,
         "timeout": 10,
         "attemptsBeforeDeactivation": 3,
         "path" : "/check",
         "error_codes" : "200-299",
         "admin_state_up": true,
         "status": "PENDING_CREATE"
      }
}

Associate and Dissociate Health Monitors with Pools

When a health monitor has been created, it can be associated with one or several pools.

Verb	URI
GET	/v1.0/pools/pool_id/healthmonitors
POST	/v1.0/pools/pool_id/healthmonitors
DELETE	/v1.0/pool_id/pool_id/healthmonitors/healthmonitor_id	Dissociates a healthmonitor from a pool.

Normal Response Code(s): 200, 202

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

List all Health Monitors associated with a Pool

Example. List health monitors for a pool

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

JSON Response:

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

{
    "healthmonitors" : [
                         "f784c3a7-c4e8-44da-bf12-5ff417d27555",
                         "e5069610-744b-42a7-8bd8-ceac1a229cd4"
                       ]
}

Associate Health Monitors with a Pool

You can associate one or several health monitors with a pool. Once associated, the health monitors will start monitoring the members of the pool and will deactivate these members if they are deemed unhealthy. A member can be disactivated (status set to INACTIVE) if any of health monitors finds its unhealthy.

The response will return the current list of all health monitors associated with the pool.

Example. Add a health monitor to the monitors for a pool

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

{
    "healthmonitors" : [
                         "f3eeab00-8367-4524-b662-55e64d4cacb5"
                       ]
}

JSON Response:

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

{
    "healthmonitors" : [
                         "f784c3a7-c4e8-44da-bf12-5ff417d27555",
                         "e5069610-744b-42a7-8bd8-ceac1a229cd4",
                         "f3eeab00-8367-4524-b662-55e64d4cacb5"
                       ]
}

Note that the pool status will change to PENDING_UPDATE while the association is processed. A pool status of ACTIVE indicates that the change has successfully taken place.

Dissociate Health Monitors from a Pool

you can dissociate a health monitor from a pool. When dissociation is successful, the health monitor will no longer check for the health of the members of the pool.

Note that the pool status will change to PENDING_UPDATE while the dissociation is processed. A pool status of ACTIVE indicates that the change has successfully taken place.

Example. Dissociate a health monitor from a pool

#!highlight xml numbers=disable
DELETE /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764/healthmonitors/f3eeab00-8367-4524-b662-55e64d4cacb5
Host: lbaas-service.cloudX.com:8651
Accept: application/json
X-Auth-Token:887665443383838

JSON Response:

#!highlight xml numbers=disable
202 Accepted

Statistics

List Traffic Statistics of a pool

Name	URI	Description
GET	/v1.0/pools/pool_id/stats

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 pool stats reports provide a set of stats counters. This list will contain at least the following counters:

bytes_in: The total number of bytes that pool members have received from clients.
bytes_out: The total number of bytes that pool members have sent to clients.
active_connections: The current number of active connections being served by the pool members.
total_connections: The total number of connections that have been processed by the pool members.

Example 4.25. Retrieve the stats for a pool

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

JSON Response:

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

{
    "stats" : {
                         "bytes_in" : 36839202,
                         "bytes_out" : 673193022,
                         "active_connections" : 39,
                         "total_connections" : 682
              }
}

Protocols

List Supported Load Balancing Protocols

Verb	URI
GET	/v1.0/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 vips and members must be configured with a protocol value from this list. The vip's protocol and the pool's protocol must be compatible with each other, which in this version of the API specification means that they have to be identical.

All LBaaS implementations of this specification must support at least the following protocols:

TCP
HTTP
HTTPS

When the protocol is HTTPS, the traffic received on the vip is SSL-encrypyted and will be forwaded as is to the pool members. The traffic is not decrypted by the load balancers. Because, requests are opaque, the HTTP_COOKIE session persistence cannot be configured when the vip's protocol is HTTPS.

Example: Listing protocols supported

#!highlight javascript numbers=disable
{
 "protocols": [
               {
                 "name": "TCP",
               },
               {
                 "name": "HTTP",
               },
               {
                 "name": "HTTPS",
               }
              ]
}

LB Methods

All LB methods utilize an algorithm that defines how a member is chosen to process a new request or a connection that arrives on a vip. The default algorithm for newly created vips is ROUND_ROBIN, which can be overridden at creation time or changed after the vip 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

Listing Supported Load Balancing Methods

Verb	URI
GET	/v1.0/lb_methods

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 javascript numbers=disable
200 OK
Content-type: application/json
Content-length: 362

{
   "lb_methods": [
                  {
                    "name": "ROUND_ROBIN"
                  },
                  {
                    "name": "LEAST_CONNECTIONS"
                  }
                 ]
}

@@ Line 1: / Line 1: @@
-__NOTOC__
+= OpenStack LBaaS API 1.0 =
-<!-- #acl [[YoucefLaribi]]:read,write,delete,revert,admin [[UmaGoring]]:read,write,delete,revert,admin All:read -->
-<pre><nowiki>#!wiki caution
-'''Note'''
-If you want to discuss changes to this spec or found an error, please contact youcef.laribi AT citrix.com
-</nowiki></pre>
-= [[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.
+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 service, the [[OpenStack]] Quantum service, and the integration between the two.
 You should also be familiar with:
@@ Line 21: / Line 10: @@
 * ReSTful web services
 * HTTP/1.1
-* JSON and XML data serialization formats
+* JSON serialization format
 === 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:
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Revision Date'''
 |-
-| Oct,25 2012
+| Oct, 25 2012
 |}
 === Resources ===
 Use the following resources in conjunction with this guide:
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Resource'''
 |-
-|
+| tbd
 |}
-= Chapter 1. Overview =
+== 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 ---
+  <tbd>
-== Glossary ==
+=== High-Level Task Flow ===
+The high-level task flow for using LBaaS API to configure load balancing is as follows:
-{| border="1" cellpadding="2" cellspacing="0"
+* The tenant creates a pool, which is initially empty
-| '''Term'''
+* The tenant create one or several members in the pool
-|-
+* The tenant create one or several health monitors
-|
+* The tenant associates the health monitors with the pool
-|}
+* The tenant creates a vip with the pool
-== Concepts ==
+=== Concepts ===
 To use OpenStack LBaaS APIs effectively, you should understand several key concepts:
-=== VIP ===
+==== 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.
+A VIP is the primary load balancing configuration object that specifies the virtual IP address and port on which client traffic is received, as well as other details such as the load balancing method to be use, protocol, etc. This entity is sometimes known in LB products under the name of a "virtual server", a "vserver" or a "listener".
-This is the primary entity of configuration in the API.
-=== Pool ===
+==== 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.
+A load balancing pool is a logical set of devices, such as web servers, that you group together to receive and process traffic. The loadbalancing function chooses a member of the pool according to the configured load balancing method to handle the new requests or connections received on the VIP address. There is only one pool for a VIP.
-=== Member ===
+==== Pool 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.
+A pool member represents the application running on backend server.
-=== Health Monitoring ===
+==== 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.
+A health monitor is used to determine whether or not back-end members of the VIP's pool are usable for processing a request. A pool can have several health monitors associated with it. There are different types of health monitors supported by the [[OpenStack]] LBaaS service:
-The following types of health monitors are available for use:
+* PING: used to ping the members using ICMP.
+* TCP: used to connect to the members using TCP.
+* HTTP: used to send an HTTP request to the member.
+* HTTPS: used to send a secure HTTP request to the member.
-* PING
+==== Session Persistence ====
-* TCP
+Session persistence is a feature of the load balancing service. It attempts to force connections or requests in the same session to be processed by the same member as long as it is ative. The [[OpenStack]] LBaaS service supports three types of persistence:
-* HTTP
-* HTTPS
-=== Session Persistence ===
+* SOURCE_IP: With this persistence mode, all connections originating from the same source IP address, will be handled by the same member of the pool.
-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.
+* HTTP_COOKIE: With this persistence mode, the loadbalancer will create a cookie on the first request from a client. Subsequent requests containing the same cookie value will be handled by the same member of the pool.
-The [[OpenStack]] LBaaS service supports SOURCE IP and COOKIE persistence.
+* APP_COOKIE: With this persistence mode, the loadbalancer will rely on a cookie established by the backend application. All requests carrying the same cookie value will be handled by the same member of the pool.
-== General API Information ==
+==== Connection Limits ====
-Sections in this chapter describe operations and guidelines that are common to all OpenStack APIs, and are not specific to the Load Balancing API.
+To control incoming traffic on the VIP address as well as traffic for a specific member of a pool, you can set a connection limit beyond which the load balancing function will refuse client requests or connections. This can be used to thwart DoS attacks and to allow each member to continue to work within its limits.
-=== Service Access/Endpoints ===
+For HTTP and HTTPS protocols, since several HTTP requests can be multiplexed on the same TCP connection, the connection limit value is interpreted as the maximum number of requests allowed.
-Your service provider will publish the endpoints that you can use to connect to the LB service it operates.
-=== Request/Response Types ===
+== Chapter 2. General API Information ==
-The LBaaS API supports both the JSON and XML data serialization formats. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using either the Accept header or  adding an .xml or .json extension to the request URI. Note that it is possible for a response to be serialized using a format different from the request. If no response format is specified, JSON is the default. If conflicting formats are specified using both an Accept header and a query extension, the query extension takes precedence.
+Sections in this chapter describe operations and guidelines that are common to all OpenStack APIs, and are not specific to the Load Balancing API.
-'''Table 3.1. JSON and XML Response Formats '''
+=== Authentication and Authorization ===
-{| border="1" cellpadding="2" cellspacing="0"
+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.
-| '''Format'''
-| '''Accept Header'''
-| '''Query Extension'''
-|-
-| JSON
-| application/json
-| .json
-|-
-| XML
-| application/xml
-| .xml
-|}
-=== Paginated Collections ===
+The default authorization settings allow only administrative users to create resources on behalf of a different tenant.
-To reduce load on the service, list operations will return a maximum of 100 items at a time. To navigate the collection, the limit and marker parameters (for example, ?limit=50&marker=1) can be set in the URI. If a marker beyond the end of a list is given, an empty list is returned. Note that list operations never return 404 ('''itemNotFound''') faults.
-=== Limits ===
+LBaaS uses information received from Keystone to authorize user requests. LBaaS handles the following types of authorization policies:
-Accounts may be preconfigured with a set of thresholds (or limits) to manage capacity and prevent abuse of the system. The system recognizes two kinds of limits: rate limits and absolute limits. Rate limits are thresholds that are reset after a certain amount of time passes. Absolute limits are fixed.
-==== Rate Limits ====
+Operation-based policies
-We specify rate limits in terms of both a human-readable wild-card URI and a machine-processable regular expression. The regular expression boundary matcher '^' takes effect after the root URI path. For example, the regular expression/v1.1/1234/loadbalancers would match the bold portion of the following URI: <code><nowiki>https://loadbalancers.api.openstack.org</nowiki></code>'''<code><nowiki>/v1.1/1234/loadbalancers</nowiki></code>'''.
-'''Table 3.3. Default Rate Limits'''
+Specify access criteria for specific operations, possibly with fine-grained control over specific attributes.
-{| border="1" cellpadding="2" cellspacing="0"
-| '''Verb'''
-| '''URI'''
-| '''RegEx'''
-|-
-| GET
-| /v1.1/*
-| ^/1.1/.*
-|-
-| POST
-| /v1.1/*
-| ^/1.1/.*
-|-
-| POST
-| /v1.1/*
-| ^/1.1/.*
-|-
-| PUT
-| /v1.1/*
-| ^/1.1/.*
-|-
-| DELETE
-| /v1.1/*
-| ^/1.1/.*
-|}
-Rate limits are applied in order relative to the verb, going from least to most specific. For example, although the threshold for POST to /v1.1/* is 25 per minute, one cannot POST to /v1.1/* more than 2 times per second because the rate limit for any POST is 2 per second. In the event you exceed the thresholds established for your account, a 413 (Rate Control) HTTP response will be returned with a Retry-After header to notify the client when they can attempt to try again.
+Resource-based policies
-==== Absolute Limits ====
+Access a specific resource. Permissions might or might not be granted depending on the permissions configured for the resource.
-Absolute limits are specified as name/value pairs. Then name of the absolute limit uniquely identifies the limit within a deployment. For example '''maxNodesPerLoadbalancer''' identifies the total number of nodes that may be associated with a given load balancer.
-The following table shows some of these limits and example values:
+=== Request/Response Types ===
-{| border="1" cellpadding="2" cellspacing="0"
+The LBaaS API v1.0 supports the JSON data serialization format.This means that for requests that contain a body, the Content-Type header must be set to the MIME type value "application/json". Also, clients must accept JSON serialized responses by specifying the Accept header with the MIME type value "application/json" or adding ".json" extension to the resource name.
-| '''Name'''
-| '''Value'''
-|-
-| maxLoadBalancers
-| 20
-|-
-| maxNodesPerLoadBalancer
-| 5
-|-
-| maxVIPsPerLoadBalancer
-| 1
-|-
-| maxDaysKeptForDeletedLoadBalancers
-| 15
-|-
-| maxLoadBalancerNameLength
-| 15
-|}
-==== Determining Limits Programmatically ====
+Example:
-Applications can programmatically determine current account limits using the /limits URI as  follows:
-{| border="1" cellpadding="2" cellspacing="0"
-| '''Verb'''
-| '''URI'''
-|-
-| GET
-| /limits
-|}
-'''Normal Response Code(s)''': 200
-'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+<pre><nowiki>#!highlight javascript numbers=disable
+GET /v1.0/vips.json
+</nowiki></pre>
-This operation does not require a request body.
+or
-'''Example 3.1. List Limits Response: XML '''
+<pre><nowiki>#!highlight javascript numbers=disable
+GET /v1.0/vips
+Accept: application/json
+</nowiki></pre>
-<pre><nowiki>#!highlight xml numbers=disable
+=== Filtering and Column Selection ===
-<limits xmlns="http://docs.openstack.org/common/api/v1.1">
+The LBaaS API v1.0 supports filtering based on all top level attributes of a resource. Filters are applicable to all list requests.
-   <rates>
-      <rate uri="/v1.1/*" regex="^/1.1/.*">
-          <limit  verb="GET"  value="600000"
-                  remaining="426852"  unit="HOUR"
-                  next-available="2011-02-22T19:32:43.835Z"/>
-      </rate>
-   </rates>
-   <absolute>
-       <limit name="maxNodesPerLoadBalancer" value="5"/>
-       <limit name="maxVIPsPerLoadBalancer" value="1"/>
-   </absolute>
-</limits>
-</nowiki></pre>
-''' Example 3.2. List Limits Response: JSON '''
+For example, the following request returns all networks named foobar:
 <pre><nowiki>#!highlight javascript numbers=disable
- {
+GET /v1.0/vips?name=foobar
-    "limits" :
-          {
-            "rate" : {
-                       "values": [
-                                  {
-                                    "uri" : "/v1.1/*",
-                                    "regex" : "^/1./.*",
-                                    "limit" : [
-                                               {
-                                                 "verb" : "GET",
-                                                 "value" : 600000,
-                                                 "remaining" : 426852,
-                                                 "unit" : "HOUR",
-                                                 "next-available" : "2011-02-22T19:32:43.835Z"
-                                               }
-                                              ]
-                                  }
-                                ]
-                     },
-            "absolute" : {
-                           "values" : {
-                                        "maxNodesPerLoadBalancer" : "5",
-                                        "maxVIPsPerLoadBalancer" : "1"
-                                      }
-                         }
-          }
-}
 </nowiki></pre>
-=== Faults ===
+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.
-API calls that return an error return one of the following fault objects. All fault objects extend from the base fault, serviceFault, for easier exception handling for languages that support it.
-==== serviceFault ====
-The serviceFault and by extension all other faults include message and detail elements which  contain strings describing the nature of the fault as well as a code attribute representing the HTTP response code for convenience. The code attribute of the fault is for the convenience of the caller so  that they may retrieve the response code from the HTTP response headers or directly from the fault object if they choose. The caller should not expect the serviceFault to be returned directly but should instead expect only one of the child faults to be returned.
-==== badRequest ====
-This fault indicates that the data in the request object is invalid; for example, a string was used in a parameter that was expecting an integer. The fault will wrap validation errors.
-'''Example 3.3. Fault Response, badRequest'''
+<pre><nowiki>#!wiki caution
+Note
-<pre><nowiki>#!highlight xml numbers=disable
+LBaaS does not offer an OR mechanism for filters.
-<badRequest xmlns="http://docs.openstack.org/atlas/api/v1.1" code="400">
-   <message>Validation fault</message>
-   <details>The object is not valid</details>
-   <validationErrors>
-      <message>Node IP address is invalid. Please specify a valid IP address.</message>
-   </validationErrors>
-</badRequest>
 </nowiki></pre>
-==== immutableEntity ====
+Alternatively, you can issue a distinct request for each filter and build a response set from the received responses on the client-side.
-This fault is returned when a user attempts to modify an item that is not currently in a state that allows modification. For example, load balancers in a status of BUILD,PENDING_UPDATE or DELETED may not be modified.
-''' Example 3.4. Fault Response, immutableEntity '''
+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.
-<pre><nowiki>#!highlight xml numbers=disable
+For example, the following request returns only id,name,network_id,address and port for each vip:
-<immutableEntity code="422" xmlns="http://docs.openstack.org/atlas/api/v1.1">
-  <message>The object at the specified URI is immutable and cannot be modified.
-  </message>
-</immutableEntity>
-</nowiki></pre>
-==== itemNotFound ====
-'''Example 3.5. Fault Response, itemNotFound '''
+<pre><nowiki>#!highlight javascript numbers=disable
-<pre><nowiki>#!highlight xml numbers=disable
+GET /v1.0/vips.json?fields=id&fields=name&fields=network_id&fields=address&fields=port
-<itemNotFound code="404" xmlns="http://docs.openstack.org/atlas/api/v1.1">
-  <message>Object not Found</message>
-</itemNotFound>
 </nowiki></pre>
-==== loadBalancerFault ====
+=== Synchronous versus Asynchronous Plugin Behavior ===
-The loadBalancerFault fault shall be returned in the event that an unpexpected error occurred during a loadbalancer operation.
+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.
-''' Example 3.6. Fault Response, loadBalancerFault '''
+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.
-<pre><nowiki>#!highlight xml numbers=disable
+You can use the status attribute of the VIP, the pool, the member or the health monitor to determine whether the LBaaS plugin has successfully completed the configuration of the resource.
-<loadBalancerFault code="500" xmlns="http://docs.openstack.org/atlas/api/v1.1">
-  <message>Load Balancer has experienced an internal error</message>
-</loadBalancerFault>
-</nowiki></pre>
-==== outOfVirtualIps ====
+=== Bulk Create Operations ===
-This fault indicates that there are no virtual IPs left to assign to a new load balancer. In practice, this fault should not occur, as virtual IPs will be ordered as capacity is required.
+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.
-''' Example 3.7. Fault Response, outOfVirtualIps '''
+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.
+The LBaaS service might be deployed without support for bulk operations and when the client attempts a bulk create operation, a 400 Bad Request error is returned.
-<pre><nowiki>#!highlight xml numbers=disable
+For information about how to submit bulk requests to the LBaaS API v1.0, see the section called “Bulk Create Members” section.
-<outOfVirtualIps code="500" xmlns="http://docs.openstack.org/atlas/api/v1.1">
-   <message>
-       Out of virtual IPs. Please contact support so they can allocate more virtual IPs.
-   </message>
-</outOfVirtualIps>
-</nowiki></pre>
-==== overLimit ====
+=== Quotas ===
-This fault is returned when the user has exceeded a currently allocated limit.
+[tbd]
-''' Example 3.8. Fault Response, overLimit '''
+=== Notifications ===
+[tbd]
+=== Extensions ===
+The LBaaS API v1.0 is extensible.
-<pre><nowiki>#!highlight xml numbers=disable
+The purpose of LBaaS API v1.0 extensions is to:
-<overLimit code="413" xmlns="http://docs.openstack.org/atlas/api/v1.1">
-  <message>
-    Load balancer cannot be created. You have reached your maximum number of load balancers.
-  </message>
-</overLimit>
-</nowiki></pre>
-==== serviceUnavailable ====
+* Introduce new features in the API without requiring a version change.
-This fault is returned when the service is unavailable, such as when the service is undergoing maintenance. Note that this does not necessarily mean that the currently configured load balancers are unable to process traffic; it simply means that the API is currently unable to service requests.
+* Introduce vendor-specific niche functionality.
+* Act as a proving ground for experimental functionalities that might be included in a future version of the API.
-''' Example 3.9. Fault Response, serviceUnavailable '''
+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.
-<pre><nowiki>#!highlight xml numbers=disable
+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. So, make sure that your extension is available on the deployed LBaaS service before making use of its extra features.
-<serviceUnavailable code="500" xmlns="http://docs.openstack.org/atlas/api/v1.1">
-   <message>The Load balancing service is currently not available</message>
-</serviceUnavailable>
-</nowiki></pre>
-==== unauthorized ====
+=== Faults ===
-This fault is returned when the user is not authorized to perform an attempted operation.
+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.
+{| border="1" cellpadding="2" cellspacing="0"
+| '''Error'''
+| '''Description'''
+|-
+| 400
+| Bad Request
+|-
+| 404
+| Not Found
+|-
+| 409
+| Conflict
+|-
+| 413
+| Over limit
+|-
+| 422
+| Immutable
+|-
+| 500
+| Internal server error
+|-
+| 503
+| Service unavailable
+|}
-''' Example 3.10. Fault Response, unauthorized '''
+Users submitting requests to the LBaaS API v1.0 might also receive the following errors:
+Unauthorized - If invalid credentials are provided.
-<pre><nowiki>#!highlight xml numbers=disable
+Forbidden - If the user cannot access a specific resource or perform the requested operation.
-<unauthorized code="401" xmlns="http://docs.openstack.org/atlas/api/v1.1">
-    <message>You are not authorized to execute this operation.</message>
-</unauthorized>
-</nowiki></pre>
-==== unprocessableEntity ====
+The response body will contain richer information about the cause of the error. An error response follows the format illustrated by the following example:
-This fault is returned when an entity cannot be processed due to semantic errors.
-'''Example 3.11. Fault Response, unprocessableEntity'''
+<pre><nowiki>#!highlight javascript numbers=disable
+Conflict
+Content-type: application/json
+Content-lentgh:78
-<pre><nowiki>#!highlight xml numbers=disable
+{
-<unprocessableEntity code="422" xmlns="http://docs.openstack.org/atlas/api/v1.1">
+   "errorcode": 409,
-   <message>The Object at the specified URI is unprocessable.</message>
+   "errormessage": "pool is already used by an existing VIP"
-</unprocessableEntity>
+}
 </nowiki></pre>
-== API Operations ==
+== Chapter 3. API Operations ==
 This chapter explains specific API operations. For ideas relevant to all API operations, see the "General API Information" chapter.
-=== Load Balancers ===
+=== VIPs ===
-==== List Load Balancers ====
+Use the LBaaS API v1.0 to manage network resources
+{| border="1" cellpadding="2" cellspacing="0"
+| 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 all VIPs ====
 {| border="1" cellpadding="2" cellspacing="0"
 | Verb
@@ Line 374: / Line 264: @@
 |-
 | GET
-| /loadbalancers
+| /v1.0/vips/
-| List all load balancers configured for the account.
 |}
-'''Normal Response Code(s)''': 200
+'''Normal Response Code(s)''': 202
-'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+'''Error Response Code(s)''': 401 (Unauthorized), 500 (Internal server error), 503 (Service Unavailable)
-This operation provides a list of all load balancers configured and associated with your account.
+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.
-To view deleted load balancers, add "?status=DELETED" to the end of the  GET URI. A deleted loadbalancer is immutable and irrecoverable.
+This operation does not require a request body.
-This operation returns the following attributes for each load balancer:
+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
-* algorithm
+* description
+* network_id
+* address
+* port
+* lbmethod
 * protocol
-* port
+* pool_id
+* session_persistence
+* connection_limit
+* admin_state_up
 * status
-* created
-* updated
-This operation does not require a request body.
+'''Example . List vips'''
-'''Example 4.1. List Load Balancers Response: XML '''
+JSON Request:
-<pre><nowiki>#!highlight xml numbers=disable
+<pre><nowiki>#!highlight javascript numbers=disable
-<?xml version="1.0" ?>
+GET /v1.0/vips
-<loadBalancers xmlns="http://docs.openstack.org/atlas/api/v1.1">
+Host: lbaas-service.cloudX.com:8651
-  <loadBalancer id="71" name="lb-site1" status="ACTIVE"
+Accept: application/json
-                protocol="HTTP" port="80" algorithm="LEAST_CONNECTIONS" created="2010-12-13T15:38:27-06:00" updated="2010-12-13T15:38:38-06:00" >
+X-Auth-Token:887665443383838
-  </loadBalancer>
-  <loadBalancer id="166" name="lb-site2" status="ACTIVE"
-                protocol="HTTP" port="80" algorithm="ROUND_ROBIN"  created="2010-12-13T15:38:27-06:00" updated="2010-12-13T15:38:38-06:00" >
-  </loadBalancer>
-</loadBalancers>
 </nowiki></pre>
-'''Example 4.2. List Load Balancers Response: JSON'''
+JSON Response:
 <pre><nowiki>#!highlight javascript numbers=disable
+OK
+Content-Type: application/json
+Content-Length: 384
 {
-   "loadBalancers":[
+   "vips":[
           {
-            "name":"lb-site1",
+            "id": "db902c0c-d5ff-4753-b465-668ad9656918",
-            "id":"71",
+            "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
-            "protocol":"HTTP",
+            "name": "web_vip",
-            "port":"80",
+            "description": "lb config for the web tier",
-            "algorithm":"LEAST_CONNECTIONS",
+            "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
-            "status":"ACTIVE",
+            "address" : "10.30.176.47",
-            "created":"2010-11-30T03:23:42Z",
+            "protocol": "HTTP",
-            "updated":"2010-11-30T03:23:44Z"
+           "port": 80,
+           "lb_method": "ROUND_ROBIN",
+            "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764",
+           "admin_state_up": true,
+           "status": "ACTIVE"
           },
           {
-            "name":"lb-site2",
+            "id": "36e08a3e-a78f-4b40-a229-1e7e23eee1ab",
-            "id":"166",
+           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
-            "protocol":"TCP",
+            "name": "db_vip",
-            "port":"9123",
+            "network_id": "9cedb85d-0759-4898-8a4b-fa5a5ea10086",
-            "algorithm":"ROUND_ROBIN",
+            "address" : "10.30.176.48",
-            "status":"ACTIVE",
+            "protocol": "TCP",
-            "created":"2010-11-30T03:23:42Z",
+           "port": 3306,
-            "updated":"2010-11-30T03:23:44Z"
+            "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"
           }
        ]
@@ Line 445: / Line 347: @@
 </nowiki></pre>
-==== List Load Balancer Details ====
+==== Retrieve a specific VIP ====
 {| border="1" cellpadding="2" cellspacing="0"
 | Verb
@@ Line 452: / Line 354: @@
 |-
 | GET
-| /loadbalancers/''loadBalancerId''
+| /v1.0/vips/''vip_id''
-| List details of the specified load balancer.
 |}
-'''Normal Response Code(s)''': 200
+'''Normal Response Code(s)''': 202
-'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+'''Error Response Code(s)''': 401 (Unauthorized), 404 (Not Found), 409 (Conflict), 413 (Over limit), 500 (Internal server error), 503 (Service Unavailable)
-This operation provides detailed output for a specific load balancer configured and associated with your account. This operation is not capable of returning details for a load balancer which has been deleted.
+This operation returns a vip object associated with your tenant account.
 This operation does not require a request body.
-'''Example 4.3. List Load Balancer Details Response: XML'''
+This operation returns a response body. The returned element is a VIP that can contain the following attributes:
+* id
+* tenant_id
+* name
+* description
+* network_id
+* address
+* port
+* lb_method
+* protocol
+* pool_id
+* session_persistence
+* connection_limit
+* admin_state_up
+* status
-<pre><nowiki>#!highlight xml numbers=disable
+'''Example . Retrieve a VIP details: '''
-<loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1"
-   id="2000"
-   name="sample-loadbalancer"
-   protocol="HTTP"
-   port="80"
-   algorithm="ROUND_ROBIN"
-   status="ACTIVE"
-   created="2010-11-30T03:23:42Z"
-   updated="2010-11-30T03:23:44Z">
-   <virtualIps>
+JSON Request:
-     <virtualIp id="1000" address="2001:cdba:0000:0000:0000:0000:3257:9652" type="PUBLIC" ipVersion="IPV6" />
-   </virtualIps>
-   <nodes>
-     <node id="1041" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" />
-     <node id="1411" address="10.1.1.2" port="80" condition="ENABLED" status="ONLINE" />
-   </nodes>
-   <sessionPersistence persistenceType="HTTP_COOKIE"/>
+<pre><nowiki>#!highlight javascript numbers=disable
+GET /v1.0/vips/36e08a3e-a78f-4b40-a229-1e7e23eee1ab
-   <connectionThrottle maxRequestRate="50" rateInterval="60" />
+Host: lbaas-service.cloudX.com:8651
+Accept: application/json
-</loadBalancer>
+X-Auth-Token:887665443383838
 </nowiki></pre>
-'''Example 4.4. List Load Balancers Details Response: JSON'''
+JSON Response:
 <pre><nowiki>#!highlight javascript numbers=disable
+OK
+Content-Type: application/json
+Content-Length: 156
 {
-      "id": "2000",
+     "vip": {
-      "name":"sample-loadbalancer",
+           "id": "36e08a3e-a78f-4b40-a229-1e7e23eee1ab",
-      "protocol":"HTTP",
+           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
-      "port": "80",
+           "name": "db_vip",
-      "algorithm":"ROUND_ROBIN",
+           "description": "lb config for the MYSQL db tier",
-      "status":"ACTIVE",
+           "network_id": "9cedb85d-0759-4898-8a4b-fa5a5ea10086",
-      "created":"2010-11-30T03:23:42Z",
+           "address" : "10.30.176.47",
-      "updated":"2010-11-30T03:23:44Z",
+           "protocol": "TCP",
-      "virtualIps":[
+           "port": 3306,
-                    {
+           "lb_method": "LEAST_CONNECTIONS",
-                       "id": "1000",
+           "pool_id" : "41efe233-7591-43c5-9cf7-923964759f9e",
-                       "address":"2001:cdba:0000:0000:0000:0000:3257:9652",
+           "session_persistence" : {"type" : "SOURCE_IP"},
-                       "type":"PUBLIC",
+           "connection_limit" : 2000,
-                       "ipVersion":"IPV6"
+           "admin_state_up": true,
-                    }
+           "status": "INACTIVE"
-                   ],
+         }
-       "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"
-                            }
 }
 </nowiki></pre>
-==== Create Load Balancer ====
+==== Create a VIP ====
 {| border="1" cellpadding="2" cellspacing="0"
 | Verb
@@ Line 549: / Line 429: @@
 |-
 | POST
-| /loadbalancers
+| /v1.0/vips
-| Create a new load balancer with the configuration defined by the request.
 |}
 '''Normal Response Code(s)''': 202
-'''Error Response Code(s)''': loadbalancerFault (500), serviceUnavailable (503), unauthorized (401),badRequest (400), overLimit (413)
+'''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 load balancer based on the configuration defined in the request object. Once the request is validated and progress has started on the provisioning process, a response object will be returned. The object will contain a unique identifier and status of the request.
+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.
-If the status returned is set to "BUILD", then using the identifier of the load balancer, the caller can check on the progress of the creation operation by performing a GET on loadbalancers/''loadbalancerid''. When the status of the load balancer returned changes to "ACTIVE", then the load balancer has been successfully provisioned and is now operational.
+The status of the vip in the response can take one of the following values: ACTIVE, PENDING_CREATE or ERROR.
-The caller of this operation must specify at least the following attributes of the load balancer:
+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
-* At least one node
+* 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.
-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.
+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.
-<pre><nowiki>#!wiki caution
+If the request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 (Bad Request) error response will be returned with information regarding the nature of the failure in the body of the response. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST the request again.
-Note
-By default the system will create a loadbalancer with protocol set to HTTP, port set to 80 (or 443 if protocol is HTTPS), and assign a public IPV6 address to the loadbalancer. The default algorithm used is set to ROUND_ROBIN.
+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.
-</nowiki></pre>
+Users with an admin role can create vips for other tenants by specifying a tenant_id attribute different than their own.
-<pre><nowiki>#!wiki caution
+'''Example 4.6. Create a vip (Required Attributes) Request: JSON '''
-Note
-A load balancer's name has a max length that can be queried when querying limits.
+'''Example . create a vip with a shared address''' JSON Request:
-</nowiki></pre>
-Users may configure all documented features of the load balancer at creation time by simply providing the additional elements or attributes in the request. This document provides an overview of all the features the load balancing service supports.
+<pre><nowiki>#!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
-<pre><nowiki>#!wiki caution
+{
-Note
+  "vips":[
+         {
-Users may request either an IPv4 or IPV6 address by specifying the version in the create request. For example to request a public IPV6 virtual IP address for the load balancer, use the following virtualIP element in the request:
+           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
+           "name": "web_vip",
-<virtualIp type="PUBLIC" ipVersion="IPV6"/>
+           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
+           "protocol": "HTTP",
-If the version attribute is not specified, then an IPv6 IP address is allocated by default.
+           "port": 80,
+           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764"
+         }
+      ]
+}
 </nowiki></pre>
-'''Example 4.5. Create Load Balancer (Required Attributes) Request: XML'''
+JSON Response:
-<pre><nowiki>#!highlight xml numbers=disable
+<pre><nowiki>#!highlight javascript numbers=disable
-<loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1"
+Accepted
-              name="a-new-loadbalancer">
+Content-Type: application/json
-      <nodes>
+Content-Length: 213
-      <node address="10.1.1.1" port="80" />
-      <node address="10.1.1.2" port="81" />
-    </nodes>
-</loadBalancer>
-</nowiki></pre>
-'''Example 4.6. Create Load Balancer (Required Attributes) Request: JSON '''
-<pre><nowiki>#!highlight javascript numbers=disable
 {
-    "name": "a-new-loadbalancer",
+  "vips":[
-    "nodes":      [
+         {
-                    {
+           "id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
-                      "address": "10.1.1.1",
+           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
-                      "port": "80"
+           "name": "web_vip",
-                    },
+           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
-                    {
+           "address" : "10.30.176.47",
-                      "address": "10.1.1.2",
+           "protocol": "HTTPS",
-                      "port": "81"
+           "port": 443,
-                    }
+           "lb_method": "ROUND_ROBIN",
-                   ]
+           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764",
+           "admin_state_up": true,
+           "status": "PENDING_CREATE"
+         }
+      ]
 }
 </nowiki></pre>
-If you have at least one load balancer, you may create subsequent load balancers that share a single virtual IP by issuing a POST and supplying a virtual IP ID instead of a type. Additionally, this feature is highly desirable if you wish to load balance both an unsecured and secure protocol using one IP address. For example, this method makes it possible to use the same load balancing configuration to support an HTTP and an HTTPS load balancer.
+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.
-<pre><nowiki>#!wiki caution
+'''Example . create a vip with an address shared with another vip''' JSON Request:
-Note
-Load balancers sharing a virtual IP must utilize a unique port.
-</nowiki></pre>
-'''Example 4.7. Create Load Balancer (Required Attributes with Shared IP) Request: XML '''
+<pre><nowiki>#!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
-<pre><nowiki>#!hightlight xml
-<loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1"
-              name="a-new-loadbalancer" port="83" protocol="HTTP">
-      <virtualIps>
-         <virtualIp id="39"/>
-      </virtualIps>
-      <nodes>
-         <node address="10.1.1.1" port="80" condition="ENABLED" />
-      </nodes>
-</loadBalancer>
-</nowiki></pre>
-'''Example 4.8. Create Load Balancer (Required Attributes with Shared IP) Request: JSON '''
-<pre><nowiki>#!highlight javascript numbers=disable
 {
-   "name":"a-new-loadbalancer",
+  "vips":[
-   "port":"83",
+         {
-   "protocol":"HTTP",
+           "name": "ssl_vip",
-   "virtualIps": [
+           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
-                   {
+           "address" : "10.30.176.47",
-                      "id":"39"
+           "protocol": "HTTPS",
-                   }
+           "port": 443,
-                 ],
+           "pool_id" : "91c20e53-96cd-4476-8efc-627f398773bb"
-   "nodes":      [
+         }
-                   {
+      ]
-                      "address":"10.1.1.1",
-                      "port":"80",
-                      "condition":"ENABLED"
-                   }
-                 ]
 }
 </nowiki></pre>
-''' Example 4.9. Create Load Balancer (Required Attributes with Shared IP) Response: XML '''
+JSON Response:
-<pre><nowiki>#!highlight xml numbers=disable
+<pre><nowiki>#!highlight javascript numbers=disable
-<loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1"
+Accepted
-              id="144" name="a-new-loadbalancer" algorithm="ROUND_ROBIN"
+Content-Type: application/json
-              protocol="HTTP"
+Content-Length: 282
-              port="83"
-              status="BUILD"
-              created="2011-02-08T21:19:55Z"
-              updated="2011-02-08T21:19:55Z" >
-    <virtualIps>
-       <virtualIp id="39" address="3ffe:1900:4545:3:200:f8ff:fe21:67cf" ipVersion="IPV6" type="PUBLIC" />
-    </virtualIps>
-    <nodes>
-       <node id="653" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" />
-    </nodes>
-</loadBalancer>
-</nowiki></pre>
-'''Example 4.10. Create Load Balancer (Required Attributes with Shared IP) Response: JSON '''
-<pre><nowiki>#!highlight javascript numbers=disable
 {
-    "name": "a-new-loadbalancer",
+  "vips":[
-    "id": "144",
+         {
-    "protocol": "HTTP",
+           "id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
-    "port": "83",
+           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
-    "algorithm": "ROUND_ROBIN",
+           "name": "ssl_vip",
-    "status": "BUILD",
+           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
-    "created": "2011-04-13T14:18:07Z",
+           "address" : "10.30.176.47",
-    "updated":"2011-04-13T14:18:07Z",
+           "protocol": "HTTPS",
-    "virtualIps": [
+           "port": 443,
-                    {
+           "lb_method": "ROUND_ROBIN",
-                      "address": "3ffe:1900:4545:3:200:f8ff:fe21:67cf",
+           "pool_id" : "91c20e53-96cd-4476-8efc-627f398773bb",
-                      "id": "39",
+           "admin_state_up": true,
-                      "type": "PUBLIC",
+           "status": "PENDING_CREATE"
-                      "ipVersion": "IPV6"
+         }
-                    }
+      ]
-                  ],
-    "nodes":      [
-                    {
-                      "address": "10.1.1.1",
-                      "id": "653",
-                      "port": "80",
-                      "status": "ONLINE",
-                      "condition": "ENABLED"
-                    }
-                  ]
 }
 </nowiki></pre>
-==== Update Load Balancer Attributes ====
+==== Update a VIP ====
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Verb'''
@@ Line 737: / Line 579: @@
 |-
 | PUT
-| /loadbalancers/''loadBalancerId''
+| /1.0/vips/''vip_id''
-| Update the properties of a loadbalancer.
 |}
@@ Line 745: / Line 586: @@
 '''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
-This operation updates the attributes of the specified load balancer. Upon successful validation of the request, the service will return a 202 (Accepted) response code. A caller should check that the load balancer status is ACTIVE to confirm that the update has taken effect. If the load balancer status is "PENDING_UPDATE" then the caller can poll the load balancer with its ID (using a GET operation) to wait for the changes to be applied and the load balancer to return to an ACTIVE status.
+This operation 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
-* algorithm
+* description
+* pool_id
+* lb_method
+* session_persistence
+* connection_limit
+* admin_state_up
-This operation does not return a response body.
+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.
@@ Line 758: / Line 604: @@
 Note
-The load balancer's ID, status, port and protocol are immutable attributes and cannot be modified by the caller. Supplying an unsupported attribute will result in a 400 (badRequest) fault.
+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.
 </nowiki></pre>
-'''Example 4.11. Update Load Balancer Attributes Request: XML '''
+'''Example . updating a vip ''' JSON Request:
-<pre><nowiki>#!highlight xml numbers=disable
+<pre><nowiki>#!highlight javascript numbers=disable
-<loadBalancer xmlns="http://docs.openstack.org/atlas/api/v1.1"
+PUT /v1.0/vips/02b1fef7-16f5-4917-bf19-c40a9af805ed
-              name="newname-loadbalancer" algorithm="LEAST_CONNECTIONS" />
+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",
+           "description": "this VIP is used for secure web connections",
+           "lb_method": "LEAST_CONNECTIONS",
+           "session_persistence": { "type": "HTTP_COOKIE" }
+         }
+}
 </nowiki></pre>
-'''Example 4.12. Update Load Balancer Attributes Request: JSON '''
+JSON Response:
 <pre><nowiki>#!highlight javascript numbers=disable
+Accepted
+Content-Type: application/json
+Content-Length: 282
 {
-   "name": "newname-loadbalancer",
+  "vip": {
-   "algorithm": "LEAST_CONNECTIONS"
+           "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"
+         }
 }
 </nowiki></pre>
-'''Table 4.1. Load Balancer Statuses'''
+'''Table 4.1. vip Statuses'''
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Name'''
@@ Line 785: / Line 660: @@
 | ACTIVE
 |-
-| BUILD
+| PENDING_CREATE
 |-
 | PENDING_UPDATE
@@ Line 791: / Line 666: @@
 | PENDING_DELETE
 |-
-| DELETED
+| INACTIVE
-|-
-| SUSPENDED
 |-
 | ERROR
 |}
-Note that a load balancer whose status is SUSPENDED is not operational and traffic to it is rejected and will not be forwarded to back-end nodes.
+==== Remove a VIP ====
-==== Remove Load Balancer ====
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Verb'''
@@ Line 807: / Line 678: @@
 |-
 | DELETE
-| /loadbalancers/''loadBalancerId''
+| /v1.0/vips/''vip_id''
-| Remove a load balancer from the account.
+| Remove a VIP from the account.
 |}
@@ Line 815: / Line 686: @@
 '''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
-The remove load balancer function removes the specified load balancer and its associated configuration from the account. Any and all configuration data is immediately purged and is not recoverable.
+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.
@@ Line 821: / Line 692: @@
 This operation does not return a response body.
-Deleted load balancers are still displayed for a number of days after deletion when listing load balancers of an account. Their status is changed to DELETED.The updated date of a DELETED load balancer reflects the time/date of its deletion.
+'''Example . Deleting a vip ''' JSON Request:
+<pre><nowiki>#!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
+</nowiki></pre>
+JSON Response:
-=== Nodes ===
-The nodes defined by the load balancer are responsible for servicing the requests received through the load balancer's virtual IP. By default, the load balancer employs a basic health check that ensures the node is listening on its defined port. The node is checked at the time of addition and at regular intervals as defined by the load balancer health check configuration. If a back-end node is not listening on its port or does not meet the conditions of the defined active health check for the load balancer, then the loadbalancer will not forward connections or requests to it and its status will be listed as OFFLINE. Only nodes that are in an ONLINE status will receive and be able to service traffic from the load balancer.
-The status of the node can be determined by passive or active health monitoring.
+<pre><nowiki>#!highlight javascript numbers=disable
+Accepted
+</nowiki></pre>
-The caller can assign the relevant weights to nodes using the weight attribute of the node element.
+=== 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.
-The weight of a node determines the portion of requests or connections it services compared to the other nodes of the load balancer. For example, if node A has a weight of 2 and node B has a weight of 1, then the loadbalancer will forward twice as many requests to node A than to node B. If the weight attribute is not specified, then the node's weight is implicitly set to "1".
+Each vip object can be associated with one pool. A pool cannot be used by more than one vip.
-==== List Nodes ====
+==== List all Pools ====
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Verb'''
@@ Line 839: / Line 721: @@
 |-
 | GET
-| /loadbalancers/''loadBalancerId''/nodes
+| /v1.0/pools
-| List node(s) configured for the load balancer.
 |}
-List all nodes of a load balancer.
+List all pools of a tenant.
 '''Normal Response Code(s)''': 200
@@ Line 851: / Line 732: @@
 This operation does not require a request body.
-'''Example 4.13. List Nodes Response: XML '''
+'''Example 4.13. List pools Request:''' JSON Request:
-<pre><nowiki>#!highlight xml numbers=disable
+<pre><nowiki>#!highlight javascript numbers=disable
-<nodes>
+GET /v1.0/pools
-   <node id="410" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" />
+Host: lbaas-service.cloudX.com:8651
-   <node id="236" address="10.1.1.2" port="80" condition="ENABLED" status="ONLINE" />
+Accept: application/json
-   <node id="2815" address="10.1.1.3" port="83" condition="DISABLED" status="OFFLINE" />
+X-Auth-Token:887665443383838
-</nodes>
 </nowiki></pre>
-'''Example 4.14. List Node Response: JSON'''
+'''Example. List pools Response: JSON'''
 <pre><nowiki>#!highlight javascript numbers=disable
+OK
+Content-Type: application/json
+Content-Length: 628
 {
-   "nodes" : [
+   "pools" : [
                {
-                 "id":"410",
+                 "id":"cfc6589d-f949-4c66-99d2-c2da56ef3764",
-                 "address":"10.1.1.1",
+                 "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
-                 "port":"80",
+                 "vip_id": "db902c0c-d5ff-4753-b465-668ad9656918",
-                 "condition":"ENABLED",
+                 "name": "web_pool",
-                 "status":"ONLINE"
+                "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":"236",
+                 "id":"91c20e53-96cd-4476-8efc-627f398773bb",
-                 "address":"10.1.1.2",
+                 "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
-                 "port":"80",
+                 "vip_id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
-                 "condition":"ENABLED",
+                 "protocol": "HTTPS",
-                 "status":"ONLINE"
+                "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":"2815",
+                 "id":"41efe233-7591-43c5-9cf7-923964759f9e",
-                 "address":"10.1.1.3",
+                 "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
-                 "port":"83",
+                 "vip_id": "36e08a3e-a78f-4b40-a229-1e7e23eee1ab",
-                 "condition":"DISABLED",
+                 "protocol": "TCP",
-                 "status":"OFFLINE"
+                "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"
+               }
              ]
 }
 </nowiki></pre>
-==== Retrieve a Node ====
+==== Retrieve a specific Pool ====
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Verb'''
@@ Line 900: / Line 815: @@
 |-
 | GET
-| /loadbalancers/''loadBalancerId''/nodes/''nodeId''
+| /v1.0/pools/''pool_id''
-| Retrieve the configuration of node ''nodeid'' of loadbalancer ''loadbalancerId''.
 |}
-This operation retrieves the configuration of a node.
+This operation retrieves the configuration of a pool.
 '''Normal Response Code(s)''': 200
@@ Line 912: / Line 826: @@
 This operation does not require a request body.
-'''Example 4.15. Retrieve the configuration of a node Response: XML '''
+'''Example 4.15. Retrieve the configuration of a pool '''
+JSON Request:
-<pre><nowiki>#!highlight xml numbers=disable
+<pre><nowiki>#!highlight javascript numbers=disable
-<node id="236" address="10.1.1.2" port="80" condition="ENABLED" status="ONLINE" />
+GET /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764
+Host: lbaas-service.cloudX.com:8651
+Accept: application/json
+X-Auth-Token:887665443383838
 </nowiki></pre>
-'''Example 4.16. Retrieve a node Response: JSON'''
+'''Example. List pools Response: JSON'''
 <pre><nowiki>#!highlight javascript numbers=disable
+OK
+Content-Type: application/json
+Content-Length: 628
 {
-   "id":"236",
+   "pool" : {
-  "address":"10.1.1.2",
+         "id":"cfc6589d-f949-4c66-99d2-c2da56ef3764",
-  "port":"80",
+         "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
-  "condition":"ENABLED",
+         "vip_id": "db902c0c-d5ff-4753-b465-668ad9656918",
-  "status":"ONLINE"
+         "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" : [
+                               "f784c3a7-c4e8-44da-bf12-5ff417d27555"
+                             ],
+         "admin_state_up" : true,
+         "status" : "ACTIVE"
+  }
 }
 </nowiki></pre>
-==== Add Nodes ====
+==== Create a Pool ====
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Verb'''
 | '''URI'''
-| '''Description'''
 |-
 | POST
-| /loadbalancers/''loadBalancerId''/nodes
+| /v1.0/pools
-| Add a new node to the load balancer.
 |}
@@ Line 947: / Line 881: @@
 '''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
-When a node is added, it is assigned a unique identifier that can be used for mutating operations such as changing the condition or the weight of a node, or removing the node from the load balancer.
+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.
-Every load balancer is dual-homed on both the public Internet and the internal network; as a result, nodes can either be internal private addresses or addresses on the public Internet.
+If a user has an admin role, she can create pools for other tenant by specifying the tenant_id attribute in the request payload.
-<pre><nowiki>#!wiki caution
+'''Example 4.15. Creating a pool '''
-Note:
-When a node is added to a load balancer, it is enabled by default.
+JSON Request:
-</nowiki></pre>
-'''Example 4.17. Add Nodes Request: XML'''
+<pre><nowiki>#!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
-<pre><nowiki>#!highlight xml numbers=disable
+{
-<nodes xmlns="http://docs.openstack.org/atlas/api/v1.1">
+  "pools" : [
-  <node address="10.1.1.1" port="80" />
+         {
-  <node address="10.2.2.1" port="80" weight="2" />
+            "name": "web_pool",
-  <node address="10.2.2.2" port="88" condition="DISABLED" weight="2" />
+            "vip_id": "db902c0c-d5ff-4753-b465-668ad9656918",
-</nodes>
+            "protocol": "HTTP",
+            "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
+            "members" : [
+                          "c57f581b-c834-408f-93fa-30543cf30618",
+                          "f2e37304-e3c1-4f96-9201-dd57a16adb75"
+                        ]
+        }
+   ]
+}
 </nowiki></pre>
-'''Example 4.18. Add Nodes Request: JSON'''
+JSON Response
 <pre><nowiki>#!highlight javascript numbers=disable
+Accepted
+Content-Type: application/json
+Content-Length: 275
 {
-   "nodes": [
+   "pools" : [
-             {
+           {
-               "address": "10.1.1.1",
+            "id":"cfc6589d-f949-4c66-99d2-c2da56ef3764",
-               "port": "80"
+            "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
-             },
+            "vip_id": "db902c0c-d5ff-4753-b465-668ad9656918",
-             {
+            "name": "web_pool",
-               "address": "10.2.2.1",
+            "protocol": "HTTP",
-               "port": "80",
+            "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
-               "weight": "2"
+            "members" : [
-             },
+                          "c57f581b-c834-408f-93fa-30543cf30618",
-             {
+                          "f2e37304-e3c1-4f96-9201-dd57a16adb75"
-               "address": "10.2.2.2",
+                        ],
-               "port": "88",
+            "admin_state_up" : true,
-               "condition": "DISABLED",
+            "status" : "PENDING_CREATE"
-               "weight": "2"
+          }
-             }
+        ]
-           ]
 }
 </nowiki></pre>
-'''Example 4.19. Add Nodes Response: XML'''
+==== Update a Pool ====
+{| border="1" cellpadding="2" cellspacing="0"
+| 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)
-<pre><nowiki>#!highlight xml numbers=disable
+This operation does not return a response body.
-<nodes xmlns="http://docs.openstack.org/atlas/api/v1.1">
- <node id="7298" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" />
+'''Example 4.21. Update name of the pool'''
- <node id="293" address="10.2.2.1" port="80" weight="2" condition="ENABLED" status="OFFLINE" />
- <node id="183" address="10.2.2.2" port="88" weight="2" condition="DISABLED" status="OFFLINE" />
+JSON Request:
-</nodes>
+<pre><nowiki>#!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"
+           }
+}
 </nowiki></pre>
-'''Example 4.20. Add Nodes Response: JSON'''
+JSON Response
 <pre><nowiki>#!highlight javascript numbers=disable
+Accepted
+Content-Type: application/json
+Content-Length: 269
 {
-   "nodes": [
+   "pool" : {
-             {
+            "id":"cfc6589d-f949-4c66-99d2-c2da56ef3764",
-               "id": "7298",
+            "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
-               "address": "10.1.1.1",
+            "vip_id": "db902c0c-d5ff-4753-b465-668ad9656918",
-               "port": "80",
+            "name": "web_pool_1",
-               "condition": "ENABLED",
+            "protocol": "HTTP",
-               "status": "ONLINE"
+            "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
-             },
+            "members" : [
-             {
+                          "c57f581b-c834-408f-93fa-30543cf30618",
-               "id": "293",
+                          "f2e37304-e3c1-4f96-9201-dd57a16adb75"
-               "address": "10.2.2.1",
+                        ],
-               "port": "80",
+            "admin_state_up" : true,
-               "weight": "2",
+            "status" : "PENDING_UPDATE"
-               "condition": "ENABLED",
+          }
-               "status": "OFFLINE"
-             },
-             {
-               "id": "183",
-               "address": "10.2.2.4",
-               "port": "88",
-               "weight": "2",
-               "condition": "DISABLED",
-               "status": "OFFLINE"
-             }
-           ]
 }
 </nowiki></pre>
-==== Modify Nodes ====
+==== Remove a Pool ====
 {| border="1" cellpadding="2" cellspacing="0"
-| Verb
+| '''Verb'''
-| URI
+| '''URI'''
-| Description
+|}
-|-
-| PUT
+{| border="1" cellpadding="2" cellspacing="0"
-| /loadbalancers/''loadBalancerId''/nodes/''nodeId''
+| DELETE
-| Modify the configuration of a node on the load balancer.
+| /pools/''pool_id''
 |}
-'''Normal Response Code(s)''': 202
+'''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.
@@ Line 1,059: / Line 1,026: @@
 Note
-The node's IP and port are immutable attributes and cannot be modified with a PUT
+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.
-request. Supplying an unsupported attribute will result in a 400 (badRequest) fault. A load balancer supports a maximum number of nodes. The maximum number of nodes per loadbalancer is returned when querying the limits of the LB service.
 </nowiki></pre>
-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. Removing a pool'''
+JSON Request:
+<pre><nowiki>#!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
+</nowiki></pre>
-'''Example 4.21. Disable a node Request: XML'''
+JSON Response
-<pre><nowiki>#!highlight xml numbers=disable
+<pre><nowiki>#!highlight javascript numbers=disable
-<node condition="DISABLED" />
+Accepted
+</nowiki></pre>
+<pre><nowiki>#!wiki caution
+Note
+A pool that is pending to be deleted cannot be updated.
+</nowiki></pre>
+=== Pool 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 ====
+{| border="1" cellpadding="2" cellspacing="0"
+| '''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:
+<pre><nowiki>#!highlight javascript numbers=disable
+GET /v1.0/members
+Host: lbaas-service.cloudX.com:8651
+Accept: application/json
+X-Auth-Token:887665443383838
 </nowiki></pre>
-'''Example 4.22. Disable a node Request: JSON'''
+JSON Response:
 <pre><nowiki>#!highlight javascript numbers=disable
+OK
+Content-Type: application/json
+Content-Length: 917
 {
-   "condition": "DISABLED"
+   "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"
+              }
+            ]
 }
 </nowiki></pre>
-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.
+==== List all Members of a specific Pool ====
-==== Remove Nodes ====
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Verb'''
 | '''URI'''
-| '''Description'''
 |-
-| DELETE
+| GET
-| /loadbalancers/''loadBalancerId''/nodes/''nodeId''
+| /v1.0/pools/''pool_id''/members
-| Remove a node from the load balancer.
 |}
-'''Normal Response Code(s)''': 200, 202
+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)
@@ Line 1,100: / Line 1,200: @@
 This operation does not require a request body.
-This operation does not return a response body.
+'''Example: Listing all members '''
+JSON Request:
-<pre><nowiki>#!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.
+<pre><nowiki>#!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
 </nowiki></pre>
-=== Virtual IPs ===
+JSON Response:
-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'''
+<pre><nowiki>#!highlight javascript numbers=disable
+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"
+              }
+            ]
+}
+</nowiki></pre>
+==== Retrieve a specific Member ====
 {| border="1" cellpadding="2" cellspacing="0"
-| '''Name'''
+| '''Verb'''
+| '''URI'''
+| '''Description'''
 |-
-| PUBLIC
+| GET
-|-
+| /members/''member_id''
-| INTERNAL
 |}
-==== List Virtual IPs ====
+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:
+<pre><nowiki>#!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
+</nowiki></pre>
+JSON Response:
+<pre><nowiki>#!highlight javascript numbers=disable
+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"
+              }
+}
+</nowiki></pre>
+==== Bulk Create Members ====
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Verb'''
@@ Line 1,127: / Line 1,314: @@
 | '''Description'''
 |-
-| GET
+| POST
-| /loadbalancers/''loadBalancerId''/virtualips
+| /v1.0/members
-| List all virtual IPs associated with a load balancer.
+| Add members to pools.
 |}
-'''Normal Response Code(s): 200'''
+'''Normal Response Code(s)''': 202
 '''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.
+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.
-This request does not require a request body.
+<pre><nowiki>#!wiki caution
+Note:
+When a member is added to a load balancer, it is enabled by default (admin_state_up = true).
+</nowiki></pre>
+'''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:
+<pre><nowiki>#!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"
+              }
+            ]
+}
+</nowiki></pre>
+JSON Response:
+<pre><nowiki>#!highlight javascript numbers=disable
+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"
+              }
+            ]
+}
+</nowiki></pre>
+==== Update a Member ====
+{| border="1" cellpadding="2" cellspacing="0"
+| Verb
+| URI
+| Description
+|-
+| PUT
+| /v1.0/members/''member_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.
@@ Line 1,144: / Line 1,433: @@
 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.
+The member's address 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 pool supports a
+maximum number of nodes. The maximum number of nodes per pool is returned when querying the limits of the LBaaS service.
 </nowiki></pre>
-'''Example 4.23. List Virtual IPs Response: XML'''
+Every member in the pool is either enabled or disabled which determines its role within the pool using the admin_state_up attribute. When the member has admin_state_up=true, the member is permitted to accept new connections or requests. Its status will eventually become ACTIVE to reflect this configuration. When the member has admin_state_up=false, the member is not permitted to accept any new connections or requests regardless of session persistence configuration. Existing connections to the node are gracefully drained or forcibly terminated. The member's status changes to INACTIVE once the configuration has been successfully applied.
+'''Example 4.21. Disable a member '''
+JSON Request:
-<pre><nowiki>#!highlight xml numbers=disable
+<pre><nowiki>#!highlight javascript numbers=disable
-<virtualIps xmlns="http://docs.openstack.org/atlas/api/v1.1">
+PUT /v1.0/members/c57f581b-c834-408f-93fa-30543cf30618
-   <virtualIp id="1021" address="206.10.10.210" type="PUBLIC" ipVersion="IPV4"/>
+Host: lbaas-service.cloudX.com:8651
-</virtualIps>
+Accept: application/json
+Content-Type: application/json
+X-Auth-Token:887665443383838
+Content-Length: 826
+{
+   "member" :  {
+                "admin_state_up": false
+              }
+}
 </nowiki></pre>
-'''Example 4.24. List Virtual IPs Response: JSON'''
+JSON Response:
 <pre><nowiki>#!highlight javascript numbers=disable
+ACCEPTED
+Content-Type: application/json
+Content-Length: 917
 {
-   "virtualIps": [
+   "member" : {
-                 {
+                "id":"c57f581b-c834-408f-93fa-30543cf30618",
-                   "id": "1021",
+                "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
-                   "address": "206.10.10.210",
+                "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
-                   "type": "PUBLIC",
+                "address": "192.168.224.31",
-                   "ipVersion": "IPV4"
+                "port": 8080,
-                 }
+                "weight" : 1,
-                ]
+                "admin_state_up" : false,
+                "status" : "PENDING_UPDATE"
+             }
 }
 </nowiki></pre>
-=== Usage Reports ===
+==== Remove a Member ====
-==== List Usage ====
 {| border="1" cellpadding="2" cellspacing="0"
-| '''Name'''
+| '''Verb'''
 | '''URI'''
 | '''Description'''
 |-
-| GET
+| DELETE
-| /loadbalancers/''loadBalancerId''/usage
+| /v1.0/members/''member_id''
-| List current and historical usage.
+| Removes a member from a pool.
 |}
-'''Normal Response Code(s): 200'''
+'''Normal Response Code(s)''': 200, 202
 '''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
@@ Line 1,190: / Line 1,498: @@
 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.
+This operation does not return a response body.
+'''Example 4.21. remove a member from its pool '''
-'''Example 4.25. Report Load Balancer Usage Response: XML'''
+JSON Request:
-<pre><nowiki>#!highlight xml numbers=disable
+<pre><nowiki>#!highlight javascript numbers=disable
-<loadBalancerUsageRecords xmlns="http://docs.openstack.org/atlas/api/v1.1">
+DELETE /v1.0/members/c57f581b-c834-408f-93fa-30543cf30618
-   <loadBalancerUsageRecord  id="394"  transferBytesIn="2819204"
+Host: lbaas-service.cloudX.com:8651
-                             transferBytesOut="84923069" />
+Accept: application/json
-   <loadBalancerUsageRecord  id="473" transferBytesIn="0" transferBytesOut="0" />
+X-Auth-Token:887665443383838
-</loadBalancerUsageRecords>
 </nowiki></pre>
-'''Example 4.26. Report Load Balancer Usage Response: JSON'''
+JSON RESPONSE
 <pre><nowiki>#!highlight javascript numbers=disable
-{
+Accepted
-  "loadBalancerUsageRecords": [
-                                {
-                                  "id": "394",
-                                  "transferBytesIn": "2819204",
-                                  "transferBytesOut": "84923069"
-                                },
-                                {
-                                  "id": "473",
-                                  "transferBytesIn": "0",
-                                  "transferBytesOut": "0"
-                                }
-                              ]
-}
 </nowiki></pre>
-=== Monitors ===
+=== Health Monitors ===
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Verb'''
 | '''URI'''
-| '''Description'''
 |-
 | GET
-| /loadbalancers/''loadBalancerId''/healthmonitor
+| /v1.0/healthmonitors/
-| Retrieve the health monitor configuration, if one exists.
+|-
+| GET
+| /v1.0/healthmonitors/''healthmonitor_id''
 |-
 | PUT
-| /loadbalancers/''loadBalancerId''/healthmonitor
+| /v1.0/healthmonitors/''healthmonitor_id''
 | Update the settings for a health monitor.
 |-
 | DELETE
-| /loadbalancers/loadBalancerId/healthmonitor
+| /v1.0/healthmonitors/''healthmonitor_id''
 | Remove the health monitor.
 |}
@@ Line 1,245: / Line 1,542: @@
 '''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.
@@ Line 1,256: / Line 1,551: @@
 | '''Name'''
 |-
-| CONNECT
+| PING
+|-
+| TCP
 |-
 | HTTP
@@ Line 1,263: / Line 1,560: @@
 |}
-===== Monitor CONNECT =====
+The required attributes to specify when creating a health monitor depend on the health monitor type.
-The monitor connects to each node on its defined port to ensure that the node is listening properly.
+==== Create a PING Health Monitor ====
+The monitor pings the member to ensure that the member is alive.
-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:
+The PING monitor is the most basic type of health check. The following configurable properties can be specified
-* '''delay''': This is the minimum time in seconds between regular calls to a monitor.
+* '''delay''': This is the minimum time in seconds between regular pings of the member.
-* '''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.
+* '''timeout''': Maximum number of seconds for a monitor to  wait for a ping reply 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.
+* '''attemptsBeforeDeactivation''': Number of permissible ping failures before changing the member's status to INACTIVE. Must be a number between 1 and 10.
-'''Example 4.27. Monitor CONNECT Request: XML'''
+'''Example 4.27. Monitor PING'''
 <pre><nowiki>#!highlight xml numbers=disable
-<healthMonitor xmlns="http://docs.openstack.org/atlas/api/v1.1"
+POST /v1.0/healthmonitors
-               type="CONNECT" delay="20" timeout="10"
+Host: lbaas-service.cloudX.com:8651
-               attemptsBeforeDeactivation="3" />
+Accept: application/json
+Content-Type: application/json
+X-Auth-Token:887665443383838
+Content-Length: 91
+{
+    "healthmonitor" :
+      {
+         "type" : "PING",
+         "delay" : 20,
+         "timeout": 10,
+         "attemptsBeforeDeactivation": 3
+      }
+}
 </nowiki></pre>
-'''Example 4.28. Monitor CONNECT Request: JSON'''
+JSON Response:
-<pre><nowiki>#!highlight javascript numbers=disable
+<pre><nowiki>#!highlight xml numbers=disable
+Accepted
+Content-Type: application/json
+Content-Length: 114
 {
-  "type": "CONNECT",
+    "healthmonitor" :
-  "delay": "20",
+      {
-  "timeout": "10",
+         "id" : "f784c3a7-c4e8-44da-bf12-5ff417d27555",
-  "attemptsBeforeDeactivation": "3"
+         "type" : "PING",
+         "delay" : 20,
+         "timeout": 10,
+         "attemptsBeforeDeactivation": 3,
+         "admin_state_up": true,
+         "status": "PENDING_CREATE"
+      }
 }
 </nowiki></pre>
-'''Example 4.29. Monitor Connections Response: XML'''
+==== Create a TCP Health Monitor ====
+A TCP monitor tries to establish a TCP connection to the member to ensure that the member is healthy.
+The following configurable properties can be specified for a TCP monitor:
+* '''delay''': This is the minimum time in seconds between regular connections of the member.
+* '''timeout''': Maximum number of seconds for a monitor to  wait for a connection to be established before it times out. The value must be less than the delay value.
+* '''attemptsBeforeDeactivation''': Number of permissible connection failures before changing the member's status to INACTIVE. Must be a number between 1 and 10.
+'''Example. Monitor TCP'''
 <pre><nowiki>#!highlight xml numbers=disable
-<healthMonitor xmlns="http://docs.openstack.org/atlas/api/v1.1"
+POST /v1.0/healthmonitors
-               type="CONNECT" delay="10" timeout="10"
+Host: lbaas-service.cloudX.com:8651
-               attemptsBeforeDeactivation="3" />
+Accept: application/json
+Content-Type: application/json
+X-Auth-Token:887665443383838
+Content-Length: 91
+{
+    "healthmonitor" :
+      {
+         "type" : "TCP",
+         "delay" : 20,
+         "timeout": 10,
+         "attemptsBeforeDeactivation": 3
+      }
+}
 </nowiki></pre>
-'''Example 4.30. Monitor Connections Response: JSON'''
+JSON Response:
-<pre><nowiki>#!highlight javascript numbers=disable
+<pre><nowiki>#!highlight xml numbers=disable
+Accepted
+Content-Type: application/json
+Content-Length: 114
 {
-  "type": "CONNECT",
+    "healthmonitor" :
-  "delay": "20",
+      {
-  "timeout": "10",
+         "id" : "e5069610-744b-42a7-8bd8-ceac1a229cd4",
-  "attemptsBeforeDeactivation": "3"
+         "type" : "TCP",
+         "delay" : 20,
+         "timeout": 10,
+         "attemptsBeforeDeactivation": 3,
+         "admin_state_up": true,
+         "status": "PENDING_CREATE"
+      }
 }
 </nowiki></pre>
-===== Monitor HTTP and HTTPS =====
+==== Create an HTTP or an HTTPS Health Monitor ====
-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.
+The HTTP and HTTPS monitor is more intelligent than the TCP 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 TCP 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.
+* '''path''': The HTTP path used in the HTTP request used by the monitor to test a member's health. 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'''
+'''Example. Monitor TCP'''
 <pre><nowiki>#!highlight xml numbers=disable
-<healthMonitor xmlns="http://docs.openstack.org/atlas/api/v1.1"
+POST /v1.0/healthmonitors
-               type="HTTP" delay="10" timeout="3" attemptsBeforeDeactivation="2"
+Host: lbaas-service.cloudX.com:8651
-               path="/"
+Accept: application/json
-/>
+Content-Type: application/json
+X-Auth-Token:887665443383838
+Content-Length: 91
+{
+    "healthmonitor" :
+      {
+         "type" : "HTTP",
+         "delay" : 20,
+         "timeout": 10,
+         "attemptsBeforeDeactivation": 3,
+         "path" : "/check",
+         "error_codes" : "200-299"
+      }
+}
 </nowiki></pre>
-'''Example 4.32. Monitor HTTPS Response: XML'''
+JSON Response:
 <pre><nowiki>#!highlight xml numbers=disable
-<healthMonitor xmlns="http://docs.openstack.org/atlas/api/v1.1"
+Accepted
-               type="HTTPS" delay="10" timeout="3"
+Content-Type: application/json
-               attemptsBeforeDeactivation="3"
+Content-Length: 114
-               path="/healthcheck"
-/>
-</nowiki></pre>
-'''Example 4.33. Monitor HTTPS Response: JSON'''
-<pre><nowiki>#!highlight javascript numbers=disable
 {
-   "type": "HTTPS",
+    "healthmonitor" :
-   "delay": "10",
+      {
-   "timeout": "3",
+         "id" : "f3eeab00-8367-4524-b662-55e64d4cacb5",
-   "attemptsBeforeDeactivation": "3",
+         "type" : "HTTP",
-   "path": "/healthcheck"
+         "delay" : 20,
+         "timeout": 10,
+         "attemptsBeforeDeactivation": 3,
+         "path" : "/check",
+         "error_codes" : "200-299",
+         "admin_state_up": true,
+         "status": "PENDING_CREATE"
+      }
 }
 </nowiki></pre>
-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.
+==== Associate and Dissociate Health Monitors with Pools ====
+When a health monitor has been created, it can be associated with one or several pools.
-=== Sessions ===
-==== Manage Session Persistence ====
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Verb'''
 | '''URI'''
-| '''Description'''
 |-
 | GET
-| /loadbalancers/''loadBalancerId''/sessionpersistence
+| /v1.0/pools/''pool_id''/healthmonitors
-| List session persistence configuration.
 |-
-| PUT
+| POST
-| /loadbalancers/''loadBalancerId''/sessionpersistence
+| /v1.0/pools/''pool_id''/healthmonitors
-| Enable session persistence.
 |-
 | DELETE
-| /loadbalancers/''loadBalancerId''/sessionpersistence
+| /v1.0/pool_id/''pool_id''/healthmonitors/''healthmonitor_id''
-| Disable session persistence.
+| Dissociates a healthmonitor from a pool.
 |}
@@ Line 1,379: / Line 1,743: @@
 '''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.
+===== List all Health Monitors associated with a Pool =====
+'''Example. List health monitors for a pool'''
-'''Table 4.5. Session Persistence Modes'''
-{| border="1" cellpadding="2" cellspacing="0"
-| '''Name'''
-|-
-| HTTP_COOKIE
-|}
-'''Example 4.34. List Session Persistence Configuration Response: XML'''
+<pre><nowiki>#!highlight xml numbers=disable
+GET /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764/healthmonitors
+Host: lbaas-service.cloudX.com:8651
+Accept: application/json
+X-Auth-Token:887665443383838
+</nowiki></pre>
+JSON Response:
+<pre><nowiki>#!highlight xml numbers=disable
+OK
+Content-Type: application/json
+Content-Length: 114
+{
+    "healthmonitors" : [
+                         "f784c3a7-c4e8-44da-bf12-5ff417d27555",
+                         "e5069610-744b-42a7-8bd8-ceac1a229cd4"
+                       ]
+}
+</nowiki></pre>
+===== Associate Health Monitors with a Pool =====
+You can associate one or several health monitors with a pool. Once associated, the health monitors will start monitoring the members of the pool and will deactivate these members if they are deemed unhealthy. A member can be disactivated (status set to INACTIVE) if any of health monitors finds its unhealthy.
+The response will return the current list of all health monitors associated with the pool.
+'''Example. Add a health monitor to the monitors for a pool'''
 <pre><nowiki>#!highlight xml numbers=disable
-<sessionPersistence xmlns="http://docs.openstack.org/atlas/api/v1.1"
+POST /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764/healthmonitors
-                    persistenceType="HTTP_COOKIE" />
+Host: lbaas-service.cloudX.com:8651
+Accept: application/json
+X-Auth-Token:887665443383838
+{
+    "healthmonitors" : [
+                         "f3eeab00-8367-4524-b662-55e64d4cacb5"
+                       ]
+}
 </nowiki></pre>
-'''Example 4.35. List Session Persistence Configuration Response: JSON'''
+JSON Response:
-<pre><nowiki>#!highlight javascript numbers=disable
+<pre><nowiki>#!highlight xml numbers=disable
+Accepted
+Content-Type: application/json
+Content-Length: 114
 {
-   "persistenceType":"HTTP_COOKIE"
+    "healthmonitors" : [
+                         "f784c3a7-c4e8-44da-bf12-5ff417d27555",
+                         "e5069610-744b-42a7-8bd8-ceac1a229cd4",
+                         "f3eeab00-8367-4524-b662-55e64d4cacb5"
+                       ]
 }
 </nowiki></pre>
-'''Example 4.36. Set Session Persistence Type Request: XML'''
+Note that the pool status will change to PENDING_UPDATE while the association is processed. A pool status of ACTIVE indicates that the change has successfully taken place.
+===== Dissociate Health Monitors from a Pool =====
+you can dissociate a health monitor from a pool. When dissociation is successful, the health monitor will no longer check for the health of the members of the pool.
+Note that the pool status will change to PENDING_UPDATE while the dissociation is processed. A pool status of ACTIVE indicates that the change has successfully taken place.
+'''Example. Dissociate a health monitor from a pool'''
 <pre><nowiki>#!highlight xml numbers=disable
-<sessionPersistence xmlns="http://docs.openstack.org/atlas/api/v1.1"
+DELETE /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764/healthmonitors/f3eeab00-8367-4524-b662-55e64d4cacb5
-                    persistenceType="HTTP_COOKIE" />
+Host: lbaas-service.cloudX.com:8651
+Accept: application/json
+X-Auth-Token:887665443383838
 </nowiki></pre>
-'''Example 4.37. Set Session Persistence Type Request: JSON'''
+JSON Response:
-<pre><nowiki>#!highlight javascript numbers=disable
+<pre><nowiki>#!highlight xml numbers=disable
-{
+Accepted
-    "persistenceType":"HTTP_COOKIE"
-}
 </nowiki></pre>
-=== Connections ===
+=== Statistics ===
-==== Throttle Connections ====
+==== List Traffic Statistics of a pool ====
 {| border="1" cellpadding="2" cellspacing="0"
-| '''Verb'''
+| '''Name'''
 | '''URI'''
 | '''Description'''
 |-
 | GET
-| /loadbalancers/''loadBalancerId''/connectionthrottle
+| /v1.0/pools/''pool_id''/stats
-| 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
+'''Normal Response Code(s): 200'''
 '''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.
+This operation does not require a request body.
-* '''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.
-<pre><nowiki>#!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.
+The pool stats reports provide a set of stats counters. This list will contain at least the following counters:
-</nowiki></pre>
-'''Example 4.42. List Connection Throttling Configuration Response: XML'''
+* ''bytes_in'': The total number of bytes that pool members have received from clients.
+* ''bytes_out'': The total number of bytes that pool members have sent to clients.
+* ''active_connections'': The current number of active connections being served by the pool members.
+* ''total_connections'': The total number of connections that have been processed by the pool members.
+'''Example 4.25. Retrieve the stats for a pool'''
-<pre><nowiki>#!highlight xml numbers=disable
-<connectionThrottle xmlns="http://docs.openstack.org/atlas/api/v1.1"
-                    maxRequestRate="50" rateInterval="60" />
-</nowiki></pre>
-'''Example 4.43. List Connection Throttling Configuration Response: JSON'''
+<pre><nowiki>#!highlight json numbers=disable
+GET /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764/stats
+Host: lbaas-service.cloudX.com:8651
-<pre><nowiki>#!highlight javascript numbers=disable
+Accept: application/json
-{
+X-Auth-Token:887665443383838
-    "maxRequestRate": "50",
-    "rateInterval": "60"
-}
 </nowiki></pre>
-'''Example 4.44. Update Connection Throttling Configuration Request: XML'''
+JSON Response:
 <pre><nowiki>#!highlight xml numbers=disable
-<connectionThrottle xmlns="http://docs.openstack.org/atlas/api/v1.1"
+OK
-                    maxRequestRate="40" />
+Content-Type: application/json
-</nowiki></pre>
+Content-Length: 114
-'''Example 4.45. Update Connection Throttling Configuration Request: JSON'''
-<pre><nowiki>#!highlight javascript numbers=disable
 {
-   "maxRequestRate": "40"
+    "stats" : {
+                         "bytes_in" : 36839202,
+                         "bytes_out" : 673193022,
+                         "active_connections" : 39,
+                         "total_connections" : 682
+              }
 }
 </nowiki></pre>
 === Protocols ===
-==== List Load Balancing Protocols ====
+==== List Supported Load Balancing Protocols ====
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Verb'''
 | '''URI'''
-| '''Description'''
 |-
 | GET
-| /protocols
+| /v1.0/protocols
-| List all supported load balancing protocols.
 |}
@@ Line 1,511: / Line 1,900: @@
 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.
+All vips and members must be configured with a protocol value from this list. The vip's protocol and the pool's protocol must be compatible with each other, which in this version of the API specification means that they have to be identical.
-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.
+All LBaaS implementations of this specification must support at least the following protocols:
-'''Example 4.46. List Load Balancing Protocols Response: XML'''
+* TCP
+* HTTP
+* HTTPS
+When the protocol is HTTPS, the traffic received on the vip is SSL-encrypyted and will be forwaded as is to the pool members. The traffic is not decrypted by the load balancers. Because, requests are opaque, the HTTP_COOKIE session persistence cannot be configured when the vip's protocol is HTTPS.
-<pre><nowiki>#!highlight xml numbers=disable
+'''Example: Listing protocols supported '''
-<protocols xmlns="http://docs.openstack.org/atlas/api/v1.1">
-     <protocol name="HTTP" port="80" />
-     <protocol name="HTTPS" port="443" />
-     <protocol name="TCP" port="*" />
-</protocols>
-</nowiki></pre>
-'''Example 4.47. List Load Balancing Protocols Response: JSON'''
@@ Line 1,532: / Line 1,916: @@
 {
   "protocols": [
+               {
+                 "name": "TCP",
+               },
                 {
                   "name": "HTTP",
-                 "port": "80"
                 },
                 {
                   "name": "HTTPS",
-                 "port": "443"
-               },
-               {
-                 "name": "TCP",
-                 "port": "*"
                 }
                ]
@@ Line 1,548: / Line 1,929: @@
 </nowiki></pre>
-=== Algorithms ===
+=== LB Methods ===
-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.
+All LB methods utilize an algorithm that defines how a member is chosen to process a new request or a connection that arrives on a vip. The default algorithm for newly created vips is ROUND_ROBIN, which can be overridden at creation time or changed after the vip 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.
@@ Line 1,562: / Line 1,943: @@
 |}
-==== List Load Balancing Algorithms ====
+==== Listing Supported Load Balancing Methods ====
 {| border="1" cellpadding="2" cellspacing="0"
 | '''Verb'''
 | '''URI'''
-| '''Description'''
 |-
 | GET
-| /algorithms
+| /v1.0/lb_methods
-| List all supported load balancing algorithms.
 |}
@@ Line 1,582: / Line 1,961: @@
-<pre><nowiki>#!highlight xml numbers=disable
+<pre><nowiki>#!highlight javascript numbers=disable
-<algorithms xmlns="http://docs.openstack.org/atlas/api/v1.1">
+OK
-   <algorithm name="ROUND_ROBIN" />
+Content-type: application/json
-   <algorithm name="LEAST_CONNECTIONS" />
+Content-length: 362
-</algorithms>
-</nowiki></pre>
-'''Example 4.49. List Load Balancing Algorithms Response: JSON'''
-<pre><nowiki>#!highlight javascript numbers=disable
 {
-    "algorithms": [
+    "lb_methods": [
                    {
                      "name": "ROUND_ROBIN"
@@ Line 1,604: / Line 1,977: @@
 }
 </nowiki></pre>
-== 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.

Difference between revisions of "Neutron/LBaaS/API"

Latest revision as of 15:54, 21 June 2013

Contents

OpenStack LBaaS API 1.0

Overview

Intended Audience

Document Change History

Resources

Chapter 1. Overview

High-Level Task Flow

Concepts

VIP

Pool

Pool Member

Health Monitoring

Session Persistence

Connection Limits

Chapter 2. General API Information

Authentication and Authorization

Request/Response Types

Filtering and Column Selection

Synchronous versus Asynchronous Plugin Behavior

Bulk Create Operations

Quotas

Notifications

Extensions

Faults

Chapter 3. API Operations

VIPs

List all VIPs

Retrieve a specific VIP

Create a VIP

Update a VIP

Remove a VIP

Pools

List all Pools

Retrieve a specific Pool

Create a Pool

Update a Pool

Remove a Pool

Pool Members

List all Members

List all Members of a specific Pool

Retrieve a specific Member

Bulk Create Members

Update a Member

Remove a Member

Health Monitors

Create a PING Health Monitor

Create a TCP Health Monitor

Create an HTTP or an HTTPS Health Monitor

Associate and Dissociate Health Monitors with Pools

List all Health Monitors associated with a Pool

Associate Health Monitors with a Pool

Dissociate Health Monitors from a Pool

Statistics

List Traffic Statistics of a pool

Protocols

List Supported Load Balancing Protocols

LB Methods

Listing Supported Load Balancing Methods