Create and manage Cloud Load Balancers

You can use the examples in the following sections to create and manage load balancers by using Cloud Load Balancers API operations.

Before running the examples, review the Cloud Load Balancers concepts to understand the API workflow, messaging patterns, and use cases.

Note

These examples use the $API_ENDPOINT, $AUTH_TOKEN, and $TENANT_ID environment variables to specify the API endpoint, authentication token, and project ID values for accessing the service. Make sure you configure these variables before running the code samples.

Creating Cloud Servers

In this section you create two new Cloud Servers (or use two existing Cloud Servers) to set up as nodes for your load balancer.

Note

If you are using existing Cloud Servers on your account, skip Steps 1-5 and go directly to Step 6 below.

Create a Cloud Server using the Cloud Servers section of the Cloud Control Panel (login here: Cloud Control Panel).

Note

You can also create a Cloud Server using the Cloud Servers API. Refer to the Cloud Servers API Developer Guide for details.

  1. Click Servers to view the Cloud Servers page.

  2. Click Create Server, then select the Region, and specify the Server Name.

  3. Select an image from a list of different operating systems, including Linux Distributions and Windows Images.

  4. Specify the Flavor for your Cloud Server, then click Create Server. Record the information requested in Step 6 below.

  5. Create a second Cloud Server by performing Steps 1-4 again.

  6. Record the IP addresses of your Cloud Servers that are listed in the the Cloud Servers section of the Cloud Control Panel):

    FIRST Cloud Server IP Address =
_______________________________________

SECOND Cloud Server IP Address =
_______________________________________

Creating a Load Balancer

Cloud Load Balancers make it easy to develop scalable, high-availability configurations in the Cloud. By leveraging Cloud Load Balancers, you will be provided with a dedicated IP address that you can use to reach your service.

You need to use the Create Load Balancer API call (POST /loadbalancers) to create a load balancer with the configuration that you specify.

In this case, assume that you want to create a load balancer with the following configuration:

  • Protocol = HTTP(80)

  • Virtual IP Type = PUBLIC

Note

When your resources reside in the same region as your load balancer, devices are in close proximity to each other and can elect to take advantage of ServiceNet connectivity (by specifying Virtual IP Type = SERVICENET) for free data transfer between services if desired.

  • Nodes = enter the IP address that you recorded for your first Cloud Server created in Creating Cloud Servers:

    <node address="<IP address of FIRST cloud server>"\
port="80" condition="ENABLED"/>

Note

Although you can add the nodes for both of your Cloud Servers in this Create Load Balancer request, the Getting Started examples show how to add the node for your second Cloud Server by making a separate request using the Add node operation.

The following examples show the cURL requests for Create Load Balancer:

Example: cURL Create Load Balancer request: XML

curl -s -d \
'<?xml version="1.0" ?>
<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="<IP address of FIRST cloud server>" port="80" condition="ENABLED"/>
    </nodes>
</loadBalancer>' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
"$API_ENDPOINT/loadbalancers" | ppxml

Example: cURL Create Load Balancer request: JSON

curl -s -d \
'{
    "loadBalancer": {
        "name": "a-new-loadbalancer",
        "port": 80,
        "protocol": "HTTP",
        "virtualIps": [
            {
                "type": "PUBLIC"
            }
         ],
        "nodes": [
            {
                "address": "<IP address of FIRST cloud server>",
                "port": 80,
                "condition": "ENABLED"
            }
        ]
    }
}' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
"$API_ENDPOINT/loadbalancers" | python -m json.tool

The following examples show the responses for Create Load Balancer:

Example: Create Load Balancer response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0" id="5355" name="a-new-loadbalancer"
    algorithm="RANDOM" protocol="HTTP" port="80" status="BUILD">
    <virtualIps>
        <virtualIp id="1163" address="50.56.166.100" ipVersion="IPV4" type="PUBLIC"/>
        <virtualIp id="9002499" address="2001:4800:7901:0000:9c92:6fca:0000:0001" ipVersion="IPV6" type="PUBLIC"/>
    </virtualIps>
    <nodes>
        <node id="44615" address="50.56.207.146" port="80" condition="ENABLED" status="ONLINE" weight="1"/>
    </nodes>
    <cluster name="ztm-n02.lbaas.dfw1.rackspace.net"/>
    <created time="2012-02-29T18:20:44Z"/>
    <updated time="2012-02-29T18:20:44Z"/>
    <connectionLogging enabled="false"/>
    <sourceAddresses ipv4Servicenet="10.183.250.133" ipv4Public="174.143.139.133" ipv6Public="2001:4800:7901::2/64"/>
</loadBalancer>

Example: cURL Create Load Balancer response: JSON

{
    "loadBalancer":{
        "name":"a-new-loadbalancer",
        "id":5355,
        "port":80,
        "protocol":"HTTP",
        "algorithm":"RANDOM",
        "status":"BUILD",
        "cluster":{
        "name":"ztm-n02.lbaas.dfw1.rackspace.net"
        },
        "nodes":[{
                "address":"50.56.207.146",
                "id":44615,
                "port":80,
                "status":"ONLINE",
                "condition":"ENABLED",
                "weight":1
            }
        ],
        "virtualIps":[{
                "address":"50.56.166.100",
                "id":1163,
                "type":"PUBLIC",
                "ipVersion":"IPV4"
            },
            {
                "address":"2001:4800:7901:0000:9c92:6fca:0000:0001",
                "id":9002499,
                "type":"PUBLIC",
                "ipVersion":"IPV6"
            }
        ],
        "created":{
            "time":"2012-02-29T18:20:44Z"
        },
        "updated":{
            "time":"2012-02-29T18:20:44Z"
        },
        "connectionLogging":{
            "enabled":false
        },
        "sourceAddresses":{
            "ipv6Public":"2001:4800:7901::2/64",
            "ipv4Servicenet":"10.183.250.133",
            "ipv4Public":"174.143.139.133"
        }
    }
}

In the previous examples, you can see that one node (with IP address 50.56.166.100) has been added to your new load balancer with id 5355. You need the load balancer id when you use the list load balancer details API operation in the next section. You also need to supply the load balancer id in examples that include the load_balancer_id variable.

Listing Load Balancer details

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.

This operation does not require a request body.

The examples list the details for the load balancer (with load_balancer_id, which you will need to replace in the URL in the example below) that you created in the previous section.

The following examples show the cURL requests for List Load Balancer Details:

Example: cURL List Load Balancer details request: XML

curl -s  \
-H "X-Auth-Token: $AUTH_TOKEN"  \
-H "X-Project-Id: $TENANT_ID" \
-H "Accept: application/xml"  \
"$API_ENDPOINT/loadbalancers/load_balancer_id" | ppxml

Example: cURL List Load Balancer details request: JSON

curl -s  \
-H "X-Auth-Token: $AUTH_TOKEN"  \
-H "X-Project-Id: $TENANT_ID" \
-H "Accept: application/json"  \
"$API_ENDPOINT/loadbalancers/load_balancer_id" | python -m json.tool

The following examples show the List Load Balancer details responses:

Example: List Load Balancer details response: XML

<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0"
    id="5355"
    name="a-new-loadbalancer"
    protocol="HTTP"
    port="80"
    algorithm="RANDOM"
    status="ACTIVE"
    timeout="30">
    <connectionLogging enabled="false" />
    <virtualIps>
        <virtualIp
            id="1163"
            address="50.56.166.100"
            ipVersion="IPV4"
            type="PUBLIC" />
        <virtualIp
            id="9002499"
            address="2001:4800:7901:0000:9c92:6fca:0000:0001"
            ipVersion="IPV6"
            type="PUBLIC"/>
    </virtualIps>
    <nodes>
        <node
            id="44615"
            address="50.56.207.146"
            port="80"
            condition="ENABLED"
            status="ONLINE" />
    </nodes>
    <cluster name="ztm-n02.lbaas.dfw1.rackspace.net" />
    <created time="2010-11-30T03:23:42Z" />
    <updated time="2010-11-30T03:23:44Z" />
    <sourceAddresses ipv4Servicenet="10.183.250.133" ipv4Public="174.143.139.133" ipv6Public="2001:4800:7901::2/64"/>
</loadBalancer>

Example: List Load Balancer details response: JSON

{
    "loadBalancer":{
        "id": 5355,
        "name":"a-new-loadbalancer",
        "protocol":"HTTP",
        "port": 80,
        "algorithm":"RANDOM",
        "status":"ACTIVE",
        "timeout": 30,
        "connectionLogging":{
            "enabled":false
        },
        "virtualIps":[
            {
                "id": 1163,
                "address":"50.56.166.100",
                "ipVersion":"IPV4",
                "type":"PUBLIC"
            },
            {
                "id": 9002499,
                "address":"2001:4800:7901:0000:9c92:6fca:0000:0001",
                "ipVersion":"IPV6",
                "type":"PUBLIC"
            }
        ],
        "nodes":[
            {
                "id": 44615,
                "address":"50.56.207.146",
                "port": 80,
                "condition":"ENABLED",
                "status":"ONLINE"
            }
        ],
        "cluster":{
            "name":"ztm-n02.lbaas.dfw1.rackspace.net"
        },
        "created":{
            "time":"2010-11-30T03:23:42Z"
        },
        "updated":{
            "time":"2010-11-30T03:23:44Z"
        },
        "accountLoadBalancerServiceEvents":{
            "accountId":406271
        },
        "sourceAddresses":{"ipv6Public":"2001:4800:7901::2/64","ipv4Servicenet":"10.183.250.133","ipv4Public":"174.143.139.133"}
    }
}

Adding a node

When a node is added to a load balancer, it is assigned a unique identifier that can be used for management operations such as changing the condition or removing it.

For the node, enter the IP address that you recorded for your second Cloud Server created in Creating Cloud Servers. For example, for the XML request, enter:

  • <node address="<IP address of SECOND cloud server>" port="80" condition="ENABLED"/>

The following examples show the cURL requests for Add node:

Example: cURL Add node request: XML

curl -s -d \
'<?xml version="1.0" ?>
<nodes xmlns="http://docs.openstack.org/loadbalancers/api/v1.0">
    <node address="<IP address of SECOND cloud server>" port="80" condition="ENABLED" />
</nodes>' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
"$API_ENDPOINT/loadbalancers/load_balancer_id/nodes" | ppxml

Example: cURL Add node request: JSON

curl -s -d \
'{
    "nodes": [
        {
            "address": "<IP address of SECOND cloud server>",
            "port": 80,
            "condition": "ENABLED"
        }
    ]
}' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
"$API_ENDPOINT/loadbalancers/load_balancer_id/nodes" | python -m json.tool

Remember to replace the load_balancer_id in the examples above with its actual respective value:

The following examples show the responses returned for an add node API request:

Example: Add node response: XML

<nodes xmlns="http://docs.openstack.org/loadbalancers/api/v1.0">
    <node
        address="108.166.67.215"
        id="44717"
        port="80"
        condition="ENABLED"
        status="ONLINE"
        weight="1"/>
</nodes>

Example: Add node response: JSON

{
    "nodes": [
        {
            "address": "108.166.67.215",
            "id": 44717,
            "port": 80,
            "status": "ONLINE",
            "condition": "ENABLED",
            "weight": 1
        }
    ]
}

Updating Load Balancer attributes

Assume that you want to change the algorithm for your load balancer from RANDOM to LEAST_CONNECTIONS. You can use the Update Load Balancer attributes API call to accomplish this task. This call allows you to change one or more of the following load balancer attributes:

  • name

  • algorithm

  • protocol

  • port

The following examples show the cURL requests for Update Load Balancer attributes to change the algorithm to LEAST_CONNECTIONS:

Example: cURL Update Load Balancer attributes request: XML

curl -s -d \
'<?xml version="1.0" ?>
<loadBalancer xmlns="http://docs.openstack.org/loadbalancers/api/v1.0"
    algorithm="LEAST_CONNECTIONS" />' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
-X PUT \
"$API_ENDPOINT/loadbalancers/load_balancer_id"

Example: cURL Update Load Balancer attributes request: JSON

curl -s -d \
'{"loadBalancer":{
    "algorithm": "LEAST_CONNECTIONS"
    }
}' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
-X PUT \
"$API_ENDPOINT/loadbalancers/load_balancer_id"

This operation does not return a response body.

You can now confirm that the algorithm is changed by calling List Load Balancer details, as described in Listing Load Balancer details.

You can also view the information for the load balancer you have created by clicking Load Balancers near the top of the Cloud Control Panel. Then click the name of the load balancer to view the details.

This concludes the Getting Started Guide.