Rackspace ManualsRackspace Cloud Load Balancers Developer Guide  - API v1.0

  Atom feed of this document
 
 
 

 4.1.3. Create Load Balancer

Verb URI Description
POST /loadbalancers Create a new load balancer with the configuration defined by the request.

Normal Response Code(s): 202

Error Response Code(s): loadbalancerFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

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 will be returned. The object will contain a unique identifier and status of the request. Using the identifier, 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 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.

An HTTP load balancer will have the X-Forwarded-For (XFF) HTTP header set by default. This header will contain 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 reenable it.)

An HTTP load balancer will also include 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 (refer to Section 4.17, “SSL Termination”).

An HTTP load balancer will also include 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.

The following table lists the required and optional attributes for Create Load Balancer:

Table 4.1. Required and Optional Attributes for Create Load Balancer
Name Description Required
name Name of the load balancer to create. The name must be 128 characters or less in length, and all UTF-8 characters are valid. Refer to http://www.utf8-chartable.de/ for information about the UTF-8 character set. Refer to the request examples in this section for the required xml/json format. Yes
nodes Nodes to be added to the load balancer. Refer to the request examples in this section for the required xml/json format. Yes
protocol Protocol of the service which is being load balanced. Refer to Section 4.15, “Protocols” for a table of available protocols. Yes
halfClosed Enable or Disable 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. No
virtualIps Type of virtualIp to add along with the creation of a load balancer. See the Virtual IP Types table below for the Virtual IP Types. Yes
accessList The access list management feature allows fine-grained network access controls to be applied to the load balancer's virtual IP address. Refer to the request examples in Section 4.10, “Access Lists” for the required xml/json format. No
algorithm Algorithm that defines how traffic should be directed between back-end nodes. Refer to the request examples in Section 4.16, “Algorithms” for the required xml/json format. No
connectionLogging Current connection logging configuration. Refer to the request examples in Section 4.13.1, “Log Connections” for the required xml/json format. No
connectionThrottle Specifies limits on the number of connections per IP address to help mitigate malicious or abusive traffic to your applications. Refer to the request examples in Section 4.13.2, “Throttle Connections” for the required xml/json format. No
healthMonitor The type of health monitor check to perform to ensure that the service is performing properly. Refer to the request examples in Section 4.11.1, “Monitor Health” for the required xml/json format. No
metadata Information (metadata) that can be associated with each load balancer for the client's personal use. Refer to the request examples in Section 4.18.2, “Add Metadata” for the required xml/json format. No
port Port number for the service you are load balancing. Refer to Notes below table
timeout The timeout value for the load balancer and communications with its nodes. Defaults to 30 seconds with a maximum of 120 seconds. No
sessionPersistence Specifies whether multiple requests from clients are directed to the same node. Refer to the request examples in Section 4.12.1, “Manage Session Persistence” for the required xml/json format. No
[Note]Notes

  • 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.

  • Any protocol that is not listed in the List Load Balancing Protocols Response (see Section 4.15.1, “List Load Balancing Protocols”), 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 4.2. 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
 

Example 4.9. Create Load Balancer (Required Attributes) Request: XML

<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 4.10. Create Load Balancer (Required Attributes) Request: JSON

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

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 need to determine the IP addresses of requests coming from our load balancers for the purpose of creating more robust firewall rules.

 

Example 4.11. Create Load Balancer (Required Attributes) Response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0" id="2198" name="a-new-loadbalancer"
              algorithm="RANDOM" protocol="HTTP" halfClosed="false" port="80" status="BUILD" timeout="30">
    <virtualIps>
        <virtualIp id="13" address="10.0.0.16" ipVersion="IPV4" type="PUBLIC"/>
        <virtualIp id="9000135" address="fd24:f480:ce44:91bc:1af2:15ff:0000:0003" ipVersion="IPV6" type="PUBLIC"/>
    </virtualIps>
    <nodes>
        <node id="2206" address="10.1.1.1" port="80" condition="ENABLED" status="ONLINE" weight="1"/>
    </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"/>
    <sourceAddresses ipv4Servicenet="10.0.0.0" ipv4Public="10.12.99.29" ipv6Public="2001:4801:79f1:1::3/64"/>
</loadBalancer>

 

Example 4.12. Create Load Balancer (Required Attributes) Response: JSON

{
    "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
            }
        ],
        "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-06-01T08:20:09-05:00"
        },
        "updated":{
            "time":"2011-06-01T08:20:09-05:00"
        },
        "connectionLogging":{
            "enabled":false
        },
        "sourceAddresses":{
            "ipv6Public":"2001:4801:79f1:1::1/64",
            "ipv4Servicenet":"10.0.0.0",
            "ipv4Public":"10.12.99.28"
        }
    }
}

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 method makes it possible to use the same load balancing configuration to support HTTP and HTTPS.

[Note]Notes

  • 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. Please see Section 3.10, “Compatible Shared Load Balancing Protocols” for more details.

 

Example 4.13. Create Load Balancer (Required Attributes with Shared IP) Request: XML

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

 

Example 4.14. Create Load Balancer (Required Attributes with Shared IP) Request: JSON

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

 

Example 4.15. Create Load Balancer (Required Attributes with Shared IP) Response: XML

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0"
    id="144"
    name="a-new-loadbalancer"
    algorithm="RANDOM"
    protocol="HTTP"
    port="83"
    status="BUILD"
    timeout="30">
    <virtualIps>
        <virtualIp
            id="39"
            address="206.10.10.210"
            ipVersion="IPV4"
            type="PUBLIC" />
    </virtualIps>
    <nodes>
        <node
            id="653"
            address="10.1.1.1"
            port="80"
            condition="ENABLED"
            status="ONLINE"
            weight="1" />
    </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" />
</loadBalancer>

 

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

{
    "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
            }
        ],
        "virtualIps": [
            {
                "address": "206.10.10.210",
                "id": 39,
                "type": "PUBLIC",
                "ipVersion": "IPV4"
            }
        ],
        "created": {
            "time": "2011-04-13T14:18:07Z"
        },
        "updated": {
            "time": "2011-04-13T14:18:07Z"
        },
        "connectionLogging": {
            "enabled": false
        }
    }
}

 

Example 4.17. Create Load Balancer (Required Attributes with Shared IPV4 and IPV6) Request: XML

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

 

Example 4.18. Create Load Balancer (Required Attributes with Shared IPV4 and IPV6) Request: JSON

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

 

Example 4.19. Create Load Balancer (Required Attributes with Shared IPV4 and IPV6) Response: XML

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0"
    id="144"
    name="a-new-loadbalancer"
    algorithm="RANDOM"
    protocol="HTTP"
    halfclosed="false"
    port="83"
    status="BUILD"
    timeout="30">
    <virtualIps>
        <virtualIp
            id="39"
            address="206.10.10.210"
            ipVersion="IPV4"
            type="PUBLIC" />
        <virtualIp
            id="900001"
            address="2001:4801:79f1:0002:711b:be4c:0000:0021"
            ipVersion="IPV6"
            type="PUBLIC" />
    </virtualIps>
    <nodes>
        <node
            id="653"
            address="10.1.1.1"
            port="80"
            condition="ENABLED"
            status="ONLINE"
            weight="1" />
    </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" />
</loadBalancer>

 

Example 4.20. Create Load Balancer (Required Attributes with Shared IPV4 and IPV6) Response: JSON 

{
    "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
            }
        ],
        "virtualIps": [
            {
                "address": "206.10.10.210",
                "id": 39,
                "type": "PUBLIC",
                "ipVersion": "IPV4"
            },
            {
                "address": "2001:4801:79f1:0002:711b:be4c:0000:0021",
                "id": 900001,
                "type": "PUBLIC",
                "ipVersion": "IPV6"
            }
        ],
        "created": {
            "time": "2011-04-13T14:18:07Z"
        },
        "updated": {
            "time": "2011-04-13T14:18:07Z"
        },
        "connectionLogging": {
            "enabled": false
        }
    }
}

Legal notices
loading table of contents...