Jump to: navigation, search

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

< Neutron‎ | LBaaS
(Pools)
(Update a Listener)
Line 630: Line 630:
 
'''Error Response Code(s)''': serviceFault (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 Listener. Upon successful validation of the request, the service will return a 202 (Accepted) response code. A caller should check that the Listener provisioning_status has changed to ACTIVE to confirm that the update has taken effect. If the Listener provisioning_status is "PENDING_UPDATE" then the caller can poll the Listener object (using a GET operation) to wait for the changes to be applied.
+
This operation updates the attributes of the specified Listener. Upon successful validation of the request, the service will return a 202 (Accepted) response code.
  
 
The update operation allows the caller to change one or more of the following Listener attributes:
 
The update operation allows the caller to change one or more of the following Listener attributes:
Line 704: Line 704:
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
 
  
 
==== Remove a Listener ====
 
==== Remove a Listener ====

Revision as of 02:35, 2 February 2015

API Operations

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

Load Balancers

Use the following APIs to manage Load Balancer resources

Verb URI
GET /lbaas/loadbalancers/
GET /lbaas/loadbalancers/loadbalancer_id
POST /lbaas/loadbalancers
PUT /lbaas/loadbalancers/loadbalancer_id
DELETE /lbaas/loadbalancers/loadbalancer_id

List all Load Balancers

Verb URI
GET /lbaas/loadbalancers/

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 load balancers associated with your tenant account.

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 Load Balancer that can contain the following attributes:

  • id
  • tenant_id
  • name
  • description
  • vip_subnet_id
  • vip_address
  • admin_state_up
  • listeners
  • provisioning_status
  • operating_status

Example . List all Load Balancers

JSON Request:


#!highlight javascript numbers=disable
GET /lbaas/loadbalancers
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

{
    "loadbalancers": [
        {
            "description": "simple lb",
            "admin_state_up": true,
            "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c",
            "provisioning_status": "ACTIVE",
            "listeners": [ ],
            "vip_address": "10.0.0.2",
            "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2",
            "id": "a9729389-6147-41a3-ab22-a24aed8692b2",
            "operating_status": "ONLINE",
            "name": "loadbalancer1"
        }
    ]
}

Retrieve a specific Load Balancer

Verb URI
GET /lbaas/loadbalancers/"loadbalancer_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 Load Balancer object identified by loadbalancer_id. If the user is not an admin, and the Load Balancer 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 Load Balancer that can contain the following attributes:

  • id
  • tenant_id
  • name
  • description
  • vip_subnet_id
  • vip_address
  • admin_state_up
  • listeners
  • provisioning_status
  • operating_status

Example . Retrieve a Load Balancer's details:

JSON Request:


#!highlight javascript numbers=disable
GET /lbaas/loadbalancers/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

{
    "loadbalancer": {
        "description": "simple lb",
        "admin_state_up": true,
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c",
        "provisioning_status": "ACTIVE",
        "listeners": [ ],
        "vip_address": "10.0.0.2",
        "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2",
        "id": "a9729389-6147-41a3-ab22-a24aed8692b2",
        "operating_status": "ONLINE",
        "name": "loadbalancer1"
    }
}

Create a Load Balancer

Verb URI
POST /lbaas/loadbalancers

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 Load Balancer based on the configuration defined in the request object. Once the request is validated and progress has started on the provisioning process, a response object will be returned. The object will contain a unique identifier and the status of provisioning the Load Balancer.

The provisioning_status of the Load Balancer 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 Load Balancer, the caller can check on the progress of the provisioning operation by performing a GET on /lbaas/loadbalancers/loadbalancer_id. When the status of the load balancer returned changes to "ACTIVE", then the Load Balancer 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 Load Balancer:

  • tenant_id: only required if the caller has an admin role and wants to create a Load Balancer for another tenant.
  • vip_subnet_id: The network on which to allocate the load balancer's vip address. A tenant can only create load balancer vips on networks authorized by policy (e.g. her own networks or shared/provider networks).

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

  • admin_state_up: The default value for this attribute is true.
  • name: The default value for this attribute will be an empty string.
  • description: The default value for this attribute will be an empty string.

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

Users may configure all documented features of the Load Balancer at creation time by simply providing the additional elements or attributes in the request.

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

Example . Create a Load Balancer

JSON Request:

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

{
    "loadbalancer": {
        "name": "loadbalancer1",
        "description": "simple lb",
        "tenant_id": "b7c1a69e88bf4b21a8148f787aef2081",
        "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2",
        "vip_address": "10.0.0.4",
        "admin_state_up": true
    }
}


JSON Response:

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

{
    "loadbalancer": {
        "description": "simple lb",
        "admin_state_up": true,
        "tenant_id": "b7c1a69e88bf4b21a8148f787aef2081",
        "provisioning_status": "ACTIVE",
        "listeners": [],
        "vip_address": "10.0.0.4",
        "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2",
        "id": "a36c20d0-18e9-42ce-88fd-82a35977ee8c",
        "operating_status": "ONLINE",
        "name": "loadbalancer1"
    }
}


A user can supply a vip_address field if she owns the subnet on which the Load Balancer's VIP will be created. If a vip_address is not specified in the payload, then the LBaaS service will allocate one from the Load Balancer VIP's subnet.

Update a Load Balancer

Verb URI
PUT /lbaas/loadbalancers/loadbalancer_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 Load Balancer. Upon successful validation of the request, the service will return a 202 (Accepted) response code. A caller should check that the Load Balancer provisioning_status has changed to ACTIVE to confirm that the update has taken effect. If the Load Balancer provisioning_status is "PENDING_UPDATE" then the caller can poll the Load Balancer 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 Load Balancer attributes:

  • name
  • description
  • admin_state_up

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


#!wiki caution
Note

The Load Balancer's ID, provisioning_status, operating_status, vip_subnet_id, vip_address, and listeners are immutable attributes and cannot be updated. Supplying an unsupported attribute will result in a 422 (Immutable) fault.


#!wiki caution
Note

A Load Balancer that is does not have a provisioning_status of ACTIVE  cannot be updated.


Example . Updating a Load Balancer

JSON Request:

#!highlight javascript numbers=disable
PUT /lbaas/loadbalancers/a36c20d0-18e9-42ce-88fd-82a35977ee8c
Host: lbaas-service.cloudX.com:8651
Content-Type: application/json
Accept: application/json
X-Auth-Token:887665443383838
Content-Length: 75

{
    "loadbalancer": {
        "name": "loadbalancer2",
        "description": "simple lb2",
        "admin_state_up": false
    }
}


JSON Response:

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

{
    "loadbalancer": {
        "description": "simple lb2",
        "admin_state_up": false,
        "tenant_id": "b7c1a69e88bf4b21a8148f787aef2081",
        "provisioning_status": "PENDING_UPDATE",
        "listeners": [],
        "vip_address": "10.0.0.4",
        "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2",
        "id": "a36c20d0-18e9-42ce-88fd-82a35977ee8c",
        "operating_status": "ONLINE",
        "name": "loadbalancer2"
    }
}


Remove a Load Balancer

Verb URI
DELETE /lbaas/loadbalancers/loadbalancer_id Remove a Load Balancer 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 Load Balancer 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 Load Balancer

JSON Request:

#!highlight javascript numbers=disable
DELETE /lbaas/loadbalancers/a36c20d0-18e9-42ce-88fd-82a35977ee8c
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

Listeners

Use the following APIs to manage Listener resources

Verb URI
GET /lbaas/listeners/
GET /lbaas/listeners/listener_id
POST /lbaas/listeners
PUT /lbaas/listeners/listener_id
DELETE /lbaas/listeners/listener_id

List all Listeners

Verb URI
GET /lbaas/listeners/

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 listeners associated with your tenant account.

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 Listener that can contain the following attributes:

  • id
  • tenant_id
  • name
  • description
  • protocol
  • protocol_port
  • connection_limit
  • default_pool_id
  • admin_state_up
  • loadbalancers

Example . List all Listeners

JSON Request:


#!highlight javascript numbers=disable
GET /lbaas/listeners
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

{
    "listeners": [
        {
            "default_pool_id": null,
            "protocol": "HTTP",
            "description": "",
            "admin_state_up": true,
            "loadbalancers": [
                {
                    "id": "a9729389-6147-41a3-ab22-a24aed8692b2"
                }
            ],
            "tenant_id": "3e4d8bec50a845fcb09e03a4375c691d",
            "connection_limit": 100,
            "protocol_port": 80,
            "id": "35cb8516-1173-4035-8dae-0dae3453f37f",
            "name": ""
        }
    ]
}

Retrieve a specific Listener

Verb URI
GET /lbaas/listeners/"listener_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 Listener object identified by listener_id. If the user is not an admin, and the Listener 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 Listener that can contain the following attributes:

  • id
  • tenant_id
  • name
  • description
  • protocol
  • protocol_port
  • connection_limit
  • default_pool_id
  • admin_state_up
  • loadbalancers

Example . Retrieve a Listener's details:

JSON Request:


#!highlight javascript numbers=disable
GET /lbaas/listeners/35cb8516-1173-4035-8dae-0dae3453f37f
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

{
    "listener": {
        "default_pool_id": null,
        "protocol": "HTTP",
        "description": "",
        "admin_state_up": true,
        "loadbalancers": [
            {
                "id": "a9729389-6147-41a3-ab22-a24aed8692b2"
            }
        ],
        "tenant_id": "3e4d8bec50a845fcb09e03a4375c691d",
        "connection_limit": 100,
        "protocol_port": 80,
        "id": "35cb8516-1173-4035-8dae-0dae3453f37f",
        "name": ""
    }
}

Create a Listener

Verb URI
POST /lbaas/listeners

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

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

  • tenant_id: only required if the caller has an admin role and wants to create a Listener for another tenant.
  • loadbalancer_id: The load balancer this listener will be provisioned on. A tenant can only create listeners on load balancers authorized by policy (e.g. her own load balancers).
  • protocol: The protocol the frontend will be listening for. Must be one of TCP, HTTP, or HTTPS
  • protocol_port: The port in which the frontend will be listening. Must be an integer in the range of 1-65535

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

  • admin_state_up: The default value for this attribute is true.
  • name: The default value for this attribute will be an empty string.
  • description: The default value for this attribute will be an empty string.
  • connection_limit: The default value for this attribute will be -1, indicating an infinite limit.

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 Listener at creation time by simply providing the additional elements or attributes in the request.

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

A Listener cannot be update if the load balancer it is attempting to be attached to is not in an ACTIVE provisioning_status.

Example . Create a Listener

JSON Request:

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

{
    "listener": {
        "loadbalancer_id": "a36c20d0-18e9-42ce-88fd-82a35977ee8c",
        "protocol": "HTTP",
        "protocol_port": "80",
        "connection_limit": 100,
        "admin_state_up": true,
        "name": "listener1",
        "description": "listener one"
    }
}


JSON Response:

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

{
    "listener": {
        "default_pool_id": null,
        "protocol": "HTTP",
        "description": "listener one",
        "admin_state_up": true,
        "loadbalancers": [
            {
                "id": "a36c20d0-18e9-42ce-88fd-82a35977ee8c"
            }
        ],
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c",
        "connection_limit": 100,
        "protocol_port": 80,
        "id": "39de4d56-d663-46e5-85a1-5b9d5fa17829",
        "name": "listener1"
    }
}


Update a Listener

Verb URI
PUT /lbaas/listeners/listener_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 Listener. Upon successful validation of the request, the service will return a 202 (Accepted) response code.

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

  • name
  • description
  • admin_state_up
  • connection_limit


#!wiki caution
Note

The Listener's ID, tenant_id, loadbalancer_id, loadbalancers, default_pool_id, protocol, and protocol_port are immutable attributes and cannot be updated. Supplying an unsupported attribute will result in a 422 (Immutable) fault.


#!wiki caution
Note

A Listener cannot be update if the load balancer it is attached to is not in an ACTIVE provisioning_status.


Example . Updating a Listener

JSON Request:

#!highlight javascript numbers=disable
PUT /lbaas/listeners/39de4d56-d663-46e5-85a1-5b9d5fa17829
Host: lbaas-service.cloudX.com:8651
Content-Type: application/json
Accept: application/json
X-Auth-Token:887665443383838
Content-Length: 75

{
    "listener": {
        "name": "listener2",
        "description": "listener two",
        "admin_state_up": false,
        "connection_limit": 200
    }
}


JSON Response:

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

{
    "listener": {
        "default_pool_id": null,
        "protocol": "HTTP",
        "description": "listener two",
        "admin_state_up": false,
        "loadbalancers": [
            {
                "id": "a36c20d0-18e9-42ce-88fd-82a35977ee8c"
            }
        ],
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c",
        "connection_limit": 200,
        "protocol_port": 80,
        "id": "39de4d56-d663-46e5-85a1-5b9d5fa17829",
        "name": "listener2"
    }
}

Remove a Listener

Verb URI
DELETE /lbaas/listeners/listener_id Remove a Listener from the account.

Normal Response Code(s): 204

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

This operation removes the specified Listener 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.

A Listener cannot be deleted if the load balancer it is attached to is not in an ACTIVE provisioning_status.

Example. Deleting a Listener

JSON Request:

#!highlight javascript numbers=disable
DELETE /lbaas/listeners/39de4d56-d663-46e5-85a1-5b9d5fa17829
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

Use the following APIs to manage Pool resources

Verb URI
GET /lbaas/pools/
GET /lbaas/pools/pool_id
POST /lbaas/pools
PUT /lbaas/pools/pool_id
DELETE /lbaas/pools/pool_id

List all Pools

Verb URI
GET /lbaas/pools/

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 pools associated with your tenant account.

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 Pool that can contain the following attributes:

  • id
  • tenant_id
  • name
  • description
  • protocol
  • lb_algorithm
  • session_persistence
  • admin_state_up
  • listeners
  • members
  • healthmonitor_id

Example . List all Pools

JSON Request:


#!highlight javascript numbers=disable
GET /lbaas/pools
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

{
    "pools": [
        {
            "lb_algorithm": "ROUND_ROBIN",
            "protocol": "HTTP",
            "description": "simple pool",
            "admin_state_up": true,
            "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c",
            "healthmonitor_id": null,
            "listeners": [
                {
                    "id": "35cb8516-1173-4035-8dae-0dae3453f37f"
                }
            ],
            "members": [ ],
            "id": "4c0a0a5f-cf8f-44b7-b912-957daa8ce5e5",
            "name": "pool1"
        }
    ]
}

Retrieve a specific Pool

Verb URI
GET /lbaas/pools/"pool_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 Pool object identified by pool_id. If the user is not an admin, and the Pool 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 Pool that can contain the following attributes:

  • id
  • tenant_id
  • name
  • description
  • protocol
  • lb_algorithm
  • session_persistence
  • admin_state_up
  • listeners
  • members
  • healthmonitor_id

Example . Retrieve a Pool's details:

JSON Request:


#!highlight javascript numbers=disable
GET /lbaas/pools/35cb8516-1173-4035-8dae-0dae3453f37f
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

{
    "pool": {
        "lb_algorithm": "ROUND_ROBIN",
        "protocol": "HTTP",
        "description": "simple pool",
        "admin_state_up": true,
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c",
        "healthmonitor_id": null,
        "listeners": [
            {
                "id": "35cb8516-1173-4035-8dae-0dae3453f37f"
            }
        ],
        "members": [],
        "id": "4c0a0a5f-cf8f-44b7-b912-957daa8ce5e5",
        "name": "pool1"
    }
}

Create a Pool

Verb URI
POST /lbaas/pools

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

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.
  • protocol: The protocol this pool and its members will be listening for. Must be one of TCP, HTTP, or HTTPS
  • lb_algorithm: The load balancing algorithm to distribute traffic to the pool's members. Must be one of ROUND_ROBIN, LEAST_CONNECTIONS, or SOURCE_IP.
  • protocol_port: The port in which the frontend will be listening. Must be an integer in the range of 1-65535
  • listener_id: The listener in which this pool will become the default pool. There can only be on default pool for a listener.

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

  • admin_state_up: The default value for this attribute is true.
  • name: The default value for this attribute will be an empty string.
  • description: The default value for this attribute will be an empty string.
  • session_persistence: The default value for this is an empty dictionary.

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 Pool at creation time by simply providing the additional elements or attributes in the request.

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

A Pool cannot be update if the load balancer it is attempting to be attached to is not in an ACTIVE provisioning_status.

Example . Create a Pool

JSON Request:

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

{
    "pool": {
        "name": "pool1",
        "description": "simple pool",
        "listener_id": "39de4d56-d663-46e5-85a1-5b9d5fa17829",
        "lb_algorithm": "ROUND_ROBIN",
        "protocol": "HTTP",
        "session_persistence": {
            "type": "APP_COOKIE",
            "cookie_name": "my_cookie"
        },
        "admin_state_up": true
    }
}


JSON Response:

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

{
    "pool": {
        "lb_algorithm": "ROUND_ROBIN",
        "protocol": "HTTP",
        "description": "simple pool",
        "admin_state_up": true,
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c",
        "session_persistence": {
            "cookie_name": "my_cookie",
            "type": "APP_COOKIE"
        },
        "healthmonitor_id": null,
        "listeners": [
            {
                "id": "39de4d56-d663-46e5-85a1-5b9d5fa17829"
            }
        ],
        "members": [],
        "id": "12ff63af-4127-4074-a251-bcb2ecc53ebe",
        "name": "pool1"
    }
}


Update a Pool

Verb URI
PUT /lbaas/pools/pool_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 Pool. Upon successful validation of the request, the service will return a 202 (Accepted) response code.

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

  • name
  • description
  • admin_state_up
  • lb_algorithm
  • session_persistence


#!wiki caution
Note

The Pool's ID, tenant_id, listener_id, listeners, healthmonitor_id, protocol, and members are immutable attributes and cannot be updated. Supplying an unsupported attribute will result in a 422 (Immutable) fault.


#!wiki caution
Note

A Pool cannot be updated if the load balancer it is attached to is not in an ACTIVE provisioning_status.


Example . Updating a Pool

JSON Request:

#!highlight javascript numbers=disable
PUT /lbaas/pools/12ff63af-4127-4074-a251-bcb2ecc53ebe
Host: lbaas-service.cloudX.com:8651
Content-Type: application/json
Accept: application/json
X-Auth-Token:887665443383838
Content-Length: 75

{
    "pool": {
        "name": "pool2",
        "description": "pool two",
        "admin_state_up": false,
        "lb_algorithm": "LEAST_CONNECTIONS",
        "session_persistence": {"type": "HTTP_COOKIE"}
    }
}


JSON Response:

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

{
    "pool": {
        "lb_algorithm": "LEAST_CONNECTIONS",
        "protocol": "HTTP",
        "description": "pool two",
        "admin_state_up": false,
        "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c",
        "session_persistence": {
            "cookie_name": null,
            "type": "HTTP_COOKIE"
        },
        "healthmonitor_id": null,
        "listeners": [
            {
                "id": "39de4d56-d663-46e5-85a1-5b9d5fa17829"
            }
        ],
        "members": [],
        "id": "12ff63af-4127-4074-a251-bcb2ecc53ebe",
        "name": "pool2"
    }
}


Remove a Pool

Verb URI
DELETE /lbaas/pools/pool_id Remove a Pool from the account.

Normal Response Code(s): 204

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

This operation removes the specified Pool 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.

A Pool cannot be deleted if the load balancer it is attached to is not in an ACTIVE provisioning_status.

Example. Deleting a Pool

JSON Request:

#!highlight javascript numbers=disable
DELETE /lbaas/pools/12ff63af-4127-4074-a251-bcb2ecc53ebe
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