Jump to: navigation, search

Difference between revisions of "Neutron/LBaaS/API 1.0"

< Neutron‎ | LBaaS
m (ThierryCarrez moved page Quantum/LBaaS/API 1.0 to Neutron/LBaaS/API 1.0)
 
(71 intermediate revisions by 3 users not shown)
Line 1: Line 1:
__NOTOC__
+
 
 
<!-- #acl [[YoucefLaribi]]:read,write,delete,revert,admin [[UmaGoring]]:read,write,delete,revert,admin All:read -->
 
<!-- #acl [[YoucefLaribi]]:read,write,delete,revert,admin [[UmaGoring]]:read,write,delete,revert,admin All:read -->
 
= [[OpenStack]] LBaaS API 1.0 (draft) =
 
= [[OpenStack]] LBaaS API 1.0 (draft) =
<<[[TableOfContents]]()>>
+
__TOC__
  
 
== Overview ==
 
== Overview ==
Line 8: Line 8:
 
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 service, the [[OpenStack]] Quantum service, and the integration between the two.
+
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 know how to obtain authentication tokens from the [[OpenStack]] [[KeyStone]] service.
  
 
You should also be familiar with:
 
You should also be familiar with:
Line 22: Line 22:
 
|-
 
|-
 
| Oct, 25 2012  
 
| Oct, 25 2012  
 +
|-
 +
| Nov, 5 2012
 +
|-
 +
| Nov, 19 2012
 +
|-
 +
| Dec, 6 2012
 +
|-
 +
| Dec, 10 2012
 +
|-
 +
| Dec, 21 2012
 +
|-           
 +
| Dec, 24 2012
 +
|-           
 +
| Mar, 11 2013
 
|}
 
|}
  
Line 37: Line 51:
 
Th capabilities provided by the LBaaS service are:
 
Th capabilities provided by the LBaaS service are:
  
  <tbd>
+
* Load balancing client traffic coming from one network to application services (e.g. VMs) present on the same or a different network.
 +
* Supporting load balancing for several protocols
 +
* Supporting session persistence
 +
* Monitoring the health of the application services
 +
* Protecting the application services against Denial of Service (DoS) attacks
 +
* Collecting traffic statistics on the incoming client traffic.
  
 
=== High-Level Task Flow ===
 
=== High-Level Task Flow ===
 
The high-level task flow for using LBaaS API to configure load balancing is as follows:
 
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 creates a Pool, which is initially empty
* The tenant create one or several members in the pool
+
* The tenant creates one or several Members in the Pool
* The tenant create one or several health monitors
+
* The tenant create one or several Health Monitors
* The tenant associates the health monitors with the pool
+
* The tenant associates the Health Monitors with the Pool
* The tenant creates a vip with the pool
+
* The tenant finally creates a VIP with the Pool
  
 
=== Concepts ===
 
=== Concepts ===
Line 53: Line 72:
 
==== VIP ====
 
==== 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".
 
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".
 +
 +
 +
<pre><nowiki>#!wiki caution
 +
Note
 +
 +
In the tradional load balancing vernacular, the term 'VIP' is used to denote the IP address to which clients connect. As it is defined in this document, this IP address is only one attribute of the VIP object.
 +
</nowiki></pre>
  
 
==== Pool ====
 
==== 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.
+
A load balancing pool is a logical set of devices, such as web servers, that you group together to receive and process traffic. The load balancing 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 ====
 
==== Pool Member ====
Line 67: Line 93:
 
* HTTP: used to send an HTTP request to the member.
 
* HTTP: used to send an HTTP request to the member.
 
* HTTPS: used to send a secure HTTP request to the member.
 
* HTTPS: used to send a secure HTTP request to the member.
 +
 +
When a pool has several monitors associated with it, each member of the pool is monitored by all these monitors. If any monitor declares the member as unhealthy, then the member status is changed to INACTIVE and the member won't participate in its pool's load balancing. In other words, ALL monitors must declare the member to be healthy for it to stay ACTIVE.
  
 
==== Session Persistence ====
 
==== Session Persistence ====
Line 72: Line 100:
  
 
* 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.
 
* 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.
+
* HTTP_COOKIE: With this persistence mode, the load balancing function 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.
+
* APP_COOKIE: With this persistence mode, the load balancing function 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 ====
 
==== 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.
+
To control incoming traffic on the VIP address as well as traffic for each member of a pool, you can set a connection limit on the VIP or on the pool, 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 of the pool 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.
 
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.
Line 86: Line 114:
 
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 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.
+
Users with non-admin roles, can only perform CRUD (Create, Retrieve, Update and Delete) operations on the resources they own. Users with admin roles (as configured in the Keystone service) can operate on other tenant resources by specifying a "tenant_id" attribute in the resource's representation when creating or updating, and by specifying a "tenant_id" query string when retrieving or deleting.
  
 
LBaaS uses information received from Keystone to authorize user requests. LBaaS handles the following types of authorization policies:
 
LBaaS uses information received from Keystone to authorize user requests. LBaaS handles the following types of authorization policies:
Line 99: Line 127:
  
 
=== Request/Response Types ===
 
=== 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.
+
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 should accept JSON serialized responses by specifying the Accept header with the MIME type value "application/json" or adding ".json" extension to the resource name. The default response format is "application/json" if the client omits to specify an Accept header or append the ".json" extension in the URL path.
  
 
Example:
 
Example:
Line 119: Line 147:
 
The LBaaS API v1.0 supports filtering based on all top level attributes of a resource. Filters are applicable to all list requests.
 
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:
+
For example, the following request returns all VIPs named foobar:
  
  
Line 137: Line 165:
 
Alternatively, you can issue a distinct request for each filter and build a response set from the received responses on the client-side.
 
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.
+
By default, the LBaaS service returns all attributes for any show or list call. The LBaaS API v1.0 has a mechanism to limit the set of attributes returned. You can use the fields query parameter to control the attributes returned from the LBaaS API v1.0.
 
 
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:
+
For example, the following request returns only id,name,subnet_id,address and protocol_port for each vip:
  
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
GET /v1.0/vips.json?fields=id&fields=name&fields=network_id&fields=address&fields=port
+
GET /v1.0/vips.json?fields=id&fields=name&fields=subnet_id&fields=address&fields=protocol_port
 
</nowiki></pre>
 
</nowiki></pre>
 +
  
 
=== Synchronous versus Asynchronous Plugin Behavior ===
 
=== 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.
 
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.
+
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 load balancing function. 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.
+
For example, if a client issues an HTTP POST request on the members resource to add a new 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.
+
You can use the status attribute of the VIP, the Pool, the pool Member or the Health Monitor to determine whether the LBaaS plugin has successfully completed the configuration of the resource.
  
 
'''Table 4.1. Status Values '''
 
'''Table 4.1. Status Values '''
Line 174: Line 201:
 
|}
 
|}
  
=== Bulk Create Operations ===
+
When status is set to "ERROR" in an object returned by the LBaaS service, then the returned object might also contain an extra attribute called "error_details" which provides textual explanation on the error, its cause, and possibly a way for the user to remedy the situation.
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.
+
=== Update Operations ===
  
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.
+
The update operations of resources use the HTTP PUT method with "patch" semantics (as opposed to "replace" semantics), meaning that the attributes submitted in the PUT request are changed on the resource while the attributes that haven't been submitted in the update operation keep their previous values in the resource.
  
For information about how to submit bulk requests to the LBaaS API v1.0, see the section called “Bulk Create Members” section.
+
Also, note that not all attributes of a resource can be updated. This is described in the "update" operation on each resource.
  
 
=== Quotas ===
 
=== Quotas ===
Line 242: Line 268:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
409 Conflict
+
HTTP/1.1 409 Conflict
 
Content-type: application/json
 
Content-type: application/json
 
Content-lentgh:78
 
Content-lentgh:78
Line 248: Line 274:
 
{
 
{
 
   "errorcode": 409,
 
   "errorcode": 409,
   "errormessage": "pool is already used by an existing VIP"
+
   "errormessage": "pool 'cfc6589d-f949-4c66-99d2-c2da56ef3764' is already used by VIP 'db902c0c-d5ff-4753-b465-668ad9656918' "
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
Line 257: Line 283:
  
 
=== VIPs ===
 
=== VIPs ===
Use the LBaaS API v1.0 to manage network resources
+
Use the following APIs to manage vip resources
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 282: Line 308:
 
| Verb  
 
| Verb  
 
| URI  
 
| URI  
| Description
 
 
|-
 
|-
 
| GET  
 
| GET  
Line 288: Line 313:
 
|}
 
|}
  
'''Normal Response Code(s)''': 202
+
'''Normal Response Code(s)''': 200
  
 
'''Error Response Code(s)''': 401 (Unauthorized), 500 (Internal server error), 503 (Service Unavailable)
 
'''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 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 does not require a request body.
Line 302: Line 327:
 
* name
 
* name
 
* description
 
* description
* network_id
+
* subnet_id
 
* address
 
* address
* port
+
* port_id
* lbmethod
+
* protocol_port
 
* protocol
 
* protocol
 
* pool_id
 
* pool_id
Line 313: Line 338:
 
* status
 
* status
  
'''Example . List vips'''
+
'''Example . List all VIPs'''
  
 
JSON Request:
 
JSON Request:
Line 329: Line 354:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
200 OK
+
HTTP/1.1 200 OK
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 384
 
Content-Length: 384
Line 340: Line 365:
 
           "name": "web_vip",
 
           "name": "web_vip",
 
           "description": "lb config for the web tier",
 
           "description": "lb config for the web tier",
           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
+
           "subnet_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
 
           "address" : "10.30.176.47",
 
           "address" : "10.30.176.47",
 +
          "port_id" : "cd1f7a47-4fa6-449c-9ee7-632838aedfea",
 
           "protocol": "HTTP",
 
           "protocol": "HTTP",
           "port": 80,
+
           "protocol_port": 80,
          "lb_method": "ROUND_ROBIN",
 
 
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
           "admin_state_up": true,
 
           "admin_state_up": true,
Line 353: Line 378:
 
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
           "name": "db_vip",
 
           "name": "db_vip",
           "network_id": "9cedb85d-0759-4898-8a4b-fa5a5ea10086",
+
           "subnet_id": "9cedb85d-0759-4898-8a4b-fa5a5ea10086",
 
           "address" : "10.30.176.48",
 
           "address" : "10.30.176.48",
 +
          "port_id" : "cd1f7a47-4fa6-449c-9ee7-632838aedfea",
 
           "protocol": "TCP",
 
           "protocol": "TCP",
           "port": 3306,
+
           "protocol_port": 3306,
          "lb_method": "LEAST_CONNECTIONS",
 
 
           "pool_id" : "41efe233-7591-43c5-9cf7-923964759f9e",
 
           "pool_id" : "41efe233-7591-43c5-9cf7-923964759f9e",
 
           "session_persistence" : {"type" : "SOURCE_IP"},
 
           "session_persistence" : {"type" : "SOURCE_IP"},
Line 372: Line 397:
 
| Verb  
 
| Verb  
 
| URI  
 
| URI  
| Description
 
 
|-
 
|-
 
| GET  
 
| GET  
Line 378: Line 402:
 
|}
 
|}
  
'''Normal Response Code(s)''': 202
+
'''Normal Response Code(s)''': 200
  
'''Error Response Code(s)''': 401 (Unauthorized), 404 (Not Found), 409 (Conflict), 413 (Over limit), 500 (Internal server error), 503 (Service Unavailable)
+
'''Error Response Code(s)''': 401 (Unauthorized), 403 (Forbidden), 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 returns a VIP object identified by ''vip_id''. If the user is not an admin, and the VIP object doesn't belong to her tenant account, she would receive a 403 (Forbidden) error.
  
 
This operation does not require a request body.
 
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:
+
This operation returns a response body. On success, the returned element is a VIP that can contain the following attributes:
  
 
* id
 
* id
Line 392: Line 416:
 
* name
 
* name
 
* description
 
* description
* network_id
+
* subnet_id
 
* address
 
* address
* port
+
* port_id
* lb_method
+
* protocol_port
 
* protocol
 
* protocol
 
* pool_id
 
* pool_id
Line 419: Line 443:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
200 OK
+
HTTP/1.1 200 OK
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 156
 
Content-Length: 156
Line 429: Line 453:
 
           "name": "db_vip",
 
           "name": "db_vip",
 
           "description": "lb config for the MYSQL db tier",
 
           "description": "lb config for the MYSQL db tier",
           "network_id": "9cedb85d-0759-4898-8a4b-fa5a5ea10086",
+
           "subnet_id": "9cedb85d-0759-4898-8a4b-fa5a5ea10086",
 
           "address" : "10.30.176.47",
 
           "address" : "10.30.176.47",
 +
          "port_id" : "cd1f7a47-4fa6-449c-9ee7-632838aedfea",
 
           "protocol": "TCP",
 
           "protocol": "TCP",
           "port": 3306,
+
           "protocol_port": 3306,
          "lb_method": "LEAST_CONNECTIONS",
 
 
           "pool_id" : "41efe233-7591-43c5-9cf7-923964759f9e",
 
           "pool_id" : "41efe233-7591-43c5-9cf7-923964759f9e",
 
           "session_persistence" : {"type" : "SOURCE_IP"},
 
           "session_persistence" : {"type" : "SOURCE_IP"},
Line 447: Line 471:
 
| Verb  
 
| Verb  
 
| URI  
 
| URI  
| Description
 
 
|-
 
|-
 
| POST  
 
| POST  
Line 466: Line 489:
  
 
* name
 
* name
* tenant_id: only if a user has an admin role can he specify a tenant_id different from her's.
+
* tenant_id: only required if the caller has an admin role and wants to create a VIP for another tenant.
* 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).
+
* subnet_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.
 
* protocol: the protocol of the vip address.
* port: the port on which to listen for client traffic that is associated with the vip address.
+
* protocol_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.
 
* 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:
 
Some attributes will receive default values if not specified in the request:
  
* lb_method: the default method is ROUND_ROBIN
+
* service_type: The service type used to create the VIP will be the default service type configured in the LBaaS Service.
* admin_state_up: The default configuration state for a vip is UP, so the default value for this attribute is true.
+
* admin_state_up: The default value for this attribute is true.
 +
 
 +
Also note that the pool_id should refer to a pool that is not already associated with another vip. If the pool is already used by another vip, then this creation operation will fail with a 409 Conflict error.
  
 
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.
 
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.
Line 496: Line 521:
  
 
{
 
{
   "vips":[
+
   "vip": {
        {
 
 
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
           "name": "web_vip",
 
           "name": "web_vip",
           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
+
           "subnet_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
           "protocol": "HTTP",
+
           "protocol": "HTTPS",
           "port": 80,
+
           "protocol_port": 443,
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764"
+
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 +
          "session_persistence" : {"type":"APP_COOKIE", "cookie_name":"jsessionid"}
 
         }
 
         }
      ]
 
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
Line 513: Line 537:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
202 Accepted
+
HTTP/1.1 202 Accepted
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 213
 
Content-Length: 213
  
 
{
 
{
   "vips":[
+
   "vip": {
        {
 
 
           "id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
 
           "id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
 
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
           "name": "web_vip",
 
           "name": "web_vip",
           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
+
           "subnet_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
 
           "address" : "10.30.176.47",
 
           "address" : "10.30.176.47",
 +
          "port_id" : "cd1f7a47-4fa6-449c-9ee7-632838aedfea",
 
           "protocol": "HTTPS",
 
           "protocol": "HTTPS",
           "port": 443,
+
           "protocol_port": 443,
          "lb_method": "ROUND_ROBIN",
 
 
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 +
          "session_persistence" : {"type":"APP_COOKIE", "cookie_name":"jsessionid"},
 
           "admin_state_up": true,
 
           "admin_state_up": true,
 
           "status": "PENDING_CREATE"
 
           "status": "PENDING_CREATE"
 
         }
 
         }
      ]
 
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
  
  
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.
+
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 VIP's network.  
  
Once an address is allocated to the user, the user can create other VIP objects using the same address but with different ports.
+
Once an address is allocated to the user, the user can create other VIP objects using the same address but with different protocol ports.
  
 
'''Example. Create a VIP with an address shared with another VIP '''  
 
'''Example. Create a VIP with an address shared with another VIP '''  
Line 554: Line 577:
  
 
{
 
{
   "vips":[
+
   "vip": {
        {
 
 
           "name": "ssl_vip",
 
           "name": "ssl_vip",
           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
+
           "subnet_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
 
           "address" : "10.30.176.47",
 
           "address" : "10.30.176.47",
 
           "protocol": "HTTPS",
 
           "protocol": "HTTPS",
           "port": 443,
+
           "protocol_port": 443,
 
           "pool_id" : "91c20e53-96cd-4476-8efc-627f398773bb"
 
           "pool_id" : "91c20e53-96cd-4476-8efc-627f398773bb"
 
         }
 
         }
      ]
 
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
 +
  
 
JSON Response:
 
JSON Response:
Line 571: Line 593:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
202 Accepted
+
HTTP/1.1 202 Accepted
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 282
 
Content-Length: 282
  
 
{
 
{
   "vips":[
+
   "vip": {
        {
 
 
           "id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
 
           "id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
 
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
           "name": "ssl_vip",
 
           "name": "ssl_vip",
           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
+
           "subnet_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
 
           "address" : "10.30.176.47",
 
           "address" : "10.30.176.47",
 +
          "port_id" : "cd1f7a47-4fa6-449c-9ee7-632838aedfea",
 
           "protocol": "HTTPS",
 
           "protocol": "HTTPS",
           "port": 443,
+
           "protocol_port": 443,
          "lb_method": "ROUND_ROBIN",
 
 
           "pool_id" : "91c20e53-96cd-4476-8efc-627f398773bb",
 
           "pool_id" : "91c20e53-96cd-4476-8efc-627f398773bb",
 +
          "session_persistence" : {"type":"APP_COOKIE", "cookie_name":"jsessionid"},
 
           "admin_state_up": true,
 
           "admin_state_up": true,
 
           "status": "PENDING_CREATE"
 
           "status": "PENDING_CREATE"
 
         }
 
         }
      ]
 
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
 +
  
 
==== Update a VIP ====
 
==== Update a VIP ====
Line 598: Line 620:
 
| '''Verb'''  
 
| '''Verb'''  
 
| '''URI'''  
 
| '''URI'''  
| '''Description'''
 
 
|-
 
|-
 
| PUT  
 
| PUT  
Line 606: Line 627:
 
'''Normal Response Code(s)''': 202
 
'''Normal Response Code(s)''': 202
  
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+
'''Error Response Code(s)''': serviceFault (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 object (using a GET operation) to wait for the changes to be applied.
 
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 object (using a GET operation) to wait for the changes to be applied.
Line 615: Line 636:
 
* description
 
* description
 
* pool_id
 
* pool_id
* lb_method
 
 
* session_persistence
 
* session_persistence
 
* connection_limit
 
* connection_limit
Line 626: Line 646:
 
Note
 
Note
  
The VIP'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 422 (Immutable) fault.
+
The VIP's ID, status, subnet_id, address, protocol_port and protocol are immutable attributes and cannot be modified once a VIP is created. Supplying an unsupported attribute will result in a 422 (Immutable) fault.
 
</nowiki></pre>
 
</nowiki></pre>
  
Line 654: Line 674:
 
           "name": "ssl_vip_1",
 
           "name": "ssl_vip_1",
 
           "description": "this VIP is used for secure web connections",
 
           "description": "this VIP is used for secure web connections",
          "lb_method": "LEAST_CONNECTIONS",
 
 
           "session_persistence": { "type": "HTTP_COOKIE" }
 
           "session_persistence": { "type": "HTTP_COOKIE" }
 
         }
 
         }
Line 664: Line 683:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
202 Accepted
+
HTTP/1.1 202 Accepted
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 282
 
Content-Length: 282
Line 673: Line 692:
 
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
           "name": "ssl_vip_1",
 
           "name": "ssl_vip_1",
           "network_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
+
           "subnet_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
 
           "address" : "10.30.176.47",
 
           "address" : "10.30.176.47",
 +
          "port_id" : "cd1f7a47-4fa6-449c-9ee7-632838aedfea",
 
           "protocol": "HTTPS",
 
           "protocol": "HTTPS",
           "port": 443,
+
           "protocol_port": 443,
          "lb_method": "LEAST_CONNECTIONS",
 
 
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
           "session_persistence": { "type": "HTTP_COOKIE" },
 
           "session_persistence": { "type": "HTTP_COOKIE" },
Line 691: Line 710:
 
| '''Verb'''  
 
| '''Verb'''  
 
| '''URI'''  
 
| '''URI'''  
| '''Description'''
 
 
|-
 
|-
 
| DELETE  
 
| DELETE  
Line 698: Line 716:
 
|}
 
|}
  
'''Normal Response Code(s)''': 202
+
'''Normal Response Code(s)''': 204
  
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+
'''Error Response Code(s)''': serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
 
This operation removes the specified VIP and its associated configuration from the tenant account. Any and all configuration data is immediately purged and is not recoverable.
 
This operation removes the specified VIP and its associated configuration from the tenant account. Any and all configuration data is immediately purged and is not recoverable.
Line 723: Line 741:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
202 Accepted
+
HTTP/1.1 204 No Content
 
</nowiki></pre>
 
</nowiki></pre>
  
  
 
=== Pools ===
 
=== 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 protocol and health monitors are configured on the pool, and all members of the same pool, will be monitored using these health monitors.
+
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 protocol and health monitors are configured on the pool, and all members of the same pool, will be monitored using these health monitors.
  
  
Line 734: Line 752:
 
Note
 
Note
  
Each VIP object can be associated with one pool. Also a pool cannot be used by more than one VIP object. It needs to be first removed from one VIP in order to be added to another. Once removed from a VIP, all the pool's stats are reset.
+
Each VIP object can be associated with one pool. Also a pool cannot be used by more than one VIP object. It needs to be first removed from one VIP in order to be added to another.
 
</nowiki></pre>
 
</nowiki></pre>
  
Line 742: Line 760:
 
| '''Verb'''  
 
| '''Verb'''  
 
| '''URI'''  
 
| '''URI'''  
| '''Description'''
 
 
|-
 
|-
 
| GET  
 
| GET  
Line 752: Line 769:
 
'''Normal Response Code(s)''': 200
 
'''Normal Response Code(s)''': 200
  
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+
'''Error Response Code(s)''': serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
 
This operation does not require a request body.
 
This operation does not require a request body.
  
'''Example. List pools Request:'''
+
This operation returns a response body. On success, the returned element is a (potentially empty) list, each element is a Pool object which can contain the following attributes:
 
 
JSON Request:
 
  
<pre><nowiki>#!highlight javascript numbers=disable
+
* id
 +
* tenant_id
 +
* vip_id
 +
* name
 +
* description
 +
* subnet_id
 +
* protocol
 +
* lb_method
 +
* members
 +
* health_monitors
 +
* admin_state_up
 +
* status
 +
 
 +
'''Example. List pools Request:'''
 +
 
 +
JSON Request:
 +
 
 +
<pre><nowiki>#!highlight javascript numbers=disable
 
GET /v1.0/pools.json
 
GET /v1.0/pools.json
 
Host: lbaas-service.cloudX.com:8651
 
Host: lbaas-service.cloudX.com:8651
Line 770: Line 802:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
200 OK
+
HTTP/1.1 200 OK
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 628
 
Content-Length: 628
Line 782: Line 814:
 
                 "name": "web_pool",
 
                 "name": "web_pool",
 
                 "protocol": "HTTP",
 
                 "protocol": "HTTP",
                 "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
+
                 "lb_method": "ROUND_ROBIN",
 +
                "subnet_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
 
                 "members" : [
 
                 "members" : [
 
                               "c57f581b-c834-408f-93fa-30543cf30618",
 
                               "c57f581b-c834-408f-93fa-30543cf30618",
Line 799: Line 832:
 
                 "vip_id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
 
                 "vip_id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
 
                 "protocol": "HTTPS",
 
                 "protocol": "HTTPS",
                 "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
+
                 "subnet_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
 +
                "lb_method" : "LEAST_CONNECTIONS",
 
                 "members" : [
 
                 "members" : [
 
                               "fcbf4e80-2fc7-4c7a-8a2e-8ea929620df9",
 
                               "fcbf4e80-2fc7-4c7a-8a2e-8ea929620df9",
Line 816: Line 850:
 
                 "vip_id": "36e08a3e-a78f-4b40-a229-1e7e23eee1ab",
 
                 "vip_id": "36e08a3e-a78f-4b40-a229-1e7e23eee1ab",
 
                 "protocol": "TCP",
 
                 "protocol": "TCP",
                 "network_id" : "ddc3ab81-1dac-4be3-a340-c7b7b5d89beb",
+
                 "subnet_id" : "ddc3ab81-1dac-4be3-a340-c7b7b5d89beb",
 +
                "lb_method": "ROUND_ROBIN",
 
                 "members" : [
 
                 "members" : [
 
                               "a24a6159-fc0f-4f42-ab10-5fe8763fef6e",
 
                               "a24a6159-fc0f-4f42-ab10-5fe8763fef6e",
Line 836: Line 871:
 
| '''Verb'''  
 
| '''Verb'''  
 
| '''URI'''  
 
| '''URI'''  
| '''Description'''
 
 
|-
 
|-
 
| GET  
 
| GET  
Line 846: Line 880:
 
'''Normal Response Code(s)''': 200
 
'''Normal Response Code(s)''': 200
  
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+
'''Error Response Code(s)''': serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
 
This operation does not require a request body.
 
This operation does not require a request body.
 +
 +
This operation returns a response body. On success, the returned Pool object can contain the following attributes:
 +
 +
* id
 +
* tenant_id
 +
* vip_id
 +
* name
 +
* description
 +
* subnet_id
 +
* protocol
 +
* lb_method
 +
* members
 +
* health_monitors
 +
* admin_state_up
 +
* status
 +
 +
Note that only attributes that have a value are returned in the response. For example if the pool is not associated with a vip, the vip_id attribute is not returned in the response payload.
  
 
'''Example. Retrieve the configuration of a pool '''
 
'''Example. Retrieve the configuration of a pool '''
Line 866: Line 917:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
200 OK
+
HTTP/1.1 200 OK
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 628
 
Content-Length: 628
Line 877: Line 928:
 
         "name": "web_pool",
 
         "name": "web_pool",
 
         "protocol": "HTTP",
 
         "protocol": "HTTP",
         "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
+
         "lb_method": "ROUND_ROBIN",
 +
        "subnet_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
 
         "members" : [
 
         "members" : [
 
                       "c57f581b-c834-408f-93fa-30543cf30618",
 
                       "c57f581b-c834-408f-93fa-30543cf30618",
Line 903: Line 955:
 
'''Normal Response Code(s)''': 202
 
'''Normal Response Code(s)''': 202
  
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+
'''Error Response Code(s)''': serviceFault (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.
+
When a pool is added, it is assigned a unique identifier which can be used for querying, changing or deleting it.   
  
 
If a user has an admin role, she can create pools for other tenant by specifying the tenant_id attribute in the request payload.
 
If a user has an admin role, she can create pools for other tenant by specifying the tenant_id attribute in the request payload.
 +
 +
The caller of this operation must specify at least the following attributes of the Pool:
 +
 +
* tenant_id: only required if the caller has an admin role and wants to create a pool for another tenant.
 +
* name: name of the pool
 +
* subnet_id: The network on which the members of the pool will be located. Only members that are on this network can be added to the pool.
 +
* lb_method: The algorithm used to distribute load between the members of the pool. The current specification supports "ROUND_ROBIN" and "LEAST_CONNECTIONS" as valid values for this attribute.
 +
* protocol: The protocol used by the pool members
 +
 +
The status of the Pool in the response can take one of the following values: ACTIVE, PENDING_CREATE or ERROR.
  
 
'''Example. Creating a pool '''
 
'''Example. Creating a pool '''
Line 922: Line 984:
  
 
{
 
{
   "pools" : [
+
   "pool" : {
        {
 
 
             "name": "web_pool",
 
             "name": "web_pool",
            "vip_id": "db902c0c-d5ff-4753-b465-668ad9656918",
 
 
             "protocol": "HTTP",
 
             "protocol": "HTTP",
             "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
+
             "lb_method" : "ROUND_ROBIN",
             "members" : [
+
             "subnet_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
                          "c57f581b-c834-408f-93fa-30543cf30618",
+
          }
                          "f2e37304-e3c1-4f96-9201-dd57a16adb75"
 
                        ]
 
        }
 
  ]
 
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
Line 942: Line 998:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
202 Accepted
+
HTTP/1.1 202 Accepted
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 275
 
Content-Length: 275
  
 
{
 
{
   "pools" : [
+
   "pool" : {
          {
 
 
             "id":"cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
             "id":"cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
             "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
             "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
            "vip_id": "db902c0c-d5ff-4753-b465-668ad9656918",
 
 
             "name": "web_pool",
 
             "name": "web_pool",
 
             "protocol": "HTTP",
 
             "protocol": "HTTP",
             "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
+
             "subnet_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
             "members" : [
+
             "lb_method": "ROUND_ROBIN",
                          "c57f581b-c834-408f-93fa-30543cf30618",
 
                          "f2e37304-e3c1-4f96-9201-dd57a16adb75"
 
                        ],
 
 
             "admin_state_up" : true,
 
             "admin_state_up" : true,
 
             "status" : "PENDING_CREATE"
 
             "status" : "PENDING_CREATE"
 
           }
 
           }
        ]
 
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
Line 978: Line 1,028:
 
'''Normal Response Code(s)''': 202
 
'''Normal Response Code(s)''': 202
  
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+
'''Error Response Code(s)''': serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
 +
 
 +
The caller of this operation may update the following attributes of the Pool:
 +
 
 +
* name
 +
* description
 +
* lb_method
 +
* admin_state_up
 +
 
 +
The status of the Pool in the response can take one of the following values: ACTIVE, PENDING_UPDATE or ERROR.
 +
 
 +
 
 +
<pre><nowiki>#!wiki caution
 +
Note
 +
 
 +
A Pool that is pending to be deleted (status="PENDING_DELETE") or has a "ERROR" status cannot be updated.
 +
</nowiki></pre>
  
This operation does not return a response body.
 
  
 
'''Example. Update the name of the pool'''
 
'''Example. Update the name of the pool'''
Line 1,006: Line 1,071:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
202 Accepted
+
HTTP/1.1 202 Accepted
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 269
 
Content-Length: 269
Line 1,017: Line 1,082:
 
             "name": "web_pool_1",
 
             "name": "web_pool_1",
 
             "protocol": "HTTP",
 
             "protocol": "HTTP",
             "network_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
+
             "subnet_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
 +
            "lb_method": "ROUND_ROBIN",
 
             "members" : [
 
             "members" : [
 
                           "c57f581b-c834-408f-93fa-30543cf30618",
 
                           "c57f581b-c834-408f-93fa-30543cf30618",
Line 1,033: Line 1,099:
 
| '''Verb'''  
 
| '''Verb'''  
 
| '''URI'''  
 
| '''URI'''  
|}
+
|-
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
 
| DELETE  
 
| DELETE  
 
| /pools/''pool_id''  
 
| /pools/''pool_id''  
 
|}
 
|}
  
'''Normal Response Code(s)''': 200, 202
+
'''Normal Response Code(s)''': 204
  
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+
'''Error Response Code(s)''': serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
 
This operation does not require a request body.
 
This operation does not require a request body.
Line 1,052: Line 1,116:
 
Note
 
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.
+
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 destroy the pool and its members.
 
</nowiki></pre>
 
</nowiki></pre>
 +
  
 
'''Example. Removing a pool'''
 
'''Example. Removing a pool'''
Line 1,070: Line 1,135:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
202 Accepted
+
HTTP/1.1 204 No Content
 
</nowiki></pre>
 
</nowiki></pre>
  
 
<pre><nowiki>#!wiki caution
 
Note
 
 
A pool that is pending to be deleted cannot be updated.
 
</nowiki></pre>
 
  
 
=== Pool Members ===
 
=== Pool Members ===
Line 1,098: Line 1,157:
 
'''Normal Response Code(s)''': 200
 
'''Normal Response Code(s)''': 200
  
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+
'''Error Response Code(s)''': serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
 
This operation does not require a request body.
 
This operation does not require a request body.
 +
 +
This operation returns a response body. On success, the returned response is a (potentially empty) list, each element in the list is a Member object can contain the following attributes:
 +
 +
* id
 +
* tenant_id
 +
* pool_id
 +
* address
 +
* protocol_port
 +
* weight
 +
* admin_state_up
 +
* status
  
 
'''Example. Listing all members '''
 
'''Example. Listing all members '''
Line 1,117: Line 1,187:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
200 OK
+
HTTP/1.1 200 OK
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 917
 
Content-Length: 917
Line 1,128: Line 1,198:
 
                 "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
                 "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
                 "address": "192.168.224.31",
 
                 "address": "192.168.224.31",
                 "port": 8080,
+
                 "protocol_port": 8080,
 
                 "weight" : 1,
 
                 "weight" : 1,
 
                 "admin_state_up" : true,
 
                 "admin_state_up" : true,
Line 1,138: Line 1,208:
 
                 "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
                 "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
                 "address": "192.168.224.32",
 
                 "address": "192.168.224.32",
                 "port" : 8081,
+
                 "protocol_port" : 8081,
 
                 "weight": 2,
 
                 "weight": 2,
 
                 "admin_state_up" : true,
 
                 "admin_state_up" : true,
Line 1,148: Line 1,218:
 
                 "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
                 "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
                 "address": "192.168.224.35"
 
                 "address": "192.168.224.35"
                 "port": 8080,
+
                 "protocol_port": 8080,
 
                 "weight" : 1,
 
                 "weight" : 1,
 
                 "admin_state_up" : false,
 
                 "admin_state_up" : false,
Line 1,158: Line 1,228:
 
                 "pool_id": "91c20e53-96cd-4476-8efc-627f398773bb",
 
                 "pool_id": "91c20e53-96cd-4476-8efc-627f398773bb",
 
                 "address": "192.168.137.61",
 
                 "address": "192.168.137.61",
                 "port": 8443,
+
                 "protocol_port": 8443,
 
                 "weight" : 1,
 
                 "weight" : 1,
 
                 "admin_state_up" : true,
 
                 "admin_state_up" : true,
Line 1,168: Line 1,238:
 
                 "pool_id": "91c20e53-96cd-4476-8efc-627f398773bb",
 
                 "pool_id": "91c20e53-96cd-4476-8efc-627f398773bb",
 
                 "address": "192.168.137.62",
 
                 "address": "192.168.137.62",
                 "port": 8443,
+
                 "protocol_port": 8443,
 
                 "weight" : 1,
 
                 "weight" : 1,
 
                 "admin_state_up" : true,
 
                 "admin_state_up" : true,
Line 1,178: Line 1,248:
 
                 "pool_id": "91c20e53-96cd-4476-8efc-627f398773bb",
 
                 "pool_id": "91c20e53-96cd-4476-8efc-627f398773bb",
 
                 "address": "192.168.137.63",
 
                 "address": "192.168.137.63",
                 "port": 8443,
+
                 "protocol_port": 8443,
 
                 "weight" : 1,
 
                 "weight" : 1,
 
                 "admin_state_up" : true,
 
                 "admin_state_up" : true,
Line 1,188: Line 1,258:
 
                 "pool_id": "41efe233-7591-43c5-9cf7-923964759f9e",
 
                 "pool_id": "41efe233-7591-43c5-9cf7-923964759f9e",
 
                 "address": "192.168.200.114",
 
                 "address": "192.168.200.114",
                 "port": 3306,
+
                 "protocol_port": 3306,
 
                 "weight" : 1,
 
                 "weight" : 1,
 
                 "admin_state_up" : true,
 
                 "admin_state_up" : true,
Line 1,198: Line 1,268:
 
                 "pool_id": "41efe233-7591-43c5-9cf7-923964759f9e",
 
                 "pool_id": "41efe233-7591-43c5-9cf7-923964759f9e",
 
                 "address": "192.168.200.132",
 
                 "address": "192.168.200.132",
                 "port": 3306,
+
                 "protocol_port": 3306,
 
                 "weight" : 1,
 
                 "weight" : 1,
 
                 "admin_state_up" : true,
 
                 "admin_state_up" : true,
Line 1,208: Line 1,278:
  
  
==== List all Members of a specific Pool ====
+
==== Retrieve a specific Member ====
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| '''Verb'''  
 
| '''Verb'''  
Line 1,214: Line 1,284:
 
|-
 
|-
 
| GET  
 
| GET  
| /v1.0/pools/''pool_id''/members
+
| /members/''member_id''  
 
|}
 
|}
  
List all members of a specific pool.
+
This operation retrieves the configuration of a member.
  
 
'''Normal Response Code(s)''': 200
 
'''Normal Response Code(s)''': 200
  
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+
'''Error Response Code(s)''': serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
 
This operation does not require a request body.
 
This operation does not require a request body.
  
'''Example. Listing all members of a pool '''
+
This operation returns a response body. On success, the returned response is a Member object which can contain the following attributes:
 +
 
 +
* id
 +
* tenant_id
 +
* pool_id
 +
* address
 +
* protocol_port
 +
* weight
 +
* admin_state_up
 +
* status
 +
 
 +
'''Example. Retrieve the configuration of a pool member '''
  
 
JSON Request:
 
JSON Request:
 +
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
GET /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764/members
+
GET /v1.0/members/c57f581b-c834-408f-93fa-30543cf30618
 
Host: lbaas-service.cloudX.com:8651
 
Host: lbaas-service.cloudX.com:8651
 
Accept: application/json
 
Accept: application/json
Line 1,236: Line 1,318:
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
JSON Response:
  
JSON Response:
 
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
200 OK
+
HTTP/1.1 200 OK
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 917
 
Content-Length: 917
  
 
{
 
{
   "members" : [
+
   "member" : {
              {
 
 
                 "id":"c57f581b-c834-408f-93fa-30543cf30618",
 
                 "id":"c57f581b-c834-408f-93fa-30543cf30618",
 
                 "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
                 "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
                 "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
                 "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
                 "address": "192.168.224.31",
 
                 "address": "192.168.224.31",
                 "port": 8080,
+
                 "protocol_port": 8080,
 
                 "weight" : 1,
 
                 "weight" : 1,
 
                 "admin_state_up" : true,
 
                 "admin_state_up" : true,
 
                 "status" : "ACTIVE"
 
                 "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>
 
</nowiki></pre>
  
  
==== Retrieve a specific Member ====
+
==== Create Pool Members ====
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| '''Verb'''  
 
| '''Verb'''  
 
| '''URI'''  
 
| '''URI'''  
| '''Description'''
 
 
|-
 
|-
| GET
+
| POST
| /members/''member_id''
+
| /v1.0/members  
 
|}
 
|}
  
This operation retrieves the configuration of a node.
+
'''Normal Response Code(s)''': 202
 +
 
 +
'''Error Response Code(s)''': serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
 +
 
 +
When a member is created, 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.
 +
 
 +
The caller of this operation must specify at least the following attributes of the Pool:
 +
 
 +
* tenant_id: only required if the caller has an admin role and wants to create a pool for another tenant.
 +
* address: the IP address of the pool member on the pool's network.
 +
* protocol_port: The port on which the pool member listens for requests or connections.
 +
* pool_id: The pool to which the member belongs.
 +
 
 +
The status of the Member in the response can take one of the following values: ACTIVE, PENDING_CREATE or ERROR.
 +
 
 +
 
 +
<pre><nowiki>#!wiki caution
 +
Note:
  
'''Normal Response Code(s)''': 200
+
When a member is added to a pool, it is enabled by default (admin_state_up = true) unless admin_state_up was set to false.
 +
</nowiki></pre>
  
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
 
  
This operation does not require a request body.
+
'''Example. Create a member '''
  
'''Example. Retrieve the configuration of a pool member '''
+
In this example, we add the first 2 members to one pool and the third member to a second pool.
  
 
JSON Request:
 
JSON Request:
 
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
GET /v1.0/members/c57f581b-c834-408f-93fa-30543cf30618
+
POST /v1.0/members
 
Host: lbaas-service.cloudX.com:8651
 
Host: lbaas-service.cloudX.com:8651
 
Accept: application/json
 
Accept: application/json
 +
Content-Type: application/json
 
X-Auth-Token:887665443383838
 
X-Auth-Token:887665443383838
 +
Content-Length: 826
 +
{
 +
      "member" : {
 +
                  "address": "192.168.224.31",
 +
                  "protocol_port": 8080,
 +
                  "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764"
 +
                }
 +
}
 
</nowiki></pre>
 
</nowiki></pre>
 +
  
 
JSON Response:
 
JSON Response:
Line 1,315: Line 1,400:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
200 OK
+
HTTP/1.1 202 Accepted
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 917
 
Content-Length: 917
  
 
{
 
{
   "member" : {
+
   "member" : {
 
                 "id":"c57f581b-c834-408f-93fa-30543cf30618",
 
                 "id":"c57f581b-c834-408f-93fa-30543cf30618",
 
                 "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
                 "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
                 "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
                 "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
                 "address": "192.168.224.31",
 
                 "address": "192.168.224.31",
                 "port": 8080,
+
                 "protocol_port": 8080,
 
                 "weight" : 1,
 
                 "weight" : 1,
 
                 "admin_state_up" : true,
 
                 "admin_state_up" : true,
                 "status" : "ACTIVE"
+
                 "status" : "PENDING_CREATE"
 +
 
 
               }
 
               }
 
}
 
}
Line 1,334: Line 1,420:
  
  
==== Create Pool Members ====
+
==== Update a Member ====
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| '''Verb'''
+
| Verb  
| '''URI'''
+
| URI  
| '''Description'''
 
 
|-
 
|-
| POST
+
| PUT
| /v1.0/members  
+
| /v1.0/members/''member_id''
| Add members to pools.
 
 
|}
 
|}
  
 
'''Normal Response Code(s)''': 202
 
'''Normal Response Code(s)''': 202
  
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+
'''Error Response Code(s)''': serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
 +
 
 +
The caller of this operation may update the following attributes of the Member:
  
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.
+
* pool_id
 +
* weight
 +
* admin_state_up
 +
 
 +
The status of the Member in the response can take one of the following values: ACTIVE, PENDING_UPDATE or ERROR.
  
  
 
<pre><nowiki>#!wiki caution
 
<pre><nowiki>#!wiki caution
Note:
+
Note
  
When a member is added to a load balancer, it is enabled by default (admin_state_up = true).
+
The member's address and protocol_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 members. The maximum number of members per pool is returned when querying the limits of the LBaaS service.
 
</nowiki></pre>
 
</nowiki></pre>
  
  
'''Example. Bulk create 3 members '''
 
  
In this example, we add the first 2 members to one pool and the third member to a second pool.
+
<pre><nowiki>#!wiki caution
 +
Note
 +
 
 +
A pool member that is pending deletion or has an ERROR status cannot be updated.
 +
</nowiki></pre>
  
JSON Request:
+
 
 +
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 member are gracefully drained or forcibly terminated. The member's status changes to INACTIVE once the configuration has been successfully applied.
 +
 
 +
'''Example. Disable a pool member '''
 +
 
 +
JSON Request:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
POST /v1.0/members
+
PUT /v1.0/members/c57f581b-c834-408f-93fa-30543cf30618
 
Host: lbaas-service.cloudX.com:8651
 
Host: lbaas-service.cloudX.com:8651
 
Accept: application/json
 
Accept: application/json
Line 1,374: Line 1,473:
  
 
{
 
{
   "members" : [
+
   "member" : {
              {
+
                 "admin_state_up": false
                "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>
 
</nowiki></pre>
 
  
 
JSON Response:
 
JSON Response:
Line 1,400: Line 1,483:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
200 OK
+
HTTP/1.1 202 ACCEPTED
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 917
 
Content-Length: 917
  
 
{
 
{
   "members" : [
+
   "member" : {
              {
 
 
                 "id":"c57f581b-c834-408f-93fa-30543cf30618",
 
                 "id":"c57f581b-c834-408f-93fa-30543cf30618",
 
                 "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
                 "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
 
                 "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
                 "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764",
 
                 "address": "192.168.224.31",
 
                 "address": "192.168.224.31",
                 "port": 8080,
+
                 "protocol_port": 8080,
 
                 "weight" : 1,
 
                 "weight" : 1,
                 "admin_state_up" : true,
+
                 "admin_state_up" : false,
                 "status" : "PENDING_CREATE"
+
                 "status" : "PENDING_UPDATE"
              },
+
            }
              {
 
                "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>
 
</nowiki></pre>
  
 
+
==== Remove a Member ====
==== Update a Member ====
 
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
| Verb  
+
| '''Verb'''
| URI  
+
| '''URI'''
| Description
 
 
|-
 
|-
| PUT
+
| DELETE
 
| /v1.0/members/''member_id''  
 
| /v1.0/members/''member_id''  
 +
| Removes a member from a pool.
 
|}
 
|}
  
'''Normal Response Code(s)''': 202
+
'''Normal Response Code(s)''': 204
 +
 
 +
'''Error Response Code(s)''': serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
'''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.
 
This operation does not return a response body.
  
 +
'''Example. remove a member from its pool '''
 +
 +
JSON Request:
  
<pre><nowiki>#!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
+
<pre><nowiki>#!highlight javascript numbers=disable
maximum number of nodes. The maximum number of nodes per pool is returned when querying the limits of the LBaaS service.
+
DELETE /v1.0/members/c57f581b-c834-408f-93fa-30543cf30618
 +
Host: lbaas-service.cloudX.com:8651
 +
Accept: application/json
 +
X-Auth-Token:887665443383838
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
JSON RESPONSE
  
  
<pre><nowiki>#!wiki caution
+
<pre><nowiki>#!highlight javascript numbers=disable
Note
+
HTTP/1.1 204 No Content
 
 
A pool member that is pending deletion or has an ERROR status cannot be updated.
 
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
=== Health Monitors ===
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Verb'''
 +
| '''URI'''
 +
|-
 +
| GET
 +
| /v1.0/health_monitors/
 +
|-
 +
| GET
 +
| /v1.0/health_monitors/''health_monitor_id''
 +
|-
 +
| PUT
 +
| /v1.0/health_monitors/''health_monitor_id''
 +
|-
 +
| DELETE
 +
| /v1.0/health_monitors/''health_monitor_id''
 +
| Remove the health monitor.
 +
|}
  
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.
+
'''Normal Response Code(s)''': 200, 202, 204
 
 
'''Example. Disable a pool member '''
 
 
 
JSON Request:
 
 
 
<pre><nowiki>#!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
 
  
{
+
'''Error Response Code(s)''': serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  "member" : {
 
                "admin_state_up": false
 
              }
 
}
 
</nowiki></pre>
 
  
JSON Response:
+
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.
  
<pre><nowiki>#!highlight javascript numbers=disable
+
'''Table 4.4. Health Monitor Types'''
202 ACCEPTED
+
{| border="1" cellpadding="2" cellspacing="0"
Content-Type: application/json
+
| '''Name'''
Content-Length: 917
+
|-
 +
| PING
 +
|-
 +
| TCP
 +
|-
 +
| HTTP
 +
|-
 +
| HTTPS
 +
|}
  
{
+
The required attributes to specify when creating a health monitor depend on the health monitor type.
  "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"
 
            }
 
}
 
</nowiki></pre>
 
  
==== Remove a Member ====
+
==== Create a Health Monitor ====
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| '''Verb'''  
 
| '''Verb'''  
 
| '''URI'''  
 
| '''URI'''  
| '''Description'''
 
 
|-
 
|-
| DELETE
+
| POST
| /v1.0/members/''member_id''
+
| /v1.0/health_monitors
| Removes a member from a pool.  
+
| Creates a Health Monitor.  
 
|}
 
|}
  
'''Normal Response Code(s)''': 200, 202
+
'''Normal Response Code(s)''': 202
 +
 
 +
'''Error Response Code(s)''': serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
 +
 
 +
===== Create a PING Health Monitor =====
 +
 
 +
The monitor pings the member to ensure that the member is alive.
  
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+
The PING monitor is the most basic type of health check. The following configurable properties must be specified:
  
This operation does not require a request body.
+
* '''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.
 +
* '''max_retries''': Number of permissible ping failures before changing the member's status to INACTIVE. Must be a number between 1 and 10.
  
This operation does not return a response body.
+
The status of the Health Monitor in the response can take one of the following values: ACTIVE, PENDING_CREATE or ERROR.
  
'''Example. remove a member from its pool '''
+
'''Example. Monitor PING'''
  
 
JSON Request:
 
JSON Request:
 
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
DELETE /v1.0/members/c57f581b-c834-408f-93fa-30543cf30618
+
POST /v1.0/health_monitors
 
Host: lbaas-service.cloudX.com:8651
 
Host: lbaas-service.cloudX.com:8651
 
Accept: application/json
 
Accept: application/json
 +
Content-Type: application/json
 
X-Auth-Token:887665443383838
 
X-Auth-Token:887665443383838
 +
Content-Length: 91
 +
 +
{
 +
    "health_monitor" :
 +
      {
 +
        "type" : "PING",
 +
        "delay" : 20,
 +
        "timeout": 10,
 +
        "max_retries": 3
 +
      }
 +
}
 
</nowiki></pre>
 
</nowiki></pre>
  
JSON RESPONSE
 
  
 +
JSON Response:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
202 Accepted
+
HTTP/1.1 202 Accepted
 +
Content-Type: application/json
 +
Content-Length: 114
 +
 
 +
{
 +
    "health_monitor" :
 +
      {
 +
        "id" : "f784c3a7-c4e8-44da-bf12-5ff417d27555",
 +
        "type" : "PING",
 +
        "delay" : 20,
 +
        "timeout": 10,
 +
        "max_retries": 3,
 +
        "admin_state_up": true,
 +
        "status": "PENDING_CREATE"
 +
      }
 +
}
 
</nowiki></pre>
 
</nowiki></pre>
  
=== Health Monitors ===
+
===== Create a TCP Health Monitor =====
{| border="1" cellpadding="2" cellspacing="0"
+
A TCP monitor tries to establish a TCP connection to the member to ensure that the member is healthy.
| '''Verb'''  
+
 
| '''URI'''  
+
The following configurable properties must be specified for a TCP monitor:
|-
+
 
| GET
+
* '''delay''': This is the minimum time in seconds between regular connections of the member.
| /v1.0/healthmonitors/
+
* '''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.
|-
+
* '''max_retries''': Number of permissible connection failures before changing the member's status to INACTIVE. Must be a number between 1 and 10.
| GET
+
 
| /v1.0/healthmonitors/''healthmonitor_id''  
+
The status of the Health Monitor in the response can take one of the following values: ACTIVE, PENDING_CREATE or ERROR.
|-
+
 
| PUT
+
'''Example. Create a TCP Monitor'''
| /v1.0/healthmonitors/''healthmonitor_id''  
+
 
| Update the settings for a health monitor.  
+
JSON Request:
|-
 
| DELETE
 
| /v1.0/healthmonitors/''healthmonitor_id''  
 
| Remove the health monitor.
 
|}
 
  
'''Normal Response Code(s)''': 200, 202
+
<pre><nowiki>#!highlight javascript numbers=disable
 +
POST /v1.0/health_monitors
 +
Host: lbaas-service.cloudX.com:8651
 +
Accept: application/json
 +
Content-Type: application/json
 +
X-Auth-Token:887665443383838
 +
Content-Length: 91
  
'''Error Response Code(s)''': loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
+
{
 +
    "health_monitor" :
 +
      {
 +
        "type" : "TCP",
 +
        "delay" : 20,
 +
        "timeout": 10,
 +
        "max_retries": 3
 +
      }
 +
}
 +
</nowiki></pre>
  
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.
+
JSON Response:
  
'''Table 4.4. Health Monitor Types'''
 
{| border="1" cellpadding="2" cellspacing="0"
 
| '''Name'''
 
|-
 
| PING
 
|-
 
| TCP
 
|-
 
| HTTP
 
|-
 
| HTTPS
 
|}
 
  
The required attributes to specify when creating a health monitor depend on the health monitor type.
+
<pre><nowiki>#!highlight javascript numbers=disable
 +
HTTP/1.1 202 Accepted
 +
Content-Type: application/json
 +
Content-Length: 114
 +
 
 +
{
 +
    "health_monitor" :
 +
      {
 +
        "id" : "e5069610-744b-42a7-8bd8-ceac1a229cd4",
 +
        "type" : "TCP",
 +
        "delay" : 20,
 +
        "timeout": 10,
 +
        "max_retries": 3,
 +
        "admin_state_up": true,
 +
        "status": "PENDING_CREATE"
  
==== Create a PING Health Monitor ====
+
      }
The monitor pings the member to ensure that the member is alive.
+
}
 +
</nowiki></pre>
  
The PING monitor is the most basic type of health check. The following configurable properties can be specified
+
===== 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 member. 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.
  
* '''delay''': This is the minimum time in seconds between regular pings of the member.
+
* '''http_method''': The HTTP method used for requests by the monitor. If this attribute is not specified, it defaults to "GET".
* '''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.
+
* '''url_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). If this is not specified it defaults to "/".
* '''attemptsBeforeDeactivation''': Number of permissible ping failures before changing the member's status to INACTIVE. Must be a number between 1 and 10.
+
* '''expected_codes''': These are the list of HTTP status codes expected in response from the member to declare it healthy. This
 +
  attribute can contain one value, or a list of values separated by comma, or a range of values (e.g. "200-299"). If this attribute
 +
  is not specified, it defaults to "200".
 +
 
 +
The status of the Health Monitor in the response can take one of the following values: ACTIVE, PENDING_CREATE or ERROR.
  
'''Example. Monitor PING'''
+
'''Example. Create a HTTP Monitor '''
  
 
JSON Request:
 
JSON Request:
  
<pre><nowiki>#!highlight xml numbers=disable
+
<pre><nowiki>#!highlight javascript numbers=disable
POST /v1.0/healthmonitors
+
POST /v1.0/health_monitors
 
Host: lbaas-service.cloudX.com:8651
 
Host: lbaas-service.cloudX.com:8651
 
Accept: application/json
 
Accept: application/json
Line 1,620: Line 1,733:
  
 
{
 
{
     "healthmonitor" :
+
     "health_monitor" :
 
       {
 
       {
         "type" : "PING",
+
         "type" : "HTTP",
 
         "delay" : 20,
 
         "delay" : 20,
 
         "timeout": 10,
 
         "timeout": 10,
         "attemptsBeforeDeactivation": 3
+
         "max_retries": 3,
 +
        "http_method" : "HEAD",
 +
        "path" : "/check",
 +
        "expected_codes" : "200-299"
 
       }
 
       }
 
}
 
}
Line 1,633: Line 1,749:
 
JSON Response:
 
JSON Response:
  
<pre><nowiki>#!highlight xml numbers=disable
+
<pre><nowiki>#!highlight javascript numbers=disable
202 Accepted
+
HTTP/1.1 202 Accepted
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 114
 
Content-Length: 114
  
 
{
 
{
     "healthmonitor" :
+
     "health_monitor" :
 
       {
 
       {
         "id" : "f784c3a7-c4e8-44da-bf12-5ff417d27555",
+
         "id" : "f3eeab00-8367-4524-b662-55e64d4cacb5",
         "type" : "PING",
+
         "type" : "HTTP",
 
         "delay" : 20,
 
         "delay" : 20,
 
         "timeout": 10,
 
         "timeout": 10,
         "attemptsBeforeDeactivation": 3,
+
         "max_retries": 3,
 +
        "http_method" : "GET",
 +
        "url_path" : "/",
 +
        "expected_codes" : "200,202",
 
         "admin_state_up": true,
 
         "admin_state_up": true,
 
         "status": "PENDING_CREATE"
 
         "status": "PENDING_CREATE"
Line 1,652: Line 1,771:
 
</nowiki></pre>
 
</nowiki></pre>
  
==== 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:
+
==== Update a Health Monitor ====
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Verb'''
 +
| '''URI'''
 +
|-
 +
| PUT
 +
| /v1.0/health_monitors/''health_monitor_id''
 +
| Updates a Health Monitor.
 +
|}
  
* '''delay''': This is the minimum time in seconds between regular connections of the member.
+
All the attributes of a Health Monitor can be updated apart from the type attribute which is immutable.  
* '''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. Create a TCP Monitor'''
+
The status of the Health Monitor in the response can take one of the following values: ACTIVE, PENDING_UPDATE or ERROR.
  
JSON Request:
 
  
<pre><nowiki>#!highlight xml numbers=disable
+
<pre><nowiki>#!wiki caution
POST /v1.0/healthmonitors
+
Note
Host: lbaas-service.cloudX.com:8651
+
 
 +
A Health Monitor that is pending deletion or has an ERROR status cannot be updated.
 +
</nowiki></pre>
 +
 
 +
 
 +
The following example illustrate how to update a Health Monitor.
 +
 
 +
'''Example. Update a TCP Monitor'''
 +
 
 +
JSON Request:
 +
 
 +
<pre><nowiki>#!highlight javascript numbers=disable
 +
PUT /v1.0/health_monitors/e5069610-744b-42a7-8bd8-ceac1a229cd4
 +
Host: lbaas-service.cloudX.com:8651
 
Accept: application/json
 
Accept: application/json
 
Content-Type: application/json
 
Content-Type: application/json
 
X-Auth-Token:887665443383838
 
X-Auth-Token:887665443383838
Content-Length: 91
+
Content-Length: 41
  
 
{
 
{
     "healthmonitor" :
+
     "health_monitor" :
 
       {
 
       {
        "type" : "TCP",
+
         "delay" : 30,
         "delay" : 20,
+
         "max_retries": 2
        "timeout": 10,
 
         "attemptsBeforeDeactivation": 3
 
 
       }
 
       }
 
}
 
}
Line 1,688: Line 1,821:
  
  
<pre><nowiki>#!highlight xml numbers=disable
+
<pre><nowiki>#!highlight javascript numbers=disable
202 Accepted
+
HTTP/1.1 202 Accepted
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 114
 
Content-Length: 114
  
 
{
 
{
     "healthmonitor" :
+
     "health_monitor" :
 
       {
 
       {
 
         "id" : "e5069610-744b-42a7-8bd8-ceac1a229cd4",
 
         "id" : "e5069610-744b-42a7-8bd8-ceac1a229cd4",
 
         "type" : "TCP",
 
         "type" : "TCP",
         "delay" : 20,
+
         "delay" : 30,
 
         "timeout": 10,
 
         "timeout": 10,
         "attemptsBeforeDeactivation": 3,
+
         "max_retries": 2,
 
         "admin_state_up": true,
 
         "admin_state_up": true,
         "status": "PENDING_CREATE"
+
         "status": "PENDING_UPDATE"
 
 
 
       }
 
       }
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
  
==== 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.
+
==== Delete a Health Monitor ====
  
'''Example. Create a HTTP Monitor '''
+
When a health monitor is deleted, it is automatically dissociated from all the pools where it is used.
 +
 
 +
'''Example. Delete a TCP Monitor'''
  
 
JSON Request:
 
JSON Request:
  
<pre><nowiki>#!highlight xml numbers=disable
+
<pre><nowiki>#!highlight javascript numbers=disable
POST /v1.0/healthmonitors
+
DELETE /v1.0/health_monitors/e5069610-744b-42a7-8bd8-ceac1a229cd4
 
Host: lbaas-service.cloudX.com:8651
 
Host: lbaas-service.cloudX.com:8651
 
Accept: application/json
 
Accept: application/json
Content-Type: application/json
 
 
X-Auth-Token:887665443383838
 
X-Auth-Token:887665443383838
Content-Length: 91
 
 
{
 
    "healthmonitor" :
 
      {
 
        "type" : "HTTP",
 
        "delay" : 20,
 
        "timeout": 10,
 
        "attemptsBeforeDeactivation": 3,
 
        "path" : "/check",
 
        "error_codes" : "200-299"
 
      }
 
}
 
 
</nowiki></pre>
 
</nowiki></pre>
  
Line 1,741: Line 1,859:
 
JSON Response:
 
JSON Response:
  
<pre><nowiki>#!highlight xml numbers=disable
 
202 Accepted
 
Content-Type: application/json
 
Content-Length: 114
 
  
{
+
<pre><nowiki>#!highlight javascript numbers=disable
    "healthmonitor" :
+
HTTP/1.1 204 No Content
      {
 
        "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"
 
      }
 
}
 
 
</nowiki></pre>
 
</nowiki></pre>
  
  
==== Update a Health Monitor ====
+
==== List all Health Monitors ====
  
You can update all the attribute of a health monitor but its type. The following example illustrate how to update a Health Monitor.
+
This operation returns a response body. On success, the returned response is a (potentially empty) list, each element in the list is a Health Monitor object that can contain the following attributes:
  
'''Example. Update a TCP Monitor'''
+
* id
 +
* type
 +
* delay
 +
* timeout
 +
* max_retries
 +
* admin_state_up
 +
* status
 +
 
 +
In addition, if the type of the Health Monitor is HTTP or HTTPS, the following attributes are also present:
 +
 
 +
* http_method
 +
* url_path
 +
* expected_codes
 +
 
 +
'''Example. List all health monitors accessible to this tenant '''
  
 
JSON Request:
 
JSON Request:
  
<pre><nowiki>#!highlight xml numbers=disable
+
<pre><nowiki>#!highlight javascript numbers=disable
PUT /v1.0/healthmonitors/e5069610-744b-42a7-8bd8-ceac1a229cd4
+
GET /v1.0/health_monitors
 
Host: lbaas-service.cloudX.com:8651
 
Host: lbaas-service.cloudX.com:8651
 
Accept: application/json
 
Accept: application/json
Content-Type: application/json
 
 
X-Auth-Token:887665443383838
 
X-Auth-Token:887665443383838
Content-Length: 41
 
 
{
 
    "healthmonitor" :
 
      {
 
        "delay" : 30,
 
        "attemptsBeforeDeativation": 2
 
      }
 
}
 
 
</nowiki></pre>
 
</nowiki></pre>
  
Line 1,791: Line 1,897:
 
JSON Response:
 
JSON Response:
  
 
+
<pre><nowiki>#!highlight javascript numbers=disable
<pre><nowiki>#!highlight xml numbers=disable
+
HTTP/1.1 200 OK
202 Accepted
 
 
Content-Type: application/json
 
Content-Type: application/json
 
Content-Length: 114
 
Content-Length: 114
  
 
{
 
{
    "healthmonitor" :
+
  "health_monitors" : [
      {
+
                      {
        "id" : "e5069610-744b-42a7-8bd8-ceac1a229cd4",
+
                        "id" : "e5069610-744b-42a7-8bd8-ceac1a229cd4",
        "type" : "TCP",
+
                        "type" : "TCP",
        "delay" : 30,
+
                        "delay" : 30,
        "timeout": 10,
+
                        "timeout": 10,
        "attemptsBeforeDeactivation": 2,
+
                        "max_retries": 2,
        "admin_state_up": true,
+
                        "admin_state_up": true,
        "status": "PENDING_UPDATE"
+
                        "status": "ACTIVE"
      }
+
                        },
 +
                        {
 +
                          "id" : "f3eeab00-8367-4524-b662-55e64d4cacb5",
 +
                          "type" : "HTTP",
 +
                          "delay" : 20,
 +
                          "timeout": 10,
 +
                          "max_retries": 3,
 +
                          "http_method" : "GET",
 +
                          "url_path" : "/check",
 +
                          "expected_codes" : "200,202",
 +
                          "admin_state_up": true,
 +
                          "status": "PENDING_CREATE"
 +
                        }
 +
                ]
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
  
  
 +
==== Associate Health Monitors with a Pool ====
 +
You can associate a health monitor with an existing pool. Once associated, the health monitor 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 it unhealthy.
  
<pre><nowiki>#!wiki caution
+
The response will return the current list of all health monitors associated with the pool.
Note
 
  
A Health Monitor that is pending deletion or has an ERROR status cannot be updated.
+
'''Example. Add a health monitor to the monitors for a pool'''
</nowiki></pre>
 
 
 
 
 
==== Delete a Health Monitor ====
 
 
 
When a health monitor is deleted, it is automatically dissociated from all the pools where it is used.
 
 
 
'''Example. Update a TCP Monitor'''
 
  
 
JSON Request:
 
JSON Request:
  
<pre><nowiki>#!highlight xml numbers=disable
+
<pre><nowiki>#!highlight javascript numbers=disable
DELETE /v1.0/healthmonitors/e5069610-744b-42a7-8bd8-ceac1a229cd4
+
POST /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764/health_monitors
 
Host: lbaas-service.cloudX.com:8651
 
Host: lbaas-service.cloudX.com:8651
 
Accept: application/json
 
Accept: application/json
 
X-Auth-Token:887665443383838
 
X-Auth-Token:887665443383838
 +
 +
{
 +
    "id" : "f3eeab00-8367-4524-b662-55e64d4cacb5"
 +
}
 
</nowiki></pre>
 
</nowiki></pre>
  
Line 1,838: Line 1,953:
 
JSON Response:
 
JSON Response:
  
 +
<pre><nowiki>#!highlight javascript numbers=disable
 +
HTTP/1.1 202 Accepted
 +
Content-Type: application/json
 +
Content-Length: 114
  
<pre><nowiki>#!highlight xml numbers=disable
+
{
202 Accepted
+
    "id" : "f784c3a7-c4e8-44da-bf12-5ff417d27555",
 +
}
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
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.
  
==== List all Health Monitors associated with a Pool ====
+
==== Dissociate Health Monitors from a Pool ====
'''Example. List health monitors for 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'''
  
 
JSON Request:
 
JSON Request:
  
 
<pre><nowiki>#!highlight javascript numbers=disable
 
<pre><nowiki>#!highlight javascript numbers=disable
GET /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764/healthmonitors
+
DELETE /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764/health_monitors/f3eeab00-8367-4524-b662-55e64d4cacb5
 
Host: lbaas-service.cloudX.com:8651
 
Host: lbaas-service.cloudX.com:8651
 
Accept: application/json
 
Accept: application/json
Line 1,859: Line 1,984:
 
JSON Response:
 
JSON Response:
  
<pre><nowiki>#!highlight xml numbers=disable
+
<pre><nowiki>#!highlight javascript numbers=disable
200 OK
+
HTTP/1.1 204 No Content
Content-Type: application/json
 
Content-Length: 114
 
 
 
{
 
    "healthmonitors" : [
 
                        "f784c3a7-c4e8-44da-bf12-5ff417d27555",
 
                        "e5069610-744b-42a7-8bd8-ceac1a229cd4"
 
                      ]
 
}
 
 
</nowiki></pre>
 
</nowiki></pre>
  
==== Associate Health Monitors with a Pool ====
+
=== Statistics ===
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.
+
==== Retrieve Traffic Statistics for a Pool ====
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Name'''
 +
| '''URI'''
 +
|-
 +
| GET
 +
| /v1.0/pools/''pool_id''/stats
 +
|}
  
The response will return the current list of all health monitors associated with the pool.
+
'''Normal Response Code(s):''' 200
  
'''Example. Add a health monitor to the monitors for a pool'''
+
'''Error Response Code(s)''': serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
  
JSON Request:
+
This operation retrieves the aggregated traffic statistics for all members of a pool. The returned statistics are not necessarily real-time and might be collected in the background on a periodic basis and the cached data returned to the user during this call.
  
<pre><nowiki>#!highlight xml numbers=disable
+
This operation does not require a request body.
POST /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764/healthmonitors
 
Host: lbaas-service.cloudX.com:8651
 
Accept: application/json
 
X-Auth-Token:887665443383838
 
  
{
+
The pool stats reports provide a set of stats counters. This list will contain at least the following counters:
    "healthmonitors" : [
 
                        "f3eeab00-8367-4524-b662-55e64d4cacb5"
 
                      ]
 
}
 
</nowiki></pre>
 
  
 +
* ''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.
  
JSON Response:
+
'''Example. Retrieve the stats for a pool'''
 
 
<pre><nowiki>#!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"
 
                      ]
 
}
 
</nowiki></pre>
 
 
 
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'''
 
  
 
JSON Request:
 
JSON Request:
  
<pre><nowiki>#!highlight xml numbers=disable
+
<pre><nowiki>#!highlight javascript numbers=disable
DELETE /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764/healthmonitors/f3eeab00-8367-4524-b662-55e64d4cacb5
+
GET /v1.0/pools/cfc6589d-f949-4c66-99d2-c2da56ef3764/stats
 
Host: lbaas-service.cloudX.com:8651
 
Host: lbaas-service.cloudX.com:8651
 
Accept: application/json
 
Accept: application/json
Line 1,932: Line 2,027:
 
JSON Response:
 
JSON Response:
  
<pre><nowiki>#!highlight xml numbers=disable
+
<pre><nowiki>#!highlight javascript numbers=disable
202 Accepted
+
HTTP/1.1 200 OK
</nowiki></pre>
+
Content-Type: application/json
 +
Content-Length: 114
  
=== Statistics ===
+
{
==== Retrieve Traffic Statistics for a Pool ====
+
     "stats" : {
{| border="1" cellpadding="2" cellspacing="0"
+
                         "bytes_in" : 36839202,
| '''Name'''
+
                         "bytes_out" : 673193022,
| '''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 retrieves the aggregated traffic statistics for all members of a pool.
 
 
 
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. Retrieve the stats for a pool'''
 
 
 
JSON Request:
 
 
 
<pre><nowiki>#!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
 
</nowiki></pre>
 
 
 
 
 
JSON Response:
 
 
 
<pre><nowiki>#!highlight xml numbers=disable
 
200 OK
 
Content-Type: application/json
 
Content-Length: 114
 
 
 
{
 
     "stats" : {
 
                         "bytes_in" : 36839202,
 
                         "bytes_out" : 673193022,
 
 
                         "active_connections" : 39,
 
                         "active_connections" : 39,
 
                         "total_connections" : 682
 
                         "total_connections" : 682
 
               }
 
               }
}
 
</nowiki></pre>
 
 
 
=== Protocols ===
 
==== List Supported Load Balancing Protocols ====
 
{| border="1" cellpadding="2" cellspacing="0"
 
| '''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 '''
 
 
JSON Request:
 
 
<pre><nowiki>#!highlight javascript numbers=disable
 
GET /v1.0/protocols.json
 
Host: lbaas-service.cloudX.com:8651
 
X-Auth-Token:887665443383838
 
</nowiki></pre>
 
 
 
JSON Response:
 
 
<pre><nowiki>#!highlight javascript numbers=disable
 
{
 
"protocols": [
 
              {
 
                "name": "TCP",
 
              },
 
              {
 
                "name": "HTTP",
 
              },
 
              {
 
                "name": "HTTPS",
 
              }
 
              ]
 
}
 
</nowiki></pre>
 
 
=== 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'''
 
{| border="1" cellpadding="2" cellspacing="0"
 
| '''Name'''
 
|-
 
| LEAST_CONNECTIONS
 
|-
 
| ROUND_ROBIN
 
|}
 
 
==== Listing Supported Load Balancing Methods ====
 
{| border="1" cellpadding="2" cellspacing="0"
 
| '''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. List Load Balancing Algorithms Response'''
 
 
JSON Request:
 
 
<pre><nowiki>#!highlight javascript numbers=disable
 
GET /v1.0/lb_methods
 
Accept: application/json
 
Host: lbaas-service.cloudX.com:8651
 
X-Auth-Token:887665443383838
 
</nowiki></pre>
 
 
 
 
<pre><nowiki>#!highlight javascript numbers=disable
 
200 OK
 
Content-type: application/json
 
Content-length: 362
 
 
{
 
  "lb_methods": [
 
                  {
 
                    "name": "ROUND_ROBIN"
 
                  },
 
                  {
 
                    "name": "LEAST_CONNECTIONS"
 
                  }
 
                ]
 
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>

Latest revision as of 15:54, 21 June 2013

OpenStack LBaaS API 1.0 (draft)

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 service, the OpenStack Quantum service, and the integration between the two. You should also know how to obtain authentication tokens from the OpenStack KeyStone service.

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
Nov, 5 2012
Nov, 19 2012
Dec, 6 2012
Dec, 10 2012
Dec, 21 2012
Dec, 24 2012
Mar, 11 2013

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:

  • Load balancing client traffic coming from one network to application services (e.g. VMs) present on the same or a different network.
  • Supporting load balancing for several protocols
  • Supporting session persistence
  • Monitoring the health of the application services
  • Protecting the application services against Denial of Service (DoS) attacks
  • Collecting traffic statistics on the incoming client traffic.

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


#!wiki caution
Note

In the tradional load balancing vernacular, the term 'VIP' is used to denote the IP address to which clients connect. As it is defined in this document, this IP address is only one attribute of the VIP object.

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 load balancing 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.

When a pool has several monitors associated with it, each member of the pool is monitored by all these monitors. If any monitor declares the member as unhealthy, then the member status is changed to INACTIVE and the member won't participate in its pool's load balancing. In other words, ALL monitors must declare the member to be healthy for it to stay ACTIVE.

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 load balancing function 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 load balancing function 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 each member of a pool, you can set a connection limit on the VIP or on the pool, 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 of the pool 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.

Users with non-admin roles, can only perform CRUD (Create, Retrieve, Update and Delete) operations on the resources they own. Users with admin roles (as configured in the Keystone service) can operate on other tenant resources by specifying a "tenant_id" attribute in the resource's representation when creating or updating, and by specifying a "tenant_id" query string when retrieving or deleting.

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 should accept JSON serialized responses by specifying the Accept header with the MIME type value "application/json" or adding ".json" extension to the resource name. The default response format is "application/json" if the client omits to specify an Accept header or append the ".json" extension in the URL path.

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 VIPs 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, the LBaaS service returns all attributes for any show or list call. The LBaaS API v1.0 has a mechanism to limit the set of attributes returned. 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,subnet_id,address and protocol_port for each vip:


#!highlight javascript numbers=disable
GET /v1.0/vips.json?fields=id&fields=name&fields=subnet_id&fields=address&fields=protocol_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 load balancing function. 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 POST request on the members resource to add a new 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 pool Member or the Health Monitor to determine whether the LBaaS plugin has successfully completed the configuration of the resource.

Table 4.1. Status Values

Name
ACTIVE
PENDING_CREATE
PENDING_UPDATE
PENDING_DELETE
INACTIVE
ERROR

When status is set to "ERROR" in an object returned by the LBaaS service, then the returned object might also contain an extra attribute called "error_details" which provides textual explanation on the error, its cause, and possibly a way for the user to remedy the situation.

Update Operations

The update operations of resources use the HTTP PUT method with "patch" semantics (as opposed to "replace" semantics), meaning that the attributes submitted in the PUT request are changed on the resource while the attributes that haven't been submitted in the update operation keep their previous values in the resource.

Also, note that not all attributes of a resource can be updated. This is described in the "update" operation on each resource.

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
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
413 Over limit
422 Immutable
500 Internal server error
503 Service unavailable

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
HTTP/1.1 409 Conflict
Content-type: application/json
Content-lentgh:78

{
   "errorcode": 409,
   "errormessage": "pool 'cfc6589d-f949-4c66-99d2-c2da56ef3764' is already used by VIP 'db902c0c-d5ff-4753-b465-668ad9656918' "
}


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 following APIs to manage vip 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
GET /v1.0/vips/

Normal Response Code(s): 200

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
  • subnet_id
  • address
  • port_id
  • protocol_port
  • protocol
  • pool_id
  • session_persistence
  • connection_limit
  • admin_state_up
  • status

Example . List all 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
HTTP/1.1 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",
           "subnet_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
           "address" : "10.30.176.47",
           "port_id" : "cd1f7a47-4fa6-449c-9ee7-632838aedfea",
           "protocol": "HTTP",
           "protocol_port": 80,
           "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",
           "subnet_id": "9cedb85d-0759-4898-8a4b-fa5a5ea10086",
           "address" : "10.30.176.48",
           "port_id" : "cd1f7a47-4fa6-449c-9ee7-632838aedfea",
           "protocol": "TCP",
           "protocol_port": 3306,
           "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
GET /v1.0/vips/vip_id

Normal Response Code(s): 200

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

This operation returns a VIP object identified by vip_id. If the user is not an admin, and the VIP object doesn't belong to her tenant account, she would receive a 403 (Forbidden) error.

This operation does not require a request body.

This operation returns a response body. On success, the returned element is a VIP that can contain the following attributes:

  • id
  • tenant_id
  • name
  • description
  • subnet_id
  • address
  • port_id
  • protocol_port
  • 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
HTTP/1.1 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",
           "subnet_id": "9cedb85d-0759-4898-8a4b-fa5a5ea10086",
           "address" : "10.30.176.47",
           "port_id" : "cd1f7a47-4fa6-449c-9ee7-632838aedfea",
           "protocol": "TCP",
           "protocol_port": 3306,
           "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
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 required if the caller has an admin role and wants to create a VIP for another tenant.
  • subnet_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.
  • protocol_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:

  • service_type: The service type used to create the VIP will be the default service type configured in the LBaaS Service.
  • admin_state_up: The default value for this attribute is true.

Also note that the pool_id should refer to a pool that is not already associated with another vip. If the pool is already used by another vip, then this creation operation will fail with a 409 Conflict error.

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.

Users with an admin role can create VIPs on behalf of other tenants by specifying a tenant_id attribute different than their own.

Example . Create a 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: 463

{
  "vip": {
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
           "name": "web_vip",
           "subnet_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
           "protocol": "HTTPS",
           "protocol_port": 443,
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764",
           "session_persistence" : {"type":"APP_COOKIE", "cookie_name":"jsessionid"}
         }
}


JSON Response:

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

{
  "vip": {
           "id": "02b1fef7-16f5-4917-bf19-c40a9af805ed",
           "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
           "name": "web_vip",
           "subnet_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
           "address" : "10.30.176.47",
           "port_id" : "cd1f7a47-4fa6-449c-9ee7-632838aedfea",
           "protocol": "HTTPS",
           "protocol_port": 443,
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764",
           "session_persistence" : {"type":"APP_COOKIE", "cookie_name":"jsessionid"},
           "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 VIP's network.

Once an address is allocated to the user, the user can create other VIP objects using the same address but with different protocol 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

{
  "vip": {
           "name": "ssl_vip",
           "subnet_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
           "address" : "10.30.176.47",
           "protocol": "HTTPS",
           "protocol_port": 443,
           "pool_id" : "91c20e53-96cd-4476-8efc-627f398773bb"
         }
}


JSON Response:


#!highlight javascript numbers=disable
HTTP/1.1 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",
           "subnet_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
           "address" : "10.30.176.47",
           "port_id" : "cd1f7a47-4fa6-449c-9ee7-632838aedfea",
           "protocol": "HTTPS",
           "protocol_port": 443,
           "pool_id" : "91c20e53-96cd-4476-8efc-627f398773bb",
           "session_persistence" : {"type":"APP_COOKIE", "cookie_name":"jsessionid"},
           "admin_state_up": true,
           "status": "PENDING_CREATE"
         }
}


Update a VIP

Verb URI
PUT /1.0/vips/vip_id

Normal Response Code(s): 202

Error Response Code(s): serviceFault (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 object (using a GET operation) to wait for the changes to be applied.

The update operation allows the caller to change one or more of the following VIP attributes:

  • name
  • description
  • pool_id
  • 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 VIP's ID, status, subnet_id, address, protocol_port and protocol are immutable attributes and cannot be modified once a VIP is created. Supplying an unsupported attribute will result in a 422 (Immutable) fault.


#!wiki caution
Note

A VIP that is pending deletion or has an ERROR status cannot be updated.


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",
           "session_persistence": { "type": "HTTP_COOKIE" }
         }
}


JSON Response:

#!highlight javascript numbers=disable
HTTP/1.1 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",
           "subnet_id": "96a4386a-f8c3-42ed-afce-d7954eee77b3",
           "address" : "10.30.176.47",
           "port_id" : "cd1f7a47-4fa6-449c-9ee7-632838aedfea",
           "protocol": "HTTPS",
           "protocol_port": 443,
           "pool_id" : "cfc6589d-f949-4c66-99d2-c2da56ef3764",
           "session_persistence": { "type": "HTTP_COOKIE" },
           "admin_state_up": true,
           "status": "PENDING_UPDATE"
         }
}


Remove a VIP

Verb URI
DELETE /v1.0/vips/vip_id Remove a VIP from the account.

Normal Response Code(s): 204

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

This operation removes the specified VIP and its associated configuration from the tenant 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
HTTP/1.1 204 No Content


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 protocol and health monitors are configured on the pool, and all members of the same pool, will be monitored using these health monitors.


#!wiki caution
Note

Each VIP object can be associated with one pool. Also a pool cannot be used by more than one VIP object. It needs to be first removed from one VIP in order to be added to another.


List all Pools

Verb URI
GET /v1.0/pools

List all pools of a tenant.

Normal Response Code(s): 200

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

This operation does not require a request body.

This operation returns a response body. On success, the returned element is a (potentially empty) list, each element is a Pool object which can contain the following attributes:

  • id
  • tenant_id
  • vip_id
  • name
  • description
  • subnet_id
  • protocol
  • lb_method
  • members
  • health_monitors
  • admin_state_up
  • status

Example. List pools Request:

JSON Request:

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

Example. List pools Response: JSON


#!highlight javascript numbers=disable
HTTP/1.1 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",
                "lb_method": "ROUND_ROBIN",
                "subnet_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",
                "subnet_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
                "lb_method" : "LEAST_CONNECTIONS",
                "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",
                "subnet_id" : "ddc3ab81-1dac-4be3-a340-c7b7b5d89beb",
                "lb_method": "ROUND_ROBIN",
                "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
GET /v1.0/pools/pool_id

This operation retrieves the configuration of a pool.

Normal Response Code(s): 200

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

This operation does not require a request body.

This operation returns a response body. On success, the returned Pool object can contain the following attributes:

  • id
  • tenant_id
  • vip_id
  • name
  • description
  • subnet_id
  • protocol
  • lb_method
  • members
  • health_monitors
  • admin_state_up
  • status

Note that only attributes that have a value are returned in the response. For example if the pool is not associated with a vip, the vip_id attribute is not returned in the response payload.

Example. 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
HTTP/1.1 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",
         "lb_method": "ROUND_ROBIN",
         "subnet_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): serviceFault (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.

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

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

  • tenant_id: only required if the caller has an admin role and wants to create a pool for another tenant.
  • name: name of the pool
  • subnet_id: The network on which the members of the pool will be located. Only members that are on this network can be added to the pool.
  • lb_method: The algorithm used to distribute load between the members of the pool. The current specification supports "ROUND_ROBIN" and "LEAST_CONNECTIONS" as valid values for this attribute.
  • protocol: The protocol used by the pool members

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

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

{
  "pool" : {
            "name": "web_pool",
            "protocol": "HTTP",
            "lb_method" : "ROUND_ROBIN",
            "subnet_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
           }
}


JSON Response


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

{
  "pool" : {
            "id":"cfc6589d-f949-4c66-99d2-c2da56ef3764",
            "tenant_id": "310df60f-2a10-4ee5-9554-98393092194c",
            "name": "web_pool",
            "protocol": "HTTP",
            "subnet_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
            "lb_method": "ROUND_ROBIN",
            "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): serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

The caller of this operation may update the following attributes of the Pool:

  • name
  • description
  • lb_method
  • admin_state_up

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


#!wiki caution
Note

A Pool that is pending to be deleted (status="PENDING_DELETE") or has a "ERROR" status cannot be updated.


Example. Update the 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
HTTP/1.1 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",
            "subnet_id" : "e2a7a228-8fd1-4aa8-8d0c-4023a68e1c92",
            "lb_method": "ROUND_ROBIN",
            "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): 204

Error Response Code(s): serviceFault (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 destroy the pool and its members.


Example. 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
HTTP/1.1 204 No Content


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): serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

This operation does not require a request body.

This operation returns a response body. On success, the returned response is a (potentially empty) list, each element in the list is a Member object can contain the following attributes:

  • id
  • tenant_id
  • pool_id
  • address
  • protocol_port
  • weight
  • admin_state_up
  • status

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
HTTP/1.1 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",
                "protocol_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",
                "protocol_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"
                "protocol_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",
                "protocol_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",
                "protocol_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",
                "protocol_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",
                "protocol_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",
                "protocol_port": 3306,
                "weight" : 1,
                "admin_state_up" : true,
                "status" : "INACTIVE"
              }
            ]
}


Retrieve a specific Member

Verb URI
GET /members/member_id

This operation retrieves the configuration of a member.

Normal Response Code(s): 200

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

This operation does not require a request body.

This operation returns a response body. On success, the returned response is a Member object which can contain the following attributes:

  • id
  • tenant_id
  • pool_id
  • address
  • protocol_port
  • weight
  • admin_state_up
  • status

Example. Retrieve the configuration of a pool 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
HTTP/1.1 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",
                "protocol_port": 8080,
                "weight" : 1,
                "admin_state_up" : true,
                "status" : "ACTIVE"
              }
}


Create Pool Members

Verb URI
POST /v1.0/members

Normal Response Code(s): 202

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

When a member is created, 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.

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

  • tenant_id: only required if the caller has an admin role and wants to create a pool for another tenant.
  • address: the IP address of the pool member on the pool's network.
  • protocol_port: The port on which the pool member listens for requests or connections.
  • pool_id: The pool to which the member belongs.

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


#!wiki caution
Note:

When a member is added to a pool, it is enabled by default (admin_state_up = true) unless admin_state_up was set to false.


Example. Create a member

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
{
      "member" : {
                   "address": "192.168.224.31",
                   "protocol_port": 8080,
                   "pool_id": "cfc6589d-f949-4c66-99d2-c2da56ef3764"
                 }
}


JSON Response:


#!highlight javascript numbers=disable
HTTP/1.1 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",
                "protocol_port": 8080,
                "weight" : 1,
                "admin_state_up" : true,
                "status" : "PENDING_CREATE"

              }
}


Update a Member

Verb URI
PUT /v1.0/members/member_id

Normal Response Code(s): 202

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

The caller of this operation may update the following attributes of the Member:

  • pool_id
  • weight
  • admin_state_up

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


#!wiki caution
Note

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


#!wiki caution
Note

A pool member that is pending deletion or has an ERROR status cannot be updated.


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 member are gracefully drained or forcibly terminated. The member's status changes to INACTIVE once the configuration has been successfully applied.

Example. Disable a pool 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
HTTP/1.1 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",
                "protocol_port": 8080,
                "weight" : 1,
                "admin_state_up" : false,
                "status" : "PENDING_UPDATE"
             }
}

Remove a Member

Verb URI
DELETE /v1.0/members/member_id Removes a member from a pool.

Normal Response Code(s): 204

Error Response Code(s): serviceFault (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. 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
HTTP/1.1 204 No Content

Health Monitors

Verb URI
GET /v1.0/health_monitors/
GET /v1.0/health_monitors/health_monitor_id
PUT /v1.0/health_monitors/health_monitor_id
DELETE /v1.0/health_monitors/health_monitor_id Remove the health monitor.

Normal Response Code(s): 200, 202, 204

Error Response Code(s): serviceFault (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 Health Monitor

Verb URI
POST /v1.0/health_monitors Creates a Health Monitor.

Normal Response Code(s): 202

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

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 must 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.
  • max_retries: Number of permissible ping failures before changing the member's status to INACTIVE. Must be a number between 1 and 10.

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

Example. Monitor PING

JSON Request:

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

{
    "health_monitor" :
      {
         "type" : "PING",
         "delay" : 20,
         "timeout": 10,
         "max_retries": 3
      }
}


JSON Response:

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

{
    "health_monitor" :
      {
         "id" : "f784c3a7-c4e8-44da-bf12-5ff417d27555",
         "type" : "PING",
         "delay" : 20,
         "timeout": 10,
         "max_retries": 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 must 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.
  • max_retries: Number of permissible connection failures before changing the member's status to INACTIVE. Must be a number between 1 and 10.

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

Example. Create a TCP Monitor

JSON Request:

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

{
    "health_monitor" :
      {
         "type" : "TCP",
         "delay" : 20,
         "timeout": 10,
         "max_retries": 3
      }
}


JSON Response:


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

{
    "health_monitor" :
      {
         "id" : "e5069610-744b-42a7-8bd8-ceac1a229cd4",
         "type" : "TCP",
         "delay" : 20,
         "timeout": 10,
         "max_retries": 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 member. 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.

  • http_method: The HTTP method used for requests by the monitor. If this attribute is not specified, it defaults to "GET".
  • url_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). If this is not specified it defaults to "/".
  • expected_codes: These are the list of HTTP status codes expected in response from the member to declare it healthy. This
  attribute can contain one value, or a list of values separated by comma, or a range of values (e.g. "200-299"). If this attribute
  is not specified, it defaults to "200".

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

Example. Create a HTTP Monitor

JSON Request:

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

{
    "health_monitor" :
      {
         "type" : "HTTP",
         "delay" : 20,
         "timeout": 10,
         "max_retries": 3,
         "http_method" : "HEAD", 
         "path" : "/check",
         "expected_codes" : "200-299"
      }
}


JSON Response:

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

{
    "health_monitor" :
      {
         "id" : "f3eeab00-8367-4524-b662-55e64d4cacb5",
         "type" : "HTTP",
         "delay" : 20,
         "timeout": 10,
         "max_retries": 3,
         "http_method" : "GET",
         "url_path" : "/",
         "expected_codes" : "200,202",
         "admin_state_up": true,
         "status": "PENDING_CREATE"
      }
}


Update a Health Monitor

Verb URI
PUT /v1.0/health_monitors/health_monitor_id Updates a Health Monitor.

All the attributes of a Health Monitor can be updated apart from the type attribute which is immutable.

The status of the Health Monitor in the response can take one of the following values: ACTIVE, PENDING_UPDATE or ERROR.


#!wiki caution
Note

A Health Monitor that is pending deletion or has an ERROR status cannot be updated.


The following example illustrate how to update a Health Monitor.

Example. Update a TCP Monitor

JSON Request:

#!highlight javascript numbers=disable
PUT /v1.0/health_monitors/e5069610-744b-42a7-8bd8-ceac1a229cd4
Host: lbaas-service.cloudX.com:8651
Accept: application/json
Content-Type: application/json
X-Auth-Token:887665443383838
Content-Length: 41

{
    "health_monitor" :
      {
         "delay" : 30,
         "max_retries": 2
      }
}


JSON Response:


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

{
    "health_monitor" :
      {
         "id" : "e5069610-744b-42a7-8bd8-ceac1a229cd4",
         "type" : "TCP",
         "delay" : 30,
         "timeout": 10,
         "max_retries": 2,
         "admin_state_up": true,
         "status": "PENDING_UPDATE"
      }
}


Delete a Health Monitor

When a health monitor is deleted, it is automatically dissociated from all the pools where it is used.

Example. Delete a TCP Monitor

JSON Request:

#!highlight javascript numbers=disable
DELETE /v1.0/health_monitors/e5069610-744b-42a7-8bd8-ceac1a229cd4
Host: lbaas-service.cloudX.com:8651
Accept: application/json
X-Auth-Token:887665443383838


JSON Response:


#!highlight javascript numbers=disable
HTTP/1.1 204 No Content


List all Health Monitors

This operation returns a response body. On success, the returned response is a (potentially empty) list, each element in the list is a Health Monitor object that can contain the following attributes:

  • id
  • type
  • delay
  • timeout
  • max_retries
  • admin_state_up
  • status

In addition, if the type of the Health Monitor is HTTP or HTTPS, the following attributes are also present:

  • http_method
  • url_path
  • expected_codes

Example. List all health monitors accessible to this tenant

JSON Request:

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


JSON Response:

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

{
   "health_monitors" : [
                       {
                         "id" : "e5069610-744b-42a7-8bd8-ceac1a229cd4",
                         "type" : "TCP",
                         "delay" : 30,
                         "timeout": 10,
                         "max_retries": 2,
                         "admin_state_up": true,
                         "status": "ACTIVE"
                        },
                        {
                          "id" : "f3eeab00-8367-4524-b662-55e64d4cacb5",
                          "type" : "HTTP",
                          "delay" : 20,
                          "timeout": 10,
                          "max_retries": 3,
                          "http_method" : "GET",
                          "url_path" : "/check",
                          "expected_codes" : "200,202",
                          "admin_state_up": true,
                          "status": "PENDING_CREATE"
                         }
                 ]
}


Associate Health Monitors with a Pool

You can associate a health monitor with an existing pool. Once associated, the health monitor 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 it 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

JSON Request:

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

{
    "id" : "f3eeab00-8367-4524-b662-55e64d4cacb5"
}


JSON Response:

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

{
    "id" : "f784c3a7-c4e8-44da-bf12-5ff417d27555",
}

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

JSON Request:

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


JSON Response:

#!highlight javascript numbers=disable
HTTP/1.1 204 No Content

Statistics

Retrieve Traffic Statistics for a Pool

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

Normal Response Code(s): 200

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

This operation retrieves the aggregated traffic statistics for all members of a pool. The returned statistics are not necessarily real-time and might be collected in the background on a periodic basis and the cached data returned to the user during this call.

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. Retrieve the stats for a pool

JSON Request:

#!highlight javascript 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 javascript numbers=disable
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 114

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