The Complete User Guide to Load Balancers¶

Client¶

To use the load balancers service, you must first instantiate a Rackspace client object.

use OpenCloud\Rackspace;

$client = new Rackspace(Rackspace::US_IDENTITY_ENDPOINT, array(
    'username' => '<YOUR RACKSPACE CLOUD ACCOUNT USERNAME>',
    'apiKey'   => '<YOUR RACKSPACE CLOUD ACCOUNT API KEY>'
));

Load Balancer Service¶

All operations on load balancers are done via a load balancer service object.

$loadBalancerService = $client->loadBalancerService('cloudLoadBalancers', 'DFW');

Cloud Servers¶

Many of the examples in this document use two cloud servers as nodes for the load balancer. The variables $serverOne and $serverTwo refer to these two cloud servers.

Create Load Balancer¶

$loadBalancer = $loadBalancerService->loadBalancer();

$serverOneNode = $loadBalancer->node();
$serverOneNode->address = $serverOne->addresses->private[0]->addr;
$serverOneNode->port = 8080;
$serverOneNode->condition = 'ENABLED';

$serverTwoNode = $loadBalancer->node();
$serverTwoNode->address = $serverTwo->addresses->private[0]->addr;
$serverTwoNode->port = 8080;
$serverTwoNode->condition = 'ENABLED';

$loadBalancer->addVirtualIp('PUBLIC');
$loadBalancer->create(array(
    'name'     => 'My smart load balancer',
    'port'     => 80,
    'protocol' => 'HTTP',
    'nodes'    => array($serverOneNode, $serverTwoNode)
));

List Load Balancer Details¶

You can retrieve a single load balancer’s details by using its ID.

$loadBalancer = $loadBalancerService->loadBalancer('254889');

/** @var $loadBalancer OpenCloud\LoadBalancer\Resource\LoadBalancer **/

List Load Balancers¶

You can retrieve a list of all your load balancers. An instance of OpenCloud\Common\Collection\PaginatedIterator is returned.

$loadBalancers = $loadBalancerService->loadBalancerList();
foreach ($loadBalancers as $loadBalancer) {
    /** @var $loadBalancer OpenCloud\LoadBalancer\Resource\LoadBalancer **/
}

Update Load Balancer Attributes¶

You can update one or more of the following load balancer attributes:

• name: The name of the load balancer
• algorithm: The algorithm used by the load balancer to distribute traffic amongst its nodes. See also: Load balancing algorithms.
• protocol: The network protocol used by traffic coming in to the load balancer. See also: Protocols.
• port: The network port on which the load balancer listens for incoming traffic.
• halfClosed: Enable or Disable Half-Closed support for the load balancer.
• timeout: The timeout value for the load balancer to communicate with its nodes.
• httpsRedirect: Enable or disable HTTP to HTTPS redirection for the load balancer. When enabled, any HTTP request will return status code 301 (Moved Permanently), and the requestor will be 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). See also: SSL Termination.

$loadBalancer->update(array(
    'name' => 'New name'
));

$loadBalancer->update(array(
    'name'      => 'New name',
    'algorithm' => 'ROUND_ROBIN'
));

Remove Load Balancer¶

When you no longer have a need for the load balancer, you can remove it.

$loadBalancer->delete();

List Nodes¶

You can list the nodes attached to a load balancer. An instance of OpenCloud\Common\Collection\PaginatedIterator is returned.

$nodes = $loadBalancer->nodeList();
foreach ($nodes as $node) {
    /** @var $node OpenCloud\LoadBalancer\Resource\Node **/
}

Add Nodes¶

You can attach additional nodes to a load balancer. Assume $loadBalancer already has two nodes attached to it - $serverOne and $serverTwo - and you want to attach a third node to it, say $serverThree, which provides a service on port 8080.

Important: Remember to call $loadBalancer->addNodes() after all the calls to $loadBalancer->addNode() as shown below.

$address = $serverThree->addresses->private[0]->addr;
$loadBalancer->addNode($address, 8080);
$loadBalancer->addNodes();

The addNode method accepts three more optional parameters, in addition to the two shown above:

—————– | |  1 | IP address of node | String | Yes | - | |  2 | Port used by node’s service | Integer | Yes | - | |  3 | Starting condition of node: |  4 | Type of node to add: |  5 | Weight, between 1 and 100, given to node when distributing traffic using either the WEIGHTED_ROUND_ROBIN or the WEIGHTED_LEAST_CONNECTIONS load balancing algorithm. | Integer | No | 1 |

Modify Nodes¶

You can modify one or more of the following node attributes:

• condition: The condition of the load balancer:
  • ENABLED – Node is ready to receive traffic from the load balancer.
  • DISABLED – Node should not receive traffic from the load balancer.
  • DRAINING – Node should process any traffic it is already receiving but should not receive any further traffic from the load balancer.
• type: The type of the node:
  • PRIMARY – Nodes defined as PRIMARY are in the normal rotation to receive traffic from the load balancer.
  • SECONDARY – Nodes defined as SECONDARY are only in the rotation to receive traffic from the load balancer when all the primary nodes fail.
• weight: The weight, between 1 and 100, given to node when distributing traffic using either the WEIGHTED_ROUND_ROBIN or the WEIGHTED_LEAST_CONNECTIONS load balancing algorithm.

use OpenCloud\LoadBalancer\Enum\NodeCondition;

$node->update(array(
    'condition' => NodeCondition::DISABLED
));

use OpenCloud\LoadBalancer\Enum\NodeCondition;
use OpenCloud\LoadBalancer\Enum\NodeType;

$node->update(array(
    'condition' => NodeCondition::DISABLED,
    'type'      => NodeType::SECONDARY
));

Remove Nodes¶

There are two ways to remove a node.

$node->delete();

$loadBalancer->removeNode(490639);

View Node Service Events¶

You can view events associated with the activity between a node and a load balancer. An instance of OpenCloud\Common\Collection\PaginatedIterator is returned.

$nodeEvents = $loadBalancer->nodeEventList();
foreach ($nodeEvents as $nodeEvent) {
    /** @var $nodeEvent OpenCloud\LoadBalancer\Resource\NodeEvent **/
}

List Virtual IPs¶

You can list the VIPs associated with a load balancer. An instance of OpenCloud\Common\Collection\PaginatedIterator is returned.

$vips = $loadBalancer->virtualIpList();
foreach ($vips as $vip) {
    /** @var $vip of OpenCloud\LoadBalancer\Resource\VirtualIp **/
}

Add Virtual IPv6¶

You can add additional IPv6 VIPs to a load balancer.

use OpenCloud\LoadBalancer\Enum\IpType;

$loadBalancer->addVirtualIp(IpType::PUBLIC, 6);

The addVirtualIp method, as shown above, accepts the following arguments:

—————– | |  1 | Type of VIP: |  2 | IP version: Must be 6 | Integer | Yes | - |

Remove Virtual IPs¶

You can remove a VIP from a load balancer.

$vip->remove();

Please note that a load balancer must have at least one VIP associated with it. If you try to remove a load balancer’s last VIP, a ClientErrorResponseException will be thrown.

List Load Balancing Algorithms¶

You can list all supported load balancing algorithms using a load balancer service object. An instance of OpenCloud\Common\Collection\PaginatedIterator is returned.

$algorithms = $loadBalancerService->algorithmList();
foreach ($algorithms as $algorithm) {
    /** @var $algorithm OpenCloud\LoadBalancer\Resource\Algorithm **/
}

List Load Balancing Protocols¶

You can list all supported network protocols using a load balancer service object. An instance of OpenCloud\Common\Collection\PaginatedIterator is returned.

$protocols = $loadBalancerService->protocolList();
foreach ($protocols as $protocol) {
    /** @var $protocol OpenCloud\LoadBalancer\Resource\Protocol **/
}

List Session Persistence Configuration¶

$sessionPersistence = $loadBalancer->sessionPersistence();
$sessionPersistenceType = $sessionPersistence->persistenceType;

/** @var $sessionPersistenceType null | 'HTTP_COOKIE' | 'SOURCE_IP' **/

In the example above:

• If session persistence is enabled, the value of $sessionPersistenceType is the type of session persistence: either HTTP_COOKIE or SOURCE_IP.
• If session persistence is disabled, the value of $sessionPersistenceType is null.

Enable Session Persistence¶

$sessionPersistence = $loadBalancer->sessionPersistence();
$sessionPersistence->update(array(
    'persistenceType' => 'HTTP_COOKIE'
));

Disable Session Persistence¶

$sessionPersistence = $loadBalancer->sessionPersistence();
$sessionPersistence->delete();

Check Logging Configuration¶

/** @var $connectionLogging bool **/

$connectionLogging = $loadBalancer->hasConnectionLogging();

In the example above:

• If connection logging is enabled, the value of $connectionLogging is true.
• If connection logging is disabled, the value of $connectionLogging is false.

Enable Connection Logging¶

$loadBalancer->enableConnectionLogging(true);

Disable Connection Logging¶

$loadBalancer->enableConnectionLogging(false);

View Error Page Content¶

$errorPage = $loadBalancer->errorPage();
$errorPageContent = $errorPage->content;

/** @var $errorPageContent string **/

In the example above the value of $errorPageContent is the HTML for that page. This could either be the HTML of the default error page or of your custom error page.

Set Custom Error Page¶

$errorPage = $loadBalancer->errorPage();
$errorPage->update(array(
    'content' => '<HTML content of custom error page>'
));

Delete Custom Error Page¶

$errorPage = $loadBalancer->errorPage();
$errorPage->delete();

List Allowed Domains¶

You can list all allowed domains using a load balancer service object. An instance of OpenCloud\Common\Collection\PaginatedIterator is returned.

$allowedDomains = $loadBalancerService->allowedDomainList();
foreach ($allowedDomains as $allowedDomain) {
    /** @var $allowedDomain OpenCloud\LoadBalancer\Resource\AllowedDomain **/
}

View Access List¶

You can view a load balancer’s access list. An instance of OpenCloud\Common\Collection\PaginatedIterator is returned.

$accessList = $loadBalancer->accessList();
foreach ($accessList as $networkItem) {
    /** @var $networkItem OpenCloud\LoadBalancer\Resource\Access **/
}

Add Network Items To Access List¶

You can add network items to a load balancer’s access list very easily:

$loadBalancer->createAccessList(array(
    (object) array(
        'type'    => 'ALLOW',
        'address' => '206.160.165.1/24'
    ),
    (object) array(
        'type'    => 'DENY',
        'address' => '0.0.0.0/0'
    )
));

In the above example, we allowed access for 1 IP address, and used the “0.0.0.0” wildcard to blacklist all other traffic.

Remove Network Item From Access List¶

You an remove a network item from a load balancer’s access list.

$networkItem->delete();

Check Content Caching Configuration¶

/** @var $contentCaching bool **/

$contentCaching = $loadBalancer->hasContentCaching();

In the example above:

• If content caching is enabled, the value of $contentCaching is true.
• If content caching is disabled, the value of $contentCaching is false.

Enable Content Caching¶

$loadBalancer->enableContentCaching(true);

Disable Content Caching¶

$loadBalancer->enableContentCaching(false);

View current SSL termination config¶

/** @var $sslConfig OpenCloud\LoadBalancer\Resource\SSLTermination **/

$sslConfig = $loadBalancer->SSLTermination();

Update SSL termination config¶

$sslConfig->update(array(
    'enabled'     => true,
    'securePort'  => 443,
    'privateKey'  => $key,
    'certificate' => $cert
));

For a full list, with explanations, of required and optional attributes, please consult the official documentation

Delete SSL termination config¶

$sslConfig->delete();

List metadata¶

$metadataList = $loadBalancer->metadataList();

foreach ($metadataList as $metadataItem) {
    printf("Key: %s, Value: %s", $metadataItem->key, $metadataItem->value);
}

Please consult the iterator documentation for more information about iterators.

Add metadata¶

$metadataItem = $loadBalancer->metadata();
$metadataItem->create(array(
    'key'   => 'foo',
    'value' => 'bar'
));

Modify metadata¶

$metadataItem = $loadBalancer->metadata('foo');
$metadataItem->update(array(
    'value' => 'baz'
));

Remove metadata¶

$metadataItem->delete();

Update or delete¶

// Update
$healthMonitor->update(array(
    'delay'   => 120,
    'timeout' => 60,
    'type'    => 'CONNECT'
    'attemptsBeforeDeactivation' => 3
));

// Delete
$healthMonitor->delete();