Neutron/LBaaS/API 2.0

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

List all Load Balancers
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:

GET /lbaas/loadbalancers Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

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

GET /lbaas/loadbalancers/36e08a3e-a78f-4b40-a229-1e7e23eee1ab Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

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
Normal Response Code(s): 201

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.

These attributes are optional:
 * vip_address: if provided, the system will attempt to assign the load balancer's vip address to this.
 * provider: the name of a valid provider to provision the load balancer.

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:

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:

HTTP/1.1 201 Created 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
Normal Response Code(s): 200

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.

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.

Note

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

'''Example. Updating a Load Balancer '''

JSON Request:

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:

HTTP/1.1 200 OK 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
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:

DELETE /lbaas/loadbalancers/a36c20d0-18e9-42ce-88fd-82a35977ee8c Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

HTTP/1.1 204 No Content

Retrieve a specific Load Balancer's Status Tree
Normal Response Code(s): 200

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

This operation returns a status tree of 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 status tree that consists of the load balancer and all of its children's provisioning and operating statuses.

'''Example. Retrieve a Load Balancer's status tree: '''

JSON Request:

GET /lbaas/loadbalancers/36e08a3e-a78f-4b40-a229-1e7e23eee1ab Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

HTTP/1.1 200 OK Content-Type: application/json

{   "statuses": { "loadbalancer": { "operating_status": "ONLINE", "provisioning_status": "ACTIVE", "listeners": [ {                   "id": "6978ba19-1090-48a2-93d5-3523592b562a", "operating_status": "ONLINE", "provisioning_status": "ACTIVE", "pools": [ {                           "id": "f6aedfcb-9f7d-4cc5-83e1-8c02fd833922", "operating_status": "ONLINE", "provisioning_status": "ACTIVE", "members": [ {                                   "id": "fcf23bde-8cf9-4616-883f-208cebcbf858", "operating_status": "ONLINE", "provisioning_status": "ACTIVE" }                           ],                            "healthmonitor": { "id": "785131d2-8f7b-4fee-a7e7-3196e11b4518", "provisioning_status": "ACTIVE" }                       }                    ]                }            ]        }    } }

Retrieve a specific Load Balancer's Statistics
Normal Response Code(s): 200

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

This operation returns the statistics of 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 representation of a load balancer's listeners with the stats for each listener.

'''Example. Retrieve a Load Balancer's status tree: '''

JSON Request:

GET /lbaas/loadbalancers/36e08a3e-a78f-4b40-a229-1e7e23eee1ab Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

HTTP/1.1 200 OK Content-Type: application/json

{   "stats": { "loadbalancer": { "bytes_in": 0, "bytes_out": 0, "connections": 0, "active_connections": 0 }   } }

Listeners
Use the following APIs to manage Listener resources

List all 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:

GET /lbaas/listeners Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

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

GET /lbaas/listeners/35cb8516-1173-4035-8dae-0dae3453f37f Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

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
Normal Response Code(s): 201

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:

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:

HTTP/1.1 201 Created 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
Normal Response Code(s): 200

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

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.

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:

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:

HTTP/1.1 200 OK 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
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:

DELETE /lbaas/listeners/39de4d56-d663-46e5-85a1-5b9d5fa17829 Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

HTTP/1.1 204 No Content

Pools
Use the following APIs to manage Pool resources

List all 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:

GET /lbaas/pools Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

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

GET /lbaas/pools/35cb8516-1173-4035-8dae-0dae3453f37f Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

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
Normal Response Code(s): 201

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.
 * 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:

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:

HTTP/1.1 201 Created 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
Normal Response Code(s): 200

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

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.

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:

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:

HTTP/1.1 200 OK 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
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:

DELETE /lbaas/pools/12ff63af-4127-4074-a251-bcb2ecc53ebe Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

HTTP/1.1 204 No Content

Members
Use the following APIs to manage Member resources

List all Members of a Pool
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 members associated with a pool that is associated with your tenant account. The list of members shown will only be members that belong to the pool object identified by pool_id.

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


 * id
 * tenant_id
 * address
 * protocol_port
 * weight
 * subnet_id
 * admin_state_up

'''Example. List all Members of a Pool'''

JSON Request:

GET /lbaas/pools/4c0a0a5f-cf8f-44b7-b912-957daa8ce5e5/members Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

HTTP/1.1 200 OK Content-Type: application/json

{   "members": [ {           "weight": 1, "admin_state_up": true, "subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2", "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c", "address": "10.0.0.8", "protocol_port": 80, "id": "9a7aff27-fd41-4ec1-ba4c-3eb92c629313" }   ] }

Retrieve a specific Member of a Pool
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 Member object identified by member_id that belongs to a Pool object identified by pool_id. If the user is not an admin, and the Pool or Member object do not 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
 * address
 * protocol_port
 * weight
 * subnet_id
 * admin_state_up

'''Example. Retrieve a Member of a Pool's details: '''

JSON Request:

GET /lbaas/pools/4c0a0a5f-cf8f-44b7-b912-957daa8ce5e5/members/9a7aff27-fd41-4ec1-ba4c-3eb92c629313 Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

HTTP/1.1 200 OK Content-Type: application/json

{   "member": { "weight": 1, "admin_state_up": true, "subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2", "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c", "address": "10.0.0.8", "protocol_port": 80, "id": "9a7aff27-fd41-4ec1-ba4c-3eb92c629313" } }

Add a New Member to a Pool
Normal Response Code(s): 201

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 Member and adds it to a 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.
 * address: The IP Address of the member to receive traffic from the load balancer.
 * protocol_port: The port that the member is listening to receive traffic..
 * subnet_id: The subnet in which to access the member

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


 * admin_state_up: The default value for this attribute is true.
 * weight: The default value for this attribute will be 1.

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

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

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

'''Example. Add a Member to a Pool '''

JSON Request:

POST /lbaas/pools/4c0a0a5f-cf8f-44b7-b912-957daa8ce5e5/members Host: lbaas-service.cloudX.com:8651 Content-Type: application/json Accept: application/json X-Auth-Token:887665443383838

{   "member": { "address": "10.0.0.8", "protocol_port": "80", "admin_state_up": true, "subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2", "weight": "1" } }

JSON Response:

HTTP/1.1 201 Created Content-Type: application/json Content-Length: 213

{   "member": { "weight": 1, "admin_state_up": true, "subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2", "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c", "address": "10.0.0.8", "protocol_port": 80, "id": "9a7aff27-fd41-4ec1-ba4c-3eb92c629313" } }

Update a Member of a Pool
Normal Response Code(s): 200

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 200 (OK) response code.

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


 * weight
 * admin_state_up

Note

The Member's ID, tenant_id, address, protocol_port, and subnet_id are immutable attributes and cannot be updated. Supplying an unsupported attribute will result in a 422 (Immutable) fault.

Note

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

'''Example. Updating a Member of a Pool '''

JSON Request:

PUT /lbaas/pools/4c0a0a5f-cf8f-44b7-b912-957daa8ce5e5/members/9a7aff27-fd41-4ec1-ba4c-3eb92c629313 Host: lbaas-service.cloudX.com:8651 Content-Type: application/json Accept: application/json X-Auth-Token:887665443383838 Content-Length: 75

{   "member": { "admin_state_up": false, "weight": 5 } }

JSON Response:

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 282

{   "member": { "weight": 5, "admin_state_up": false, "subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2", "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c", "address": "10.0.0.8", "protocol_port": 80, "id": "9a7aff27-fd41-4ec1-ba4c-3eb92c629313" } }

Remove a Member from a Pool
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 Member 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 Member cannot be deleted if the load balancer it is attached to is not in an ACTIVE provisioning_status.

'''Example. Removing a Member from a Pool '''

JSON Request:

DELETE /lbaas/pools/12ff63af-4127-4074-a251-bcb2ecc53ebe/members/9a7aff27-fd41-4ec1-ba4c-3eb92c629313 Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

HTTP/1.1 204 No Content

Health Monitors
Use the following APIs to manage Health Monitor resources

List all Health Monitors
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 health monitors 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 Health Monitor that can contain the following attributes:


 * id
 * tenant_id
 * type
 * delay
 * timeout
 * max_retries
 * http_method
 * url_path
 * expected_codes
 * admin_state_up
 * pool_id
 * pools

'''Example. List all Health Monitors'''

JSON Request:

GET /lbaas/healthmonitors Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

HTTP/1.1 200 OK Content-Type: application/json

{   "healthmonitors": [ {           "admin_state_up": true, "tenant_id": "6f3584d5754048a18e30685362b88411", "delay": 1, "expected_codes": "200,201,202", "max_retries": 5, "http_method": "GET", "timeout": 1, "pools": [ {                   "id": "74aa2010-a59f-4d35-a436-60a6da882819" }           ],            "url_path": "/index.html", "type": "HTTP", "id": "0a9ac99d-0a09-4b18-8499-a0796850279a" }   ] }

Retrieve a specific Health Monitor
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 Health Monitor object identified by healthmonitor_id. If the user is not an admin, and the Health Monitor 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 Health Monitor that can contain the following attributes:


 * id
 * tenant_id
 * type
 * delay
 * timeout
 * max_retries
 * http_method
 * url_path
 * expected_codes
 * admin_state_up
 * pool_id
 * pools

'''Example. Retrieve a Health Monitor's details: '''

JSON Request:

GET /lbaas/healthmonitors/35cb8516-1173-4035-8dae-0dae3453f37f Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

HTTP/1.1 200 OK Content-Type: application/json

{   "healthmonitor": { "admin_state_up": true, "tenant_id": "6f3584d5754048a18e30685362b88411", "delay": 1, "expected_codes": "200,201,202", "max_retries": 5, "http_method": "GET", "timeout": 1, "pools": [ {               "id": "74aa2010-a59f-4d35-a436-60a6da882819" }       ],        "url_path": "/index.html", "type": "HTTP", "id": "0a9ac99d-0a09-4b18-8499-a0796850279a" } }

Create a Health Monitor
Normal Response Code(s): 201

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 Health Monitor 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 Health Monitor:


 * tenant_id: only required if the caller has an admin role and wants to create a Health Monitor for another tenant.
 * type: The type of health monitor. Must be one of TCP, HTTP, HTTPS
 * delay: The interval in seconds between health checks.
 * timeout: The time in seconds that a health check times out.
 * max_retries: Number of failed health checks before marked as OFFLINE.
 * pool_id: The pool that this health monitor will monitor.

Some attributes will receive default values if not specified in the request and are only useful when health monitor type of HTTP(S) is specified:


 * http_method: The default value for this attribute is GET.
 * url_path: The default value is "/"
 * expected_codes: The expected http status codes to get from a successful health check. Defaults to 200.
 * admin_state_up: The default is true.

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

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

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

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

'''Example. Create a Health Monitor '''

JSON Request:

POST /lbaas/healthmonitors Host: lbaas-service.cloudX.com:8651 Content-Type: application/json Accept: application/json X-Auth-Token:887665443383838

{   "healthmonitor": { "pool_id": "74aa2010-a59f-4d35-a436-60a6da882819", "type": "HTTP", "delay": "1", "timeout": 1, "http_method": "GET", "url_path": "/index.html", "expected_codes": "200,201,202", "max_retries": 5, "admin_state_up": true } }

JSON Response:

HTTP/1.1 201 Created Content-Type: application/json Content-Length: 213

{   "healthmonitor": { "admin_state_up": true, "tenant_id": "6f3584d5754048a18e30685362b88411", "delay": 1, "expected_codes": "200,201,202", "max_retries": 5, "http_method": "GET", "timeout": 1, "pools": [ {               "id": "74aa2010-a59f-4d35-a436-60a6da882819" }       ],        "url_path": "/index.html", "type": "HTTP", "id": "0a9ac99d-0a09-4b18-8499-a0796850279a" } }

Update a Health Monitor
Normal Response Code(s): 200

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

This operation updates the attributes of the specified Health Monitor. 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 Health Monitor attributes:


 * delay
 * timeout
 * max_retries
 * http_method
 * url_path
 * expected_codes
 * admin_state_up

Note

The Health Monitor's ID, tenant_id, pool_id, and type are immutable attributes and cannot be updated. Supplying an unsupported attribute will result in a 422 (Immutable) fault.

Note

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

'''Example. Updating a Health Monitor '''

JSON Request:

PUT /lbaas/healthmonitors/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

{   "healthmonitor": { "delay": "2", "timeout": 2, "http_method": "POST", "url_path": "/page.html", "expected_codes": "200", "max_retries": 2, "admin_state_up": false } }

JSON Response:

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 282

{   "healthmonitor": { "admin_state_up": false, "tenant_id": "6f3584d5754048a18e30685362b88411", "delay": 2, "expected_codes": "200", "max_retries": 2, "http_method": "POST", "timeout": 2, "pools": [ {               "id": "74aa2010-a59f-4d35-a436-60a6da882819" }       ],        "url_path": "/page.html", "type": "HTTP", "id": "0a9ac99d-0a09-4b18-8499-a0796850279a" } }

Remove a Health Monitor
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 Health Monitor 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 Health Monitor cannot be deleted if the load balancer it is attached to is not in an ACTIVE provisioning_status.

'''Example. Deleting a Health Monitor '''

JSON Request:

DELETE /lbaas/healthmonitors/12ff63af-4127-4074-a251-bcb2ecc53ebe Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838

JSON Response:

HTTP/1.1 204 No Content