Jump to: navigation, search

Neutron/LBaaS/API 2.0

< Neutron‎ | LBaaS

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
GET /lbaas/loadbalancers/loadbalancer_id/statuses
GET /lbaas/loadbalancers/loadbalancer_id/stats

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:


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

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:


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

Verb URI
POST /lbaas/loadbalancers

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

Verb URI
PUT /lbaas/loadbalancers/loadbalancer_id

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

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:

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

Verb URI
GET /lbaas/loadbalancers/loadbalancer_id/statuses

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

Verb URI
GET /lbaas/loadbalancers/loadbalancer_id/stats

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

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:


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

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:


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

Verb URI
POST /lbaas/listeners

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

Verb URI
PUT /lbaas/listeners/listener_id

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

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:

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

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:


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

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:


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

Verb URI
POST /lbaas/pools

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

Verb URI
PUT /lbaas/pools/pool_id

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

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:

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

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

List all Members of a Pool

Verb URI
GET /lbaas/pools/pool_id/members

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

Verb URI
GET /lbaas/pools/"pool_id/members/member_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 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

Verb URI
POST /lbaas/pools/pool_id/members

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

Verb URI
PUT /lbaas/pools/pool_id/members/member_id

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

Verb URI
DELETE /lbaas/pools/pool_id/members/member_id 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

Verb URI
GET /lbaas/healthmonitors/
GET /lbaas/healthmonitors/healthmonitor_id
POST /lbaas/healthmonitors
PUT /lbaas/healthmonitors/healthmonitor_id
DELETE /lbaas/healthmonitors/healthmonitor_id

List all Health Monitors

Verb URI
GET /lbaas/healthmonitors/

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

Verb URI
GET /lbaas/healthmonitors/"healthmonitor_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 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

Verb URI
POST /lbaas/healthmonitors

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

Verb URI
PUT /lbaas/healthmonitors/healthmonitor_id

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

Verb URI
DELETE /lbaas/healthmonitors/healthmonitor_id Remove a Health Monitor 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 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