Load balancers

Users can 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.

Any protocol that is not listed in the protocols response, or is in the list but port=0, requires port to be set. For example the TCP protocol is in the list, however it specifies port as 0 (<protocol name="TCP" port="0" />), therefore it requires port to be set.

You must specify the type of virtualIp to add along with the creation of a load balancer. The following table describes the options.

Table. Virtual IP types

Version

Type

Outcome

Not Specified

PUBLIC

IPV4 & IPV6

IPV4

PUBLIC

IPV4

IPV6

PUBLIC

IPV6

Not Specified

SERVICENET

IPV4

IPV4

SERVICENET

IPV4

IPV6

SERVICENET

Failure Message

Notice in the following examples that API users are now able to programmatically derive the source IP addresses of our load balancers using the sourceAddresses label included at the bottom of the create load balancer (required attributes) response. This feature is useful for customers who are automating the deployment of infrastructure and must determine the IP addresses of requests coming from our load balancers for the purpose of creating more robust firewall rules.

To conserve IPv4 address space, Rackspace highly recommends sharing Virtual IPs between your load balancers. If you have at least one load balancer, you may create subsequent load balancers that share a single virtual IPv4 and/or a single IPv6 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 or DNS name. For example, this methods makes it possible to use the same load balancing configuration to support HTTP and HTTPS.

Note

  • Load balancers sharing a virtual IP must utilize a unique port. Also, to share both an IPv4 as well as an IPv6, you must supply an extra virtualIp object to the virtualIps container with the desired ID being shared.

  • In addition, load balancers sharing Virtual IPs can utilize certain-compatible TCP/UDP and DNS based protocols on the same port. See Compatible shared load balancing protocols for more details.

All load balancers also have a status attribute that shows current configuration status of the device. This status is immutable by the caller and is updated automatically based on state changes within the service. When a load balancer is first created, it is placed into a BUILD status while the configuration is being generated and applied based on the request. Once the configuration is applied and finalized, it is in an ACTIVE status. In the event of a configuration change or update, the status of the load balancer changes to PENDING_UPDATE to signify configuration changes are in progress but are not yet been finalized. Load balancers in a SUSPENDED status are configured to reject traffic and does not forward requests to back-end nodes.

Table. Load balancer statuses

Name

Description

ACTIVE

Load balancer is configured properly and ready to | serve traffic to incoming requests via the configured virtual IPs.

BUILD

Load balancer is being provisioned for the first time and configuration is being applied to bring the service online. The service cannot yet serve incoming requests.

PENDING_UPDATE

Load balancer is online but configuration changes are being applied to update the service based on a previous request.

PENDING_DELETE

Load balancer is online but configuration changes are being applied to begin deletion of the service based on a previous request.

SUSPENDED

Load balancer has been taken offline and disabled; contact Support.

ERROR

The system encountered an error when attempting to configure the load balancer; contact Support.

DELETED

Load balancers in DELETED status can be displayed for at least 90 days after deletion.

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

  • name

  • algorithm

  • protocol

  • halfClosed

  • port

  • timeout

  • httpsRedirect

List load balancers

GET /v1.0/{account}/loadbalancers

Lists load balancers that are configured for the account.

The response object shows a limited set of load balancer attributes, including the following attributes: * name * id * status * created * updated

Use the changes-since query parameter to list all load balancers that have changed since the specified date/time. For example, using the URI /loadbalancers?changes-since=2011-05-19T08:07:08-0500 lists all load balancers that have changed since May 19th, 2011 at 8:07:08 AM, GMT-5. See Date and time format for information about specifying the date/time. To view deleted load balancers, add the query parameter ?status=DELETED to the end of the URI. A deleted load balancer is immutable and irrecoverable. To find out if any load balancer for an account has a specific node attached to it, use the query parameter nodeaddress to specify the IP address or domain name for the desired node. For example, using the URI /loadbalancers?nodeaddress=10.1.1.1 searches all load balancers for the account for a node with IP address 10.1.1.1, and returns a list including the ID, name, and status of all load balancers attached. The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

413

Over Limit

The number of items returned is above the allowed limit.

422

ImmutableEntity

This fault is returned when a user attempts to modify an item that is not currently in a state that allows modification. For example, load balancers in a status of PENDING_UPDATE,BUILD, or DELETED may not be modified.

500

Load Balancer Fault

The load balancer has experienced a fault.

503

Service Unavailable

The service is not available.

Request

The following table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The ID for the tenant or account in a multi- tenancy cloud.

This operation does not accept a request body.

Response

The following table shows the body parameters for the response:

Name

Type

Description

loadBalancers

String

A loadBalancers object.

name

String

Name of the load balancer to create. The name must be 128 characters or fewer in length, and all UTF-8 characters are valid. See http://www.utf8-chartable.de/ for information about the UTF-8 character set.

id

Int

The ID for the load balancer.

protocol

String

Protocol of the service that is being load balanced.

port

String

Port number for the service you are load balancing.

algorithm

String

Algorithm that defines how traffic should be directed between back- end nodes.

status

String

The status of the load balancer.

nodeCount

Int

The number of load balancer nodes.

created

Object

The date and time what the load balancer was created.

updated

Object

The date and time what the load balancer was last updated.

virtualIps

Object

The list of virtualIps for a load balancer.

id

Int

The ID for the IP address.

address

String

The IP address.

type

String

The IP address type. See the Virtual IP Types table in the Chapter 4 section “Virtual IPs”.

ipVersion

String

The IP version.

Example List load balancers: JSON response

{
    "loadBalancers":[
        {
            "name":"lb-site1",
            "id":71,
            "protocol":"HTTP",
            "port":80,
            "algorithm":"RANDOM",
            "status":"ACTIVE",
            "nodeCount":3,
            "timeout": 30,
            "virtualIps":[
                {
                    "id":403,
                    "address":"206.55.130.1",
                    "type":"PUBLIC",
                    "ipVersion":"IPV4"
                }
            ],
            "created":{
                "time":"2010-11-30T03:23:42Z"
            },
            "updated":{
                "time":"2010-11-30T03:23:44Z"
            }
        },
        {
            "name":"lb-site2",
            "id":166,
            "protocol":"HTTP",
            "port":80,
            "algorithm":"RANDOM",
            "status":"ACTIVE",
            "nodeCount":4,
            "virtualIps":[
                {
                    "id":401,
                    "address":"206.55.130.2",
                    "type":"PUBLIC",
                    "ipVersion":"IPV4"
                }
            ],
            "created":{
                "time":"2010-11-30T03:23:42Z"
            },
            "updated":{
                "time":"2010-11-30T03:23:44Z"
            }
        }
    ]
}

Example List load balancers: XML response

<loadBalancers xmlns="http://docs.openstack.org/loadbalancers/api/v1.0">
    <loadBalancer id="71" name="lb-site1" status="ACTIVE" protocol="HTTP" port="80" algorithm="RANDOM" timeout="30" nodeCount="3">
        <virtualIps>
            <virtualIp id="403" address="206.55.130.1" ipVersion="IPV4"
                type="PUBLIC" />
        </virtualIps>
        <created time="2010-12-13T15:38:27-06:00" />
        <updated time="2010-12-13T15:38:38-06:00" />
    </loadBalancer>
    <loadBalancer id="166" name="lb-site2" status="ACTIVE" protocol="HTTP" port="80" algorithm="RANDOM" timeout="30" nodeCount="4">
        <virtualIps>
            <virtualIp id="401" address="206.55.130.2" ipVersion="IPV4"
                type="PUBLIC" />
        </virtualIps>
        <created time="2010-12-13T15:38:27-06:00" />
        <updated time="2010-12-13T15:38:38-06:00" />
    </loadBalancer>
</loadBalancers>

Example List load balancers: Atom response

<feed xmlns="http://www.w3.org/2005/Atom">
    <link rel="next"
          href="https://ord.loadbalancers.api.rackspacecloud.com/v1.0/1234/loadbalancers.atom?page=2"/>
    <title type="text">Parent Feed</title>
    <id>1234-loadbalancers</id>
    <author>
        <name>Rackspace Cloud</name>
    </author>
    <entry>
        <title type="text">Access List Updated</title>
        <summary
                type="text">Access list successfully updated with the following network item: id: '2155', address: '206.160.163.210', type: 'DENY'
        </summary>
        <author>
            <name>tvardema</name>
        </author>
        <link href="https://ord.loadbalancers.api.rackspacecloud.com/v1.0/1234/loadbalancers/141/accesslist/"/>
        <id>1234-loadbalancers-141-accesslist-2011971658310</id>
        <category term="UPDATE"/>
        <updated>2011-04-07T16:58:31.000Z</updated>
    </entry>
</feed>

Create load balancer

POST /v1.0/{account}/loadbalancers

Creates a load balancer with the configuration defined by the request.

This operation asynchronously 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 is returned. The object contains a unique ID and status of the request. Using the ID, the caller can check on the progress of the operation by performing a GET on loadbalancers/id. If the corresponding request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 (Bad Request) error response is 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. An HTTP load balancer has the X-Forwarded-For (XFF) HTTP header set by default. This header contains the actual originating IP address of a client connecting to a web server through an HTTP proxy or load balancer, which many web applications are already designed to use when determining the source address for a request. (This header is also included on the Modify Load Balancer request if the protocol changes to re-enable it.) An HTTP load balancer also includes the X-Forwarded-Proto (XFP) HTTP header, which has been added for identifying the originating protocol of an HTTP request as “http” or “https” depending on what protocol the client requested. This is specially useful when using SSL termination. An HTTP load balancer also includes the X-Forwarded-Port HTTP header, which has been added for being able to generate secure URLs containing the specified port. This header, along with the X-Forwarded-For header, provide the needed information to the underlying application servers.

Note

The headers listed here (X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Port) are available for HTTP load balancers with or without SSL termination enabled, however HTTPS load balancers do not provide these header elements due to encryption.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

202

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

413

Over Limit

The number of items returned is above the allowed limit.

422

ImmutableEntity

This fault is returned when a user attempts to modify an item that is not currently in a state that allows modification. For example, load balancers in a status of PENDING_UPDATE,BUILD, or DELETED may not be modified.

500

Load Balancer Fault

The load balancer has experienced a fault.

503

Service Unavailable

The service is not available.

Request

The following table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The ID for the tenant or account in a multi- tenancy cloud.

The following table shows the body parameters for the request:

Name

Type

Description

name

String (Required)

Name of the load balancer to create. The name must be 128 characters or fewer in length, and all UTF-8 characters are valid. See http://www.utf8-chartable.de/ for information about the UTF-8 character set.

nodes

Object

Nodes to be added to the load balancer.

protocol

String (Required)

Protocol of the service that is being load balanced.

halfClosed

Boolean

Enables or disables Half-Closed support for the load balancer. Half- Closed support provides the ability for one end of the connection to terminate its output, while still receiving data from the other end. Only available for TCP/TCP_CLIENT_FIRST protocols.

virtualIps

Object (Required)

Type of virtualIp to add with the creation of a load balancer. See the virtual IP types table at Virtual IPs.

accessList

String

The access list management feature allows fine-grained network access controls to be applied to the load balancer virtual IP address. Refer to Access lists for information and examples.

algorithm

String

Algorithm that defines how traffic should be directed between back-end nodes.

connectionLogging

String

Current connection logging configuration. Refer to Log connections for information and examples.

connectionThrottle

String

Specifies limits on the number of connections per IP address to help mitigate malicious or abusive traffic to your applications. See Throttle connections for information and examples.

healthMonitor

String

The type of health monitor check to perform to ensure that the service is performing properly.

metadata

String

Information (metadata) that can be associated with each load balancer.

port

String

Port number for the service you are load balancing.

timeout

String

The timeout value for the load balancer and communications with its nodes. Defaults to 30 seconds with a maximum of 120 seconds.

sessionPersistence

String

Specifies whether multiple requests from clients are directed to the same node.

httpsRedirect

Boolean

Enables or disables HTTP to HTTPS redirection for the load balancer. When enabled, any HTTP request returns status code 301 (Moved Permanently), and the requester is redirected to the requested URL via the HTTPS protocol on port 443. For example, http://example.com/page.html would be redirected to https://example.com/page.html. Only available for HTTPS protocol ( port=443 ), or HTTP protocol with a properly configured SSL termination ( secureTrafficOnly=true, securePort=443 ). Note that SSL termination for a load balancer can only be configured after the load balancer has been created.

Example Create load balancer: JSON request

{
    "loadBalancer": {
        "name": "a-new-loadbalancer",
        "port": 80,
        "protocol": "HTTP",
        "virtualIps": [
            {
                "type": "PUBLIC"
            }
        ],
        "nodes": [
            {
                "address": "10.1.1.1",
                "port": 80,
                "condition": "ENABLED"
            }
        ]
    }
}

Example Create load balancer: XML request

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0"
    name="a-new-loadbalancer"
    port="80"
    protocol="HTTP">
    <virtualIps>
        <virtualIp type="PUBLIC"/>
    </virtualIps>
    <nodes>
        <node address="10.1.1.1" port="80" condition="ENABLED"/>
    </nodes>
</loadBalancer>

Example Create load balancer with shared IP: JSON request

{
    "loadBalancer":{
        "name":"a-new-loadbalancer",
        "port":80,
        "protocol":"HTTP",
        "virtualIps":[
            {
                "id":15
            }
        ],
        "nodes":[
            {
                "address":"10.1.1.1",
                "port":80,
                "condition":"ENABLED"
            }
        ]
    }
}

Example Create load balancer with shared IP: XML request

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0"
    name="a-new-loadbalancer"
    port="80"
    protocol="HTTP">
    <virtualIps>
        <virtualIp id="15"/>
    </virtualIps>
    <nodes>
        <node address="10.1.1.1" port="80" condition="ENABLED" />
    </nodes>
</loadBalancer>

Example Create load balancer with Shared IPv4/IPv6: JSON request

{
    "loadBalancer":{
        "name":"a-new-loadbalancer",
        "port":80,
        "protocol":"HTTP",
        "virtualIps":[
            {
                "id":15
            },
            {
                "id":9000137
            }
        ],
        "nodes":[
            {
                "address":"10.1.1.1",
                "port":80,
                "condition":"ENABLED"
            }
        ]
    }
}

Example Create load balancer with Shared IPv4/IPv6: XML request

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0"
    name="a-new-loadbalancer"
    port="80"
    protocol="HTTP">
    <virtualIps>
        <virtualIp id="15"/>
        <virtualIp id="9000137"/>
    </virtualIps>
    <nodes>
        <node address="10.1.1.1" port="80" condition="ENABLED" />
    </nodes>
</loadBalancer>

Response

The following table shows the body parameters for the response:

Name

Type

Description

loadBalancer

String

A loadBalancer object.

id

Int

The ID for the load balancer.

protocol

String

Protocol of the service that is being load balanced.

port

String

Port number for the service you are load balancing.

algorithm

String

Algorithm that defines how traffic should be directed between back- end nodes.

status

String

The status of the load balancer.

timeout

String

The timeout value for the load balancer and communications with its nodes. Defaults to 30 seconds with a maximum of 120 seconds.

connectionLogging

String

Current connection logging configuration. Refer to the API Ops section “Log Connections” for information and examples.

virtualIps

Object

Type of virtualIp to add with the creation of a load balancer. See the virtual IP types table in the API Operations section “Virtual IPs”.

id

Int

The ID for the IP address.

address

String

The IP address.

type

String

The IP address type.

ipVersion

String

The IP version.

nodes

Object

Nodes to be added to the load balancer.

address

String

The node address.

port

Int

The node port.

condition

String

The node condition. For example, ENABLED.

status

String

The node status. For example, ONLINE.

sessionPersistence

String

Specifies whether multiple requests from clients are directed to the same node.

connectionThrottle

String

Specifies limits on the number of connections per IP address to help mitigate malicious or abusive traffic to your applications. See Throttle connections for information and examples.

cluster

String

The cluster name.

created

Object

The date and time what the load balancer was created.

updated

Object

The date and time what the load balancer was last updated.

sourceAddresses

Dict

The source public and private IP addresses.

Example Create load balancer: JSON response

{
    "loadBalancer":{
        "name":"a-new-loadbalancer",
        "id":2200,
        "port":80,
        "protocol":"HTTP",
        "halfClosed":"false",
        "algorithm":"RANDOM",
        "status":"BUILD",
        "timeout": 30,
        "cluster":{
            "name":"host2_cluster1"
        },
        "nodes":[{
                "address":"10.1.1.1",
                "id":2208,
                "port":80,
                "status":"ONLINE",
                "condition":"ENABLED",
                "weight":1,
                "type": "PRIMARY",
            }
        ],
        "virtualIps":[{
                "address":"10.0.0.18",
                "id":15,
                "type":"PUBLIC",
                "ipVersion":"IPV4"
            },
            {
                "address":"fd24:f480:ce44:91bc:1af2:15ff:0000:0005",
                "id":9000137,
                "type":"PUBLIC",
                "ipVersion":"IPV6"
            }
        ],
        "created": {
            "time": "2011-04-13T14:18:07Z"
        },
        "sourceAddresses":{
            "ipv6Public":"2001:4801:79f1:1::3/64",
            "ipv4Servicenet":"10.0.0.0",
            "ipv4Public":"10.12.99.28"
        },
        "httpsRedirect": false,
        "connectionLogging":{
            "enabled":false
        },
        "contentCaching": {
            "enabled": false
        }
    }
}

Example Create load balancer: XML response

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0" id="2198" name="a-new-loadbalancer"
              algorithm="RANDOM" protocol="HTTP" httpsRedirect="false"
              halfClosed="false" port="80" status="BUILD" timeout="30">
    <virtualIps>
        <virtualIp id="15" address="10.0.0.18" ipVersion="IPV4" type="PUBLIC"/>
        <virtualIp id="9000137" address="fd24:f480:ce44:91bc:1af2:15ff:0000:0005" ipVersion="IPV6" type="PUBLIC"/>
    </virtualIps>
    <nodes>
        <node id="2206" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" weight="1" type="PRIMARY"/>
    </nodes>
    <cluster name="host2_cluster1"/>
    <created time="2011-06-01T08:08:41-05:00"/>
    <updated time="2011-06-01T08:08:41-05:00"/>
    <connectionLogging enabled="false"/>
    <contentCaching enabled="false"/>
    <sourceAddresses ipv4Servicenet="10.0.0.0" ipv4Public="10.12.99.29" ipv6Public="2001:4801:79f1:1::3/64"/>
</loadBalancer>

Example Create load balancer with shared IP: JSON response

{
    "loadBalancer": {
        "name": "a-new-loadbalancer",
        "id": 144,
        "protocol": "HTTP",
        "halfClosed": "true",
        "port": 83,
        "algorithm": "RANDOM",
        "status": "BUILD",
        "timeout": 30,
        "cluster": {
            "name": "ztm-n01.staging1.lbaas.rackspace.net"
        },
        "nodes": [
            {
                "address": "10.1.1.1",
                "id": 653,
                "port": 80,
                "status": "ONLINE",
                "condition": "ENABLED",
                "weight": 1,
                "type": "PRIMARY"
            }
        ],
        "virtualIps": [
            {
                "address": "10.0.0.18",
                "id": 15,
                "type": "PUBLIC",
                "ipVersion": "IPV4"
            }
        ],
        "created": {
            "time": "2011-04-13T14:18:07Z"
        },
        "sourceAddresses":{
            "ipv6Public":"2001:4801:79f1:1::3/64",
            "ipv4Servicenet":"10.0.0.0",
            "ipv4Public":"10.12.99.28"
        },
        "httpsRedirect": false,
        "connectionLogging": {
            "enabled": false
        },
        "contentCaching": {
            "enabled": false
        }
    }
}

Example Create load balancer with shared IP: XML response

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0"
    id="144"
    name="a-new-loadbalancer"
    algorithm="RANDOM"
    protocol="HTTP"
    port="83"
    httpsRedirect="false"
    halfClosed="false"
    status="BUILD"
    timeout="30">
    <virtualIps>
        <virtualIp
            id="15"
            address="10.0.0.18"
            ipVersion="IPV4"
            type="PUBLIC" />
    </virtualIps>
    <nodes>
        <node
            id="653"
            address="10.1.1.1"
            port="80"
            condition="ENABLED"
            status="ONLINE"
            weight="1"
            type="PRIMARY"/>
    </nodes>
    <cluster name="ztm-n03.staging1.lbaas.rackspace.net" />
    <created time="2011-02-08T21:19:55Z" />
    <updated time="2011-02-08T21:19:55Z" />
    <connectionLogging enabled="false" />
    <contentCaching enabled="false"/>
    <sourceAddresses ipv4Servicenet="10.0.0.0" ipv4Public="10.12.99.29" ipv6Public="2001:4801:79f1:1::3/64"/>
</loadBalancer>

Example Create load balancer with Shared IPv4/IPv6: JSON response

{
    "loadBalancer": {
        "name": "a-new-loadbalancer",
        "id": 144,
        "protocol": "HTTP",
        "halfClosed": "false",
        "port": 83,
        "algorithm": "RANDOM",
        "status": "BUILD",
        "timeout": 30,
        "cluster": {
            "name": "ztm-n01.staging1.lbaas.rackspace.net"
        },
        "nodes": [
            {
                "address": "10.1.1.1",
                "id": 653,
                "port": 80,
                "status": "ONLINE",
                "condition": "ENABLED",
                "weight": 1,
                "type": "PRIMARY"
            }
        ],
        "virtualIps": [
            {
                "address": "10.0.0.18",
                "id": 15,
                "type": "PUBLIC",
                "ipVersion": "IPV4"
            },
            {
                "address":"fd24:f480:ce44:91bc:1af2:15ff:0000:0005",
                "id":9000137,
                "type":"PUBLIC",
                "ipVersion":"IPV6"
            }
        ],
        "created": {
            "time": "2011-04-13T14:18:07Z"
        },
        "sourceAddresses":{
            "ipv6Public":"2001:4801:79f1:1::3/64",
            "ipv4Servicenet":"10.0.0.0",
            "ipv4Public":"10.12.99.28"
        },
        "httpsRedirect": false,
        "connectionLogging": {
            "enabled": false
        },
        "contentCaching": {
            "enabled": false
        }
    }
}

Example Create load balancer with Shared IPv4/IPv6: XML response

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0"
    id="144"
    name="a-new-loadbalancer"
    algorithm="RANDOM"
    protocol="HTTP"
    httpsRedirect="false"
    halfclosed="false"
    port="83"
    status="BUILD"
    timeout="30">
    <virtualIps>
        <virtualIp
            id="15"
            address="10.0.0.18"
            ipVersion="IPV4"
            type="PUBLIC" />
        <virtualIp
            id="9000137"
            address="fd24:f480:ce44:91bc:1af2:15ff:0000:0005"
            ipVersion="IPV6"
            type="PUBLIC" />
    </virtualIps>
    <nodes>
        <node
            id="653"
            address="10.1.1.1"
            port="80"
            condition="ENABLED"
            status="ONLINE"
            weight="1"
            type="PRIMARY"/>
    </nodes>
    <cluster name="ztm-n03.staging1.lbaas.rackspace.net" />
    <created time="2011-02-08T21:19:55Z" />
    <updated time="2011-02-08T21:19:55Z" />
    <connectionLogging enabled="false" />
    <contentCaching enabled="false"/>
    <sourceAddresses ipv4Servicenet="10.0.0.0" ipv4Public="10.12.99.29" ipv6Public="2001:4801:79f1:1::3/64"/>
</loadBalancer>

Bulk-delete load balancers

DELETE /v1.0/{account}/loadbalancers

Bulk-deletes load balancers.

The bulk-delete load balancer function removes the specified load balancer and its associated configuration from the account. Any and all configuration data is immediately purged and is not recoverable.

To bulk-delete load balancers, provide a query parameter list of load balancer IDs. For example, use /v1.0/{account}/loadbalancers?id=<id>&id=<id>. The current default limit is ten IDs per request.

This operation is an all or nothing proposition. If one or more of the items in the list cannot be removed due to their current status, a badRequest (400) is returned along with the IDs of the items the system identified as potential failures for this request. In this case, no load balancers are deleted, and the user is notified with the specified ID(s) and related error message.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

202

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

422

ImmutableEntity

This fault is returned when a user attempts to modify an item that is not currently in a state that allows modification. For example, load balancers in a status of PENDING_UPDATE,BUILD, or DELETED may not be modified.

500

Load Balancer Fault

The load balancer has experienced a fault.

503

Service Unavailable

The service is not available.

Request

The following table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The ID for the tenant or account in a multi- tenancy cloud.

The following table shows the query parameters for the request:

Name

Type

Description

id

String

One to ten load balancer IDs. For example: ?id={loadBalancerId}. The default limit is ten IDs per request.

This operation does not accept a request body.

Response

This operation does not return a response body.

Show load balancer details

GET /v1.0/{account}/loadbalancers/{loadBalancerId}

Shows details for a specified load balancer.

This operation provides detailed output 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. Notice in the following examples that API users are now able to programmatically derive the source IP addresses of our load balancers using the sourceAddresses label included at the bottom of the list load balancer details response. This feature is useful for customers who are automating the deployment of infrastructure and need to determine the IP addresses of requests coming from our load balancers for the purpose of creating more robust firewall rules. The following table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

422

ImmutableEntity

This fault is returned when a user attempts to modify an item that is not currently in a state that allows modification. For example, load balancers in a status of PENDING_UPDATE,BUILD, or DELETED may not be modified.

500

Load Balancer Fault

The load balancer has experienced a fault.

503

Service Unavailable

The service is not available.

Request

The following table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The ID for the tenant or account in a multi- tenancy cloud.

{loadBalancerId}

String

The ID for the load balancer.

This operation does not accept a request body.

Response

The following table shows the body parameters for the response:

Name

Type

Description

loadBalancer

String

A loadBalancer object.

id

Int

The ID for the load balancer.

protocol

String

Protocol of the service that is being load balanced.

port

String

Port number for the service you are load balancing.

algorithm

String

Algorithm that defines how traffic should be directed between back- end nodes.

status

String

The status of the load balancer.

timeout

String

The timeout value for the load balancer and communications with its nodes. Defaults to 30 seconds with a maximum of 120 seconds.

connectionLogging

String

Current connection logging configuration. Refer to the API Ops section “Log connections” for information and examples.

virtualIps

Object

Type of virtualIp to add with the creation of a load balancer. See the virtual IP types table in the API Ops section “Virtual IPs”.

id

Int

The ID for the IP address.

address

String

The IP address.

type

String

The IP address type.

ipVersion

String

The IP version.

nodes

Object

Nodes to be added to the load balancer.

address

String

The node address.

port

Int

The node port.

condition

String

The node condition. For example, ENABLED.

status

String

The node status. For example, ONLINE.

sessionPersistence

String

Specifies whether multiple requests from clients are directed to the same node.

connectionThrottle

String

Specifies limits on the number of connections per IP address to help mitigate malicious or abusive traffic to your applications. Refer to the API Ops section “Throttle connections” for information and examples.

cluster

String

The cluster name.

created

Object

The date and time what the load balancer was created.

updated

Object

The date and time what the load balancer was last updated.

sourceAddresses

Dict

The source public and private IP addresses.

Example Show load balancer details: JSON response

{
    "loadBalancer":{
        "id": 2000,
        "name":"sample-loadbalancer",
        "protocol":"HTTP",
        "port": 80,
        "algorithm":"RANDOM",
        "status":"ACTIVE",
        "timeout": 30,
        "virtualIps":[
            {
                "id": 1000,
                "address":"206.10.10.210",
                "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"
            }
        ],
        "sessionPersistence":{
            "persistenceType":"HTTP_COOKIE"
        },
        "connectionThrottle":{
            "minConnections": 10,
            "maxConnections": 100,
            "maxConnectionRate": 50,
            "rateInterval": 60
        },
        "cluster":{
            "name":"c1.dfw1"
        },
        "created":{
            "time":"2010-11-30T03:23:42Z"
        },
        "updated":{
            "time":"2010-11-30T03:23:44Z"
        },
        "sourceAddresses":{
            "ipv6Public":"2001:4801:79f1:1::3/64",
            "ipv4Servicenet":"10.0.0.0",
            "ipv4Public":"10.12.99.28"
        },
        "httpsRedirect": false,
        "connectionLogging":{
            "enabled":false
        },
        "contentCaching": {
            "enabled": false
        }
    }
}

Example Show load balancer details: XML response

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0"
    id="2000"
    name="sample-loadbalancer"
    protocol="HTTP"
    port="80"
    algorithm="RANDOM"
    status="ACTIVE"
    httpsRedirect="false"
    halfClosed="false"
    timeout="30">
    <virtualIps>
        <virtualIp
            id="1000"
            address="206.10.10.210"
            type="PUBLIC"
            ipVersion="IPV4" />
    </virtualIps>
    <nodes>
        <node
            id="1041"
            address="10.1.1.1"
            port="80"
            condition="ENABLED"
            status="ONLINE" />
        <node
            id="1411"
            address="10.1.1.2"
            port="80"
            condition="ENABLED"
            status="ONLINE" />
    </nodes>
    <sessionPersistence persistenceType="HTTP_COOKIE"/>
    <connectionThrottle
        minConnections="10"
        maxConnections="100"
        maxConnectionRate="50"
        rateInterval="60" />
    <cluster name="c1.dfw1" />
    <created time="2010-11-30T03:23:42Z" />
    <updated time="2010-11-30T03:23:44Z" />
    <connectionLogging enabled="false" />
    <contentCaching enabled="false"/>
    <sourceAddresses ipv4Servicenet="10.0.0.0" ipv4Public="10.12.99.29" ipv6Public="2001:4801:79f1:1::3/64"/>    </loadBalancer>

Example Show atom load balancer details: ATOM/XML response

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns="http://www.w3.org/2005/Atom">
    <link rel="next"
          href="https://ord.loadbalancers.api.rackspacecloud.com/v1.0/1234/loadbalancers/141.atom?page=2"/>
    <title type="text">Load Balancer Feed</title>
    <id>1234-loadbalancers-141</id>
    <author>
        <name>Rackspace Cloud</name>
    </author>
    <entry>
        <title type="text">Load Balancer Successfully Updated</title>
        <summary
                type="text">Load balancer successfully updated with algorithm: 'RANDOM', protocol: 'HTTP', port: '80''
        </summary>
        <author>
            <name>tvardema</name>
        </author>
        <link href="https://ord.loadbalancers.api.rackspacecloud.com/v1.0/1234/loadbalancers/141"/>
        <id>1234-loadbalancers-141-2011961339450</id>
        <category term="UPDATE"/>
        <updated>2011-04-06T13:39:45.000Z</updated>
    </entry>
</feed>

Update load balancer properties

PUT /v1.0/{account}/loadbalancers/{loadBalancerId}

Updates the properties for a specified load balancer.

This operation asynchronously updates the attributes for a specified load balancer. Upon successful validation of the request, the service returns a 202 (Accepted) response code. A caller can poll the load balancer with its ID to wait for the changes to be applied and the load balancer to return to an ACTIVE status.

Note

The load balancer’s ID and status are immutable attributes and cannot be modified by the caller. Supplying an unsupported attribute results in a 400 (badRequest) fault.

Note

When you update the Load Balancer’s protocol, some properties, such as content_caching that are incompatible, trigger validation failures resulting in a BadRequest exception. View the related documentation pages for further information.

The following table shows the possible response codes for this operation:

Response Code

Name

Description

202

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

422

ImmutableEntity

This fault is returned when a user attempts to modify an item that is not currently in a state that allows modification. For example, load balancers in a status of PENDING_UPDATE,BUILD, or DELETED may not be modified.

500

Load Balancer Fault

The load balancer has experienced a fault.

503

Service Unavailable

The service is not available.

Request

The following table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The ID for the tenant or account in a multi- tenancy cloud.

{loadBalancerId}

String

The ID for the load balancer.

The following table shows the body parameters for the request:

Name

Type

Description

name

String

Name of the load balancer to update. The name must be 128 characters or fewer in length, and all UTF-8 characters are valid. See http://www.utf8-chartable.de/ for information about the UTF-8 character set.

protocol

String

Protocol of the service that is being load balanced.

halfClosed

Boolean

Enables or disables Half-Closed support for the load balancer. Half- Closed support provides the ability for one end of the connection to terminate its output, while still receiving data from the other end. Only available for TCP/TCP_CLIENT_FIRST protocols.

algorithm

String

Algorithm that defines how traffic should be directed between back-end nodes.

port

String

Port number for the service you are load balancing.

timeout

String

The timeout value for the load balancer and communications with its nodes. Defaults to 30 seconds with a maximum of 120 seconds.

httpsRedirect

Boolean

Enables or disables HTTP to HTTPS redirection for the load balancer. When enabled, any HTTP request returns status code 301 (Moved Permanently), and the requester is redirected to the requested URL via the HTTPS protocol on port 443. For example, http://example.com/page.html would be redirected to https://example.com/page.html. Only available for HTTPS protocol ( port=443 ), or HTTP protocol with a properly configured SSL termination ( secureTrafficOnly=true, securePort=443 ). Note that SSL termination for a load balancer can only be configured after the load balancer has been created.

Example Update load balancer properties: JSON request

{"loadBalancer":{
    "name": "sample-loadbalancer",
    "algorithm": "RANDOM",
    "protocol": "HTTP",
    "port": 80,
    "timeout": 60,
    "httpsRedirect": true
    }
}

Example Update load balancer properties: XML request

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0"
    name="sample-loadbalancer"
    algorithm="RANDOM"
    protocol="HTTP"
    port="80"
    timeout="60"
    httpsRedirect="true"/>

Response

This operation does not return a response body.

Delete load balancer

DELETE /v1.0/{account}/loadbalancers/{loadBalancerId}

Deletes a load balancer from the account.

The delete load balancer call removes the specified load balancer and its associated configuration from the account. Any and all configuration data is immediately purged and is not recoverable. The following table shows the possible response codes for this operation:

Response Code

Name

Description

202

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

422

ImmutableEntity

This fault is returned when a user attempts to modify an item that is not currently in a state that allows modification. For example, load balancers in a status of PENDING_UPDATE,BUILD, or DELETED may not be modified.

500

Load Balancer Fault

The load balancer has experienced a fault.

503

Service Unavailable

The service is not available.

Request

The following table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The ID for the tenant or account in a multi- tenancy cloud.

{loadBalancerId}

String

The ID for the load balancer.

This operation does not accept a request body.

Response

This operation does not return a response body.