Difference between revisions of "Neutron/LBaaS/API 2.0"
(→Load Balancers) |
(→List all Load Balancers) |
||
Line 41: | Line 41: | ||
This operation does not require a request body. | 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 | + | 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 | * id |
Revision as of 00:30, 2 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 |
List all Load Balancers
Verb | URI |
GET | /lbaas/loadbalancers/ |
Normal Response Code(s): 200
Error Response Code(s): 401 (Unauthorized), 500 (Internal server error), 503 (Service Unavailable)
This operation returns the list of all load balancers associated with your tenant account.
This operation does not require a request body.
This operation returns a response body. It returns a (potentially empty) list, each element in the list is a Load Balancer that can contain the following attributes:
- id
- tenant_id
- name
- description
- vip_subnet_id
- vip_address
- admin_state_up
- listeners
- provisioning_status
- operating_status
Example . List all Load Balancers
JSON Request:
#!highlight javascript numbers=disable GET /lbaas/loadbalancers Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 200 OK Content-Type: application/json { "loadbalancers": [ { "description": "simple lb", "admin_state_up": true, "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c", "provisioning_status": "ACTIVE", "listeners": [ ], "vip_address": "10.0.0.2", "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2", "id": "a9729389-6147-41a3-ab22-a24aed8692b2", "operating_status": "ONLINE", "name": "loadbalancer1" } ] }
Retrieve a specific Load Balancer
Verb | URI |
GET | /lbaas/loadbalancers/"loadbalancer_id |
Normal Response Code(s): 200
Error Response Code(s): 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 413 (Over limit), 500 (Internal server error), 503 (Service Unavailable)
This operation returns a Load Balancer object identified by loadbalancer_id. If the user is not an admin, and the Load Balancer object doesn't belong to her tenant account, she would receive a 403 (Forbidden) error.
This operation does not require a request body.
This operation returns a response body. On success, the returned element is a Load Balancer that can contain the following attributes:
- id
- tenant_id
- name
- description
- vip_subnet_id
- vip_address
- admin_state_up
- listeners
- provisioning_status
- operating_status
Example . Retrieve a Load Balancer's details:
JSON Request:
#!highlight javascript numbers=disable GET /lbaas/loadbalancers/36e08a3e-a78f-4b40-a229-1e7e23eee1ab Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 200 OK Content-Type: application/json { "loadbalancer": { "description": "simple lb", "admin_state_up": true, "tenant_id": "1a3e005cf9ce40308c900bcb08e5320c", "provisioning_status": "ACTIVE", "listeners": [ ], "vip_address": "10.0.0.2", "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2", "id": "a9729389-6147-41a3-ab22-a24aed8692b2", "operating_status": "ONLINE", "name": "loadbalancer1" } }
Create a Load Balancer
Verb | URI |
POST | /lbaas/loadbalancers |
Normal Response Code(s): 202
Error Response Code(s): 401 (Unauthorized), 404 (Not Found), 409 (Conflict), 413 (Over limit), 500 (Internal server error), 503 (Service Unavailable)
This operation provisions a new Load Balancer based on the configuration defined in the request object. Once the request is validated and progress has started on the provisioning process, a response object will be returned. The object will contain a unique identifier and the status of provisioning the Load Balancer.
The provisioning_status of the Load Balancer in the response can take one of the following values: ACTIVE, PENDING_CREATE or ERROR.
If the status returned is set to "PENDING_CREATE", then using the identifier of the Load Balancer, the caller can check on the progress of the provisioning operation by performing a GET on /lbaas/loadbalancers/loadbalancer_id. When the status of the load balancer returned changes to "ACTIVE", then the VIP has been successfully provisioned and is now operational for traffic handling.
The caller of this operation must specify at least the following attributes of the Load Balancer:
- tenant_id: only required if the caller has an admin role and wants to create a VIP for another tenant.
- vip_subnet_id: The network on which to allocate the load balancer's vip address. A tenant can only create load balancer vips on networks authorized by policy (e.g. her own networks or shared/provider networks).
Some attributes will receive default values if not specified in the request:
- admin_state_up: The default value for this attribute is true.
- name: The default value for this attribute will be an empty string.
- description: The default value for this attribute will be an empty string.
If the request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 (Bad Request) error response will be returned with information regarding the nature of the failure in the body of the response. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST the request again.
Users may configure all documented features of the Load Balancer at creation time by simply providing the additional elements or attributes in the request.
Users with an admin role can create Load Balancers on behalf of other tenants by specifying a tenant_id attribute different than their own.
Example . Create a Load Balancer
JSON Request:
#!highlight javascript numbers=disable POST /lbaas/loadbalancers Host: lbaas-service.cloudX.com:8651 Content-Type: application/json Accept: application/json X-Auth-Token:887665443383838 { "loadbalancer": { "name": "loadbalancer1", "description": "simple lb", "tenant_id": "b7c1a69e88bf4b21a8148f787aef2081", "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2", "vip_address": "10.0.0.4", "admin_state_up": true } }
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 202 Accepted Content-Type: application/json Content-Length: 213 { "loadbalancer": { "description": "simple lb", "admin_state_up": true, "tenant_id": "b7c1a69e88bf4b21a8148f787aef2081", "provisioning_status": "ACTIVE", "listeners": [], "vip_address": "10.0.0.4", "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2", "id": "a36c20d0-18e9-42ce-88fd-82a35977ee8c", "operating_status": "ONLINE", "name": "loadbalancer1" } }
A user can supply a vip_address field if she owns the subnet on which the Load Balancer's VIP will be created. If a vip_address is not specified in the payload, then the LBaaS service will allocate one from the Load Balancer VIP's subnet.
Update a Load Balancer
Verb | URI |
PUT | /lbaas/loadbalancers/loadbalancer_id |
Normal Response Code(s): 202
Error Response Code(s): serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
This operation updates the attributes of the specified Load Balancer. Upon successful validation of the request, the service will return a 202 (Accepted) response code. A caller should check that the Load Balancer provisioning_status has changed to ACTIVE to confirm that the update has taken effect. If the Load Balancer provisioning_status is "PENDING_UPDATE" then the caller can poll the Load Balancer object (using a GET operation) to wait for the changes to be applied.
The update operation allows the caller to change one or more of the following Load Balancer attributes:
- name
- description
- admin_state_up
This operation returns the updated Load Balancer object. The provisioning_status of the Load Balancer in the response can take one of the following values: ACTIVE, PENDING_UPDATE or ERROR.
#!wiki caution Note The Load Balancer's ID, provisioning_status, operating_status, vip_subnet_id, vip_address, and listeners are immutable attributes and cannot be updated. Supplying an unsupported attribute will result in a 422 (Immutable) fault.
#!wiki caution Note A Load Balancer that is does not have a provisioning_status of ACTIVE cannot be updated.
Example . Updating a Load Balancer
JSON Request:
#!highlight javascript numbers=disable PUT /lbaas/loadbalancers/a36c20d0-18e9-42ce-88fd-82a35977ee8c Host: lbaas-service.cloudX.com:8651 Content-Type: application/json Accept: application/json X-Auth-Token:887665443383838 Content-Length: 75 { "loadbalancer": { "name": "loadbalancer2", "description": "simple lb2", "admin_state_up": false } }
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 202 Accepted Content-Type: application/json Content-Length: 282 { "loadbalancer": { "description": "simple lb2", "admin_state_up": false, "tenant_id": "b7c1a69e88bf4b21a8148f787aef2081", "provisioning_status": "PENDING_UPDATE", "listeners": [], "vip_address": "10.0.0.4", "vip_subnet_id": "013d3059-87a4-45a5-91e9-d721068ae0b2", "id": "a36c20d0-18e9-42ce-88fd-82a35977ee8c", "operating_status": "ONLINE", "name": "loadbalancer2" } }
Remove a Load Balancer
Verb | URI | |
DELETE | /lbaas/loadbalancers/loadbalancer_id | Remove a Load Balancer from the account. |
Normal Response Code(s): 204
Error Response Code(s): serviceFault (500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)
This operation removes the specified Load Balancer and its associated configuration from the tenant account. Any and all configuration data is immediately purged and is not recoverable.
This operation does not require a request body.
This operation does not return a response body.
Example. Deleting a Load Balancer
JSON Request:
#!highlight javascript numbers=disable DELETE /lbaas/loadbalancers/a36c20d0-18e9-42ce-88fd-82a35977ee8c Host: lbaas-service.cloudX.com:8651 Accept: application/json X-Auth-Token:887665443383838
JSON Response:
#!highlight javascript numbers=disable HTTP/1.1 204 No Content