Load balancers¶

List load balancers
Create load balancer
Bulk-delete load balancers
Show load balancer details
Update load balancer properties
Delete load balancer

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 name query parameter to list all the instances of any specific load balancer. For example, using the URI /loadbalancers?name=a-loadbalancer lists all the loadbalancer instances having the name as “a-loadbalancer”. 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.

Note

While using “nodeaddress” and “name” query params together in a URI please note that nodeaddress takes precedence over name.

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.

Load balancers¶

List load balancers¶

Request¶

Response¶

Create load balancer¶

Request¶

Response¶

Bulk-delete load balancers¶

Request¶

Response¶

Show load balancer details¶

Request¶

Response¶

Update load balancer properties¶

Request¶

Response¶

Delete load balancer¶

Request¶

Response¶

List load balancers ¶

Create load balancer ¶

Bulk-delete load balancers ¶

Show load balancer details ¶

Update load balancer properties ¶

Delete load balancer ¶