Marc Pilon f0bdbb4cd9 [API] Added LB options to docs

Change-Id: Ie92df36802812928849f9bd34100753758449745

2014-03-20 16:22:30 -04:00

24 KiB

Raw Blame History

Load Balancer

Get List Of All Load Balancers

Operation

Resource	Operation	Method	Path
Load Balancer	Get list of all load balancers	GET	{baseURI}/{ver}/loadbalancers

Description

This operation provides a list of all load balancers configured and associated with your account. This includes a summary of attributes for each load balancer. In order to retrieve all the details for a load balancer, an individual request for the load balancer must be made.

This operation returns the following attributes for each load balancer:

id : Unique identifier for the load balancer

name : Creator-assigned name for the load balancer

algorithm : Creator-specified algorithm for the load balancer

protocol : Creator-specified protocol for the load balancer

port : Creator-specified port for the load balancer

status : Current status, see section on load balancer status within load balancer create

created : When the load balancer was created

updated : When the load balancer was last updated

nodeCount : The number of backend servers attached to this load balancer

options : Current options are timeout (30 sec) and retries (3) for each load balancer

Request Data

None required.

Query Parameters Supported

None required.

Required HTTP Header Values

X-Auth-Token

Request Body

None required.

Normal Response Code

HTTP Status Code	Description
200	OK

Response Body

The response body contains a list of load balancers for the tenant making the request.

Error Response Codes

HTTP Status Code	Description
400	Bad Request
401	Unauthorized
404	Not Found
405	Not Allowed
500	LBaaS Fault

Example

Curl Request

curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers

Response

{
    "loadBalancers":[
        {
            "name":"lb-site1",
            "id":"71",
            "protocol":"HTTP",
            "port":"80",
            "algorithm":"LEAST_CONNECTIONS",
            "status":"ACTIVE",
            "created":"2010-11-30T03:23:42Z",
            "updated":"2010-11-30T03:23:44Z",
            "options": {"timeout": 30000, "retries": 3}
        },
        {
            "name":"lb-site2",
            "id":"166",
            "protocol":"TCP",
            "port":"9123",
            "algorithm":"ROUND_ROBIN",
            "status":"ACTIVE",
            "created":"2010-11-30T03:23:42Z",
            "updated":"2010-11-30T03:23:44Z",
            "options": {"timeout": 30000, "retries": 3}
        }
        ]
}

Get Load Balancer Details

Operation

Resource	Operation	Method	Path
Load Balancer	Get a specific load balancer	GET	{baseURI}/{ver}/loadbalancers/{loadbalancerId}

Description

This operation provides detailed description for a specific load balancer configured and associated with your account. This operation is not capable of returning details for a load balancer which has been deleted. Details include load balancer virtual IP and node information.

Request Data

None required.

Query Parameters Supported

None required.

Required HTTP Header Values

X-Auth-Token

Request Body

None required.

Normal Response Code

HTTP Status Code	Description
200	OK

Response Body

The response body contains the load balancer requested or 404, if not found.

Error Response Codes

HTTP Status Code	Description
400	Bad Request
401	Unauthorized
404	Not Found
405	Not Allowed
500	LBaaS Fault

Example

Curl Request

curl -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/2000

Response

{
        "id": "2000",
        "name":"sample-loadbalancer",
        "protocol":"HTTP",
        "port": "80",
        "algorithm":"ROUND_ROBIN",
        "status":"ACTIVE",
        "created":"2010-11-30T03:23:42Z",
        "updated":"2010-11-30T03:23:44Z",
        "options": {"timeout": 30000, "retries": 3},
        "virtualIps":[
                    {
                        "id": "1000",
                        "address":"192.168.1.1",
                        "type":"PUBLIC",
                        "ipVersion":"IPV4"
                    }
             ],
        "nodes":     [
                  {
                        "id": "1041",
                        "address":"10.1.1.1",
                        "port": "80",
                        "condition":"ENABLED",
                        "status":"ONLINE"
                   },
                   {
                        "id": "1411",
                        "address":"10.1.1.2",
                        "port": "80",
                        "condition":"ENABLED",
                        "status":"ONLINE"
                   }
              ],
}

Create a New Load Balancer

Operation

Resource	Operation	Method	Path
Load Balancer	Create a new load balancer	POST	{baseURI}/{ver}/loadbalancers

Description

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 status of the request.

If the status returned is set to 'BUILD', then using the identifier of the load balancer, the caller can check on the progress of the creation operation by performing a GET on loadbalancers/{loadbalancerId}. When the status of the load balancer returned changes to 'ACTIVE', then the load balancer has been successfully provisioned and is now operational.

Load Balancer Status Values

Status Name	Description
BUILD	Load balancer is in a building state and not yet operational
ACTIVE	Load balancer is in an operational state
PENDING_UPDATE	Load balancer is in the process of an update
ERROR	Load balancer is in an error state and not operational

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

*name

*at least one node

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.

By default, the system will create a load balancer with protocol set to HTTP, port set to 80 (or 443 if protocol is TCP), and assign a public IPV4 address to the load balancer. There is also a third special-case protocol "GALERA" that can be used to choose a primary write node when the load balancer is being used to deliver data to a Galera database cluster. The default load balancing algorithm used is set to ROUND_ROBIN.

The load balancer options consist of a 30 second timeout for client connections (30,000ms) and 3 retries. Valid timeout values range from 0 to 1000 seconds (1,000,000 ms) with 0 indicating no timeout. retries can range from 0 to 256.

A load balancer name has a max length that can be determined by querying limits.

Users may configure all documented features of the load balancer at creation time by simply providing the additional elements or attributes in the request. This document provides an overview of all the features the load balancing service supports.

If you have at least one load balancer, you may create subsequent load balancers that share a single virtual IP by issuing a POST and supplying a virtual IP ID instead of a type. Additionally, this feature is highly desirable if you wish to load balance both an unsecured and secure protocol using one IP address. For example, this method makes it possible to use the same load balancing configuration to support an HTTP and an TCP load balancer. Load balancers sharing a virtual IP must utilize a unique port.

Relevant weights can be assigned to nodes using the weight attribute of the node element. The weight of a node determines the portion of requests or connections it services compared to the other nodes of the load balancer. For example, if node A has a weight of 2 and node B has a weight of 1, then the loadbalancer will forward twice as many requests to node A than to node B. If the weight attribute is not specified, then the node's weight is implicitly set to "1". Weight values from 1 to 256 are allowed.

Note that nodes that are assigned to a load balancer that is delivering data to a Galera database cluster may require a primary write node be specified to avoid database locking problems that can occur. For this case, a load balancer can be configured to use the special "GALERA" protocol type. When a "GALERA" protocol is chosen, all of the specified nodes must use the node "backup" attribute to specify whether it is a backup node or the primary node. There may only be a single primary node specified by setting the "backup" attribute to FALSE. All other nodes must have the "backup" attribute set to TRUE.

Request Data

The caller is required to provide a request data with the POST which includes the appropriate information to create a new load balancer.

Query Parameters Supported

None required.

Required HTTP Header Values

X-Auth-Token
Accept: application/json
Content-Type: application/json

Request Body

The request body must follow the correct format for new load balancer creation, examples....

Request body example to create a load balancer with two nodes and an optional "weight" assigned. Note that a default weight of 1 does not have to be explicitly assigned

{
        "name": "a-new-loadbalancer",
        "nodes":      [
                    {
                        "address": "10.1.1.1",
                        "port": "80"
                        "weight": "2"
                    },
                    {
                        "address": "10.1.1.2",
                        "port": "81"
                    }
            ]
}

Request body example to create a load balancer using existing load balancer virtual IP

{
    "name":"a-new-loadbalancer",
    "port":"80",
    "protocol":"HTTP",
    "options": {"timeout": 30000, "retries": 3},
    "virtualIps": [
               {
                  "id":"39"
               }
             ],
    "nodes":      [
               {
                  "address":"10.1.1.1",
                  "port":"80",
                  "condition":"ENABLED"
               }
             ]
}

Request body example to create a load balancer that specifies a single primary write node for a Galera cluster

{
    "name":"a-new-loadbalancer",
    "port":"83",
    "protocol":"GALERA",
    "options": {"timeout": 30000, "retries": 3},
    "virtualIps": [
               {
                  "id":"39"
               }
             ],
    "nodes":  [
                {
                    "address": "10.1.1.1",
                    "port": "3306",
                    "backup": "TRUE"
                },
                {
                    "address": "10.1.1.2",
                    "port": "3306",
                    "backup": "FALSE"
                }
            ]
}

Normal Response Code

HTTP Status Code	Description
202	Accepted

Response Body

The response body contains the load balancer requested or appropriate error.

Create Load Balancer (Required Attributes with Shared IP) Response: JSON

{
        "name": "a-new-loadbalancer",
        "id": "144",
        "protocol": "HTTP",
        "port": "83",
        "algorithm": "ROUND_ROBIN",
        "status": "BUILD",
        "created": "2011-04-13T14:18:07Z",
        "updated":"2011-04-13T14:18:07Z",
        "options": {"timeout": 30000, "retries": 3},
        "virtualIps": [
                {
                    "address": "3ffe:1900:4545:3:200:f8ff:fe21:67cf",
                    "id": "39",
                    "type": "PUBLIC",
                    "ipVersion": "IPV6"
                }
              ],
        "nodes":      [
                {
                    "address": "10.1.1.1",
                    "id": "653",
                    "port": "80",
                    "status": "ONLINE",
                    "condition": "ENABLED"
                }
              ]
}

Error Response Codes

HTTP Status Code	Description
400	Bad Request
401	Unauthorized
404	Not Found
405	Not Allowed
413	Over Limit
500	LBaaS Fault
503	Service Unavailable

Example

Contents of Request file lb.json

{
    "name": "lb #1",
    "protocol":"tcp",
        "nodes":      [
                {
                    "address": "15.185.229.153",
                    "port": "443"
                },
               {
                    "address": "15.185.226.163",
                    "port": "443"
                },
               ],
}

Curl Request

curl -X POST -H "X-Auth-Token: TOKEN" --data-binary "@lb.json" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers

Response

{
    "port":"443",
    "id":"10",
    "protocol":"tcp",
    "updated":"2013-02-10T18:20Z",
    "created":"2013-02-10T18:20Z",
    "status":"BUILD",
    "nodes":[
        {
            "port":"443",
            "id":"19",
            "condition":"ENABLED",
            "status":"ONLINE",
            "address":"15.185.229.153"
        },
        {
            "port":"443",
            "id":"20",
            "condition":"ENABLED",
            "status":"ONLINE",
            "address":"15.185.226.163"
        }
    ],
    "name":"lb #1",
    "virtualIps":[
        {
            "id":"5",
            "address":"15.185.96.125",
            "ipVersion":"IPV_4",
            "type":"PUBLIC"
        }
    ],
    "algorithm":"ROUND_ROBIN",
    "options": {"timeout": 30000, "retries": 3},
}

Update an Existing Load Balancer

Operation

Resource	Operation	Method	Path
Load Balancer	Update load balancer attributes	PUT	{baseURI}/{ver}/loadbalancers/{loadbalancerId}

Description

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 status is ACTIVE to confirm that the update has taken effect. If the load balancer status is 'PENDING_UPDATE' then the caller can poll the load balancer with its ID (using a GET operation) to wait for the changes to be applied and the load balancer to return to an ACTIVE status.

This operation allows the caller to change one or more of the following attributes:

*name

*algorithm

*options

This operation does not return a response body.

Note

The load balancer ID, status, port and protocol are immutable attributes and cannot be modified by the caller. Supplying an unsupported attribute will result in a 400 (badRequest) fault.

Request Data

Load balancer body with attributes to be updated.

Query Parameters Supported

None required.

Required HTTP Header Values

X-Auth-Token

Request Body

Example

{
    "name": "newname-loadbalancer",
    "algorithm": "LEAST_CONNECTIONS",
    "options": {"timeout": 30000, "retries": 3}
}

Normal Response Code

HTTP Status Code	Description
202	Accepted

Response Body

None.

Error Response Codes

HTTP Status Code	Description
400	Bad Request
401	Unauthorized
404	Not Found
405	Not Allowed
500	LBaaS Fault

Example

Contents of Request file lb.json

{
    "name": "newname-loadbalancer",
    "algorithm": "LEAST_CONNECTIONS",
    "options": {"timeout": 30000, "retries": 3}
}

Curl Request

curl -X PUT -H "X-Auth-Token: TOKEN" --data-binary "@lb.json" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100

Response

status with no response body.

Delete Load Balancer

Operation

Resource	Operation	Method	Path
Load Balancer	Delete an existing load balancer	DELETE	{baseURI}/{ver}/loadbalancers/{loadbalancerId}

Description

Delete load balancer removes the specified load balancer and its associated configuration from the account. Any and all configuration data is immediately purged and is not recoverable.

This operation does not require a request body.

Request Data

None required.

Query Parameters Supported

None required.

Required HTTP Header Values

X-Auth-Token

Request Body

None required.

Normal Response Code

HTTP Status Code	Description
202	Accepted

Response Body

None.

Error Response Codes

HTTP Status Code	Description
400	Bad Request
401	Unauthorized
404	Not Found
405	Not Allowed
500	LBaaS Fault

Example

Curl Example

curl -X DELETE -H "X-Auth-Token: TOKEN" https://uswest.region-b.geo-1.lbaas.hpcloudsvc.com/v1.1/loadbalancers/100

Response

status with no response body.

24 KiB Raw Blame History

Load Balancer

Get List Of All Load Balancers

Operation

Description

Request Data

Query Parameters Supported

Required HTTP Header Values

Request Body

Normal Response Code

Response Body

Error Response Codes

Example

Get Load Balancer Details

Operation

Description

Request Data

Query Parameters Supported

Required HTTP Header Values

Request Body

Normal Response Code

Response Body

Error Response Codes

Example

Create a New Load Balancer

Operation

Description

Request Data

Query Parameters Supported

Required HTTP Header Values

Request Body

Normal Response Code

Response Body

Error Response Codes

Example

Update an Existing Load Balancer

Operation

Description

Request Data

Query Parameters Supported

Required HTTP Header Values

Request Body

Normal Response Code

Response Body

Error Response Codes

Example

Delete Load Balancer

Operation

Description

Request Data

Query Parameters Supported

Required HTTP Header Values

Request Body

Normal Response Code

Response Body

Error Response Codes

Example

24 KiB

Raw Blame History