Difference between revisions of "Neutron/LBaaS/API 2.0"
(→Health Monitors) |
|||
Line 21: | Line 21: | ||
|- | |- | ||
| DELETE | | DELETE | ||
− | | /lbaas/loadbalancers/''loadbalancer_id'' | + | | /lbaas/loadbalancers/''loadbalancer_id'' |
+ | |- | ||
+ | | GET | ||
+ | | /lbaas/loadbalancers/''loadbalancer_id''/statuses | ||
+ | |- | ||
+ | | GET | ||
+ | | /lbaas/loadbalancers/''loadbalancer_id''/stats | ||
|} | |} | ||
Line 362: | Line 368: | ||
<pre><nowiki>#!highlight javascript numbers=disable | <pre><nowiki>#!highlight javascript numbers=disable | ||
HTTP/1.1 204 No Content | HTTP/1.1 204 No Content | ||
+ | </nowiki></pre> | ||
+ | |||
+ | |||
+ | ==== Retrieve a specific Load Balancer's status tree ==== | ||
+ | {| border="1" cellpadding="2" cellspacing="0" | ||
+ | | 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: | ||
+ | |||
+ | |||
+ | <pre><nowiki>#!highlight javascript numbers=disable | ||
+ | GET /lbaas/loadbalancers/36e08a3e-a78f-4b40-a229-1e7e23eee1ab | ||
+ | Host: lbaas-service.cloudX.com:8651 | ||
+ | Accept: application/json | ||
+ | X-Auth-Token:887665443383838 | ||
+ | </nowiki></pre> | ||
+ | |||
+ | JSON Response: | ||
+ | |||
+ | |||
+ | <pre><nowiki>#!highlight javascript numbers=disable | ||
+ | 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" | ||
+ | } | ||
+ | } | ||
+ | ] | ||
+ | } | ||
+ | ] | ||
+ | } | ||
+ | } | ||
+ | } | ||
+ | </nowiki></pre> | ||
+ | |||
+ | ==== Retrieve a specific Load Balancer's Statistics ==== | ||
+ | {| border="1" cellpadding="2" cellspacing="0" | ||
+ | | 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: | ||
+ | |||
+ | |||
+ | <pre><nowiki>#!highlight javascript numbers=disable | ||
+ | GET /lbaas/loadbalancers/36e08a3e-a78f-4b40-a229-1e7e23eee1ab | ||
+ | Host: lbaas-service.cloudX.com:8651 | ||
+ | Accept: application/json | ||
+ | X-Auth-Token:887665443383838 | ||
+ | </nowiki></pre> | ||
+ | |||
+ | JSON Response: | ||
+ | |||
+ | |||
+ | <pre><nowiki>#!highlight javascript numbers=disable | ||
+ | HTTP/1.1 200 OK | ||
+ | Content-Type: application/json | ||
+ | |||
+ | { | ||
+ | "stats": { | ||
+ | "loadbalancer": { | ||
+ | "total_bytes_in": 0, | ||
+ | "total_bytes_out": 0, | ||
+ | "total_connections": 0, | ||
+ | "total_active_connections": 0, | ||
+ | "listeners": [ | ||
+ | { | ||
+ | "id": "", | ||
+ | "bytes_in": 0, | ||
+ | "total_connections": 0, | ||
+ | "active_connections": 0, | ||
+ | "bytes_out": 0 | ||
+ | } | ||
+ | ] | ||
+ | } | ||
+ | } | ||
+ | } | ||
</nowiki></pre> | </nowiki></pre> | ||
Revision as of 05:14, 4 February 2015
Contents
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:
#!highlight javascript numbers=disable GET /lbaas/loadbalancers Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 200 OK Content-Type: application/json { "loadbalancers": [ { "description": "simple lb", "admin_state_up": true, "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c", "provisioning_status": "ACTIVE", "listeners": [ ], "vip_address": "10.0.0.2", "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2", "id": "a9729389-6147-41a3-ab22-a24aed8692b2", "operating_status": "ONLINE", "name": "loadbalancer1" } ] }
Retrieve a specific Load Balancer
Verb | URI |
GET | /lbaas/loadbalancers/"loadbalancer_id |
Normal Response Code(s): 200
Error Response Code(s): 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 413 (Over limit), 500 (Internal server error), 503 (Service Unavailable)
This operation returns a Load Balancer object identified by loadbalancer_id. If the user is not an admin, and the Load Balancer object doesn't belong to her tenant account, she would receive a 403 (Forbidden) error.
This operation does not require a request body.
This operation returns a response body. On success, the returned element is a Load Balancer that can contain the following attributes:
- id
- tenant_id
- name
- description
- vip_subnet_id
- vip_address
- admin_state_up
- listeners
- provisioning_status
- operating_status
Example . Retrieve a Load Balancer's details:
JSON Request:
#!highlight javascript numbers=disable GET /lbaas/loadbalancers/36e08a3e-a78f-4b40-a229-1e7e23eee1ab Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 200 OK Content-Type: application/json { "loadbalancer": { "description": "simple lb", "admin_state_up": true, "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c", "provisioning_status": "ACTIVE", "listeners": [ ], "vip_address": "10.0.0.2", "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2", "id": "a9729389-6147-41a3-ab22-a24aed8692b2", "operating_status": "ONLINE", "name": "loadbalancer1" } }
Create a Load Balancer
Verb | URI |
POST | /lbaas/loadbalancers |
Normal Response Code(s): 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.
If the request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 (Bad Request) error response will be returned with information regarding the nature of the failure in the body of the response. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST the request again.
Users may configure all documented features of the Load Balancer at creation time by simply providing the additional elements or attributes in the request.
Users with an admin role can create Load Balancers on behalf of other tenants by specifying a tenant_id attribute different than their own.
Example . Create a Load Balancer
JSON Request:
#!highlight javascript numbers=disable POST /lbaas/loadbalancers Host: lbaas-service.cloudX.com:8651 Content-Type: application/json Accept: application/json X-Auth-Token:887665443383838 { "loadbalancer": { "name": "loadbalancer1", "description": "simple lb", "tenant_id": "b7c1a69e88bf4b21a8148f787aef2081", "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2", "vip_address": "10.0.0.4", "admin_state_up": true } }
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 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.
#!wiki caution Note The Load Balancer's ID, provisioning_status, operating_status, vip_subnet_id, vip_address, and listeners are immutable attributes and cannot be updated. Supplying an unsupported attribute will result in a 422 (Immutable) fault.
#!wiki caution Note A Load Balancer that is does not have a provisioning_status of ACTIVE cannot be updated.
Example . Updating a Load Balancer
JSON Request:
#!highlight javascript numbers=disable PUT /lbaas/loadbalancers/a36c20d0-18e9-42ce-88fd-82a35977ee8c Host: lbaas-service.cloudX.com:8651 Content-Type: application/json Accept: application/json X-Auth-Token:887665443383838 Content-Length: 75 { "loadbalancer": { "name": "loadbalancer2", "description": "simple lb2", "admin_state_up": false } }
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 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:
#!highlight javascript numbers=disable DELETE /lbaas/loadbalancers/a36c20d0-18e9-42ce-88fd-82a35977ee8c Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 204 No Content
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:
#!highlight javascript numbers=disable GET /lbaas/loadbalancers/36e08a3e-a78f-4b40-a229-1e7e23eee1ab Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 200 OK Content-Type: application/json { "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:
#!highlight javascript numbers=disable GET /lbaas/loadbalancers/36e08a3e-a78f-4b40-a229-1e7e23eee1ab Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 200 OK Content-Type: application/json { "stats": { "loadbalancer": { "total_bytes_in": 0, "total_bytes_out": 0, "total_connections": 0, "total_active_connections": 0, "listeners": [ { "id": "", "bytes_in": 0, "total_connections": 0, "active_connections": 0, "bytes_out": 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:
#!highlight javascript numbers=disable GET /lbaas/listeners Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 200 OK Content-Type: application/json { "listeners": [ { "default_pool_id": null, "protocol": "HTTP", "description": "", "admin_state_up": true, "loadbalancers": [ { "id": "a9729389-6147-41a3-ab22-a24aed8692b2" } ], "tenant_id": "3e4d8bec50a845fcb09e03a4375c691d", "connection_limit": 100, "protocol_port": 80, "id": "35cb8516-1173-4035-8dae-0dae3453f37f", "name": "" } ] }
Retrieve a specific Listener
Verb | URI |
GET | /lbaas/listeners/"listener_id |
Normal Response Code(s): 200
Error Response Code(s): 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 413 (Over limit), 500 (Internal server error), 503 (Service Unavailable)
This operation returns a Listener object identified by listener_id. If the user is not an admin, and the Listener object doesn't belong to her tenant account, she would receive a 403 (Forbidden) error.
This operation does not require a request body.
This operation returns a response body. On success, the returned element is a Listener that can contain the following attributes:
- id
- tenant_id
- name
- description
- protocol
- protocol_port
- connection_limit
- default_pool_id
- admin_state_up
- loadbalancers
Example . Retrieve a Listener's details:
JSON Request:
#!highlight javascript numbers=disable GET /lbaas/listeners/35cb8516-1173-4035-8dae-0dae3453f37f Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 200 OK Content-Type: application/json { "listener": { "default_pool_id": null, "protocol": "HTTP", "description": "", "admin_state_up": true, "loadbalancers": [ { "id": "a9729389-6147-41a3-ab22-a24aed8692b2" } ], "tenant_id": "3e4d8bec50a845fcb09e03a4375c691d", "connection_limit": 100, "protocol_port": 80, "id": "35cb8516-1173-4035-8dae-0dae3453f37f", "name": "" } }
Create a Listener
Verb | URI |
POST | /lbaas/listeners |
Normal Response Code(s): 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:
#!highlight javascript numbers=disable POST /lbaas/listeners Host: lbaas-service.cloudX.com:8651 Content-Type: application/json Accept: application/json X-Auth-Token:887665443383838 { "listener": { "loadbalancer_id": "a36c20d0-18e9-42ce-88fd-82a35977ee8c", "protocol": "HTTP", "protocol_port": "80", "connection_limit": 100, "admin_state_up": true, "name": "listener1", "description": "listener one" } }
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 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
#!wiki caution Note The Listener's ID, tenant_id, loadbalancer_id, loadbalancers, default_pool_id, protocol, and protocol_port are immutable attributes and cannot be updated. Supplying an unsupported attribute will result in a 422 (Immutable) fault.
#!wiki caution Note A Listener cannot be update if the load balancer it is attached to is not in an ACTIVE provisioning_status.
Example . Updating a Listener
JSON Request:
#!highlight javascript numbers=disable PUT /lbaas/listeners/39de4d56-d663-46e5-85a1-5b9d5fa17829 Host: lbaas-service.cloudX.com:8651 Content-Type: application/json Accept: application/json X-Auth-Token:887665443383838 Content-Length: 75 { "listener": { "name": "listener2", "description": "listener two", "admin_state_up": false, "connection_limit": 200 } }
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 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:
#!highlight javascript numbers=disable DELETE /lbaas/listeners/39de4d56-d663-46e5-85a1-5b9d5fa17829 Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 204 No Content
Pools
Use the following APIs to manage Pool resources
Verb | URI |
GET | /lbaas/pools/ |
GET | /lbaas/pools/pool_id |
POST | /lbaas/pools |
PUT | /lbaas/pools/pool_id |
DELETE | /lbaas/pools/pool_id |
List all Pools
Verb | URI |
GET | /lbaas/pools/ |
Normal Response Code(s): 200
Error Response Code(s): 401 (Unauthorized), 500 (Internal server error), 503 (Service Unavailable)
This operation returns the list of all pools associated with your tenant account.
This operation does not require a request body.
This operation returns a response body. It returns a (potentially empty) list, each element in the list is a Pool that can contain the following attributes:
- id
- tenant_id
- name
- description
- protocol
- lb_algorithm
- session_persistence
- admin_state_up
- listeners
- members
- healthmonitor_id
Example . List all Pools
JSON Request:
#!highlight javascript numbers=disable GET /lbaas/pools Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 200 OK Content-Type: application/json { "pools": [ { "lb_algorithm": "ROUND_ROBIN", "protocol": "HTTP", "description": "simple pool", "admin_state_up": true, "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c", "healthmonitor_id": null, "listeners": [ { "id": "35cb8516-1173-4035-8dae-0dae3453f37f" } ], "members": [ ], "id": "4c0a0a5f-cf8f-44b7-b912-957daa8ce5e5", "name": "pool1" } ] }
Retrieve a specific Pool
Verb | URI |
GET | /lbaas/pools/"pool_id |
Normal Response Code(s): 200
Error Response Code(s): 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 413 (Over limit), 500 (Internal server error), 503 (Service Unavailable)
This operation returns a Pool object identified by pool_id. If the user is not an admin, and the Pool object doesn't belong to her tenant account, she would receive a 403 (Forbidden) error.
This operation does not require a request body.
This operation returns a response body. On success, the returned element is a Pool that can contain the following attributes:
- id
- tenant_id
- name
- description
- protocol
- lb_algorithm
- session_persistence
- admin_state_up
- listeners
- members
- healthmonitor_id
Example . Retrieve a Pool's details:
JSON Request:
#!highlight javascript numbers=disable GET /lbaas/pools/35cb8516-1173-4035-8dae-0dae3453f37f Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 200 OK Content-Type: application/json { "pool": { "lb_algorithm": "ROUND_ROBIN", "protocol": "HTTP", "description": "simple pool", "admin_state_up": true, "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c", "healthmonitor_id": null, "listeners": [ { "id": "35cb8516-1173-4035-8dae-0dae3453f37f" } ], "members": [], "id": "4c0a0a5f-cf8f-44b7-b912-957daa8ce5e5", "name": "pool1" } }
Create a Pool
Verb | URI |
POST | /lbaas/pools |
Normal Response Code(s): 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.
- protocol_port: The port in which the frontend will be listening. Must be an integer in the range of 1-65535
- listener_id: The listener in which this pool will become the default pool. There can only be on default pool for a listener.
Some attributes will receive default values if not specified in the request:
- admin_state_up: The default value for this attribute is true.
- name: The default value for this attribute will be an empty string.
- description: The default value for this attribute will be an empty string.
- session_persistence: The default value for this is an empty dictionary.
If the request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 (Bad Request) error response will be returned with information regarding the nature of the failure in the body of the response. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST the request again.
Users may configure all documented features of the Pool at creation time by simply providing the additional elements or attributes in the request.
Users with an admin role can create Pools on behalf of other tenants by specifying a tenant_id attribute different than their own.
A Pool cannot be update if the load balancer it is attempting to be attached to is not in an ACTIVE provisioning_status.
Example . Create a Pool
JSON Request:
#!highlight javascript numbers=disable POST /lbaas/pools Host: lbaas-service.cloudX.com:8651 Content-Type: application/json Accept: application/json X-Auth-Token:887665443383838 { "pool": { "name": "pool1", "description": "simple pool", "listener_id": "39de4d56-d663-46e5-85a1-5b9d5fa17829", "lb_algorithm": "ROUND_ROBIN", "protocol": "HTTP", "session_persistence": { "type": "APP_COOKIE", "cookie_name": "my_cookie" }, "admin_state_up": true } }
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 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
#!wiki caution Note The Pool's ID, tenant_id, listener_id, listeners, healthmonitor_id, protocol, and members are immutable attributes and cannot be updated. Supplying an unsupported attribute will result in a 422 (Immutable) fault.
#!wiki caution Note A Pool cannot be updated if the load balancer it is attached to is not in an ACTIVE provisioning_status.
Example . Updating a Pool
JSON Request:
#!highlight javascript numbers=disable PUT /lbaas/pools/12ff63af-4127-4074-a251-bcb2ecc53ebe Host: lbaas-service.cloudX.com:8651 Content-Type: application/json Accept: application/json X-Auth-Token:887665443383838 Content-Length: 75 { "pool": { "name": "pool2", "description": "pool two", "admin_state_up": false, "lb_algorithm": "LEAST_CONNECTIONS", "session_persistence": {"type": "HTTP_COOKIE"} } }
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 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:
#!highlight javascript numbers=disable DELETE /lbaas/pools/12ff63af-4127-4074-a251-bcb2ecc53ebe Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 204 No Content
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:
#!highlight javascript numbers=disable GET /lbaas/pools/4c0a0a5f-cf8f-44b7-b912-957daa8ce5e5/members Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 200 OK Content-Type: application/json { "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:
#!highlight javascript numbers=disable 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:
#!highlight javascript numbers=disable 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..
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:
#!highlight javascript numbers=disable 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:
#!highlight javascript numbers=disable 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
#!wiki caution 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.
#!wiki caution 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:
#!highlight javascript numbers=disable 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:
#!highlight javascript numbers=disable 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:
#!highlight javascript numbers=disable 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:
#!highlight javascript numbers=disable 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:
#!highlight javascript numbers=disable GET /lbaas/healthmonitors Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 200 OK Content-Type: application/json { "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:
#!highlight javascript numbers=disable GET /lbaas/healthmonitors/35cb8516-1173-4035-8dae-0dae3453f37f Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 200 OK Content-Type: application/json { "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:
#!highlight javascript numbers=disable 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:
#!highlight javascript numbers=disable 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
#!wiki caution 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.
#!wiki caution 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:
#!highlight javascript numbers=disable 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:
#!highlight javascript numbers=disable 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:
#!highlight javascript numbers=disable DELETE /lbaas/healthmonitors/12ff63af-4127-4074-a251-bcb2ecc53ebe Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 204 No Content