Load Balancers
==============

A **load balancer** is a device that distributes incoming network
traffic amongst multiple back-end systems. These back-end systems are
called the **nodes** of the load balancer.

Getting started
---------------

1. Instantiate a Rackspace client.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: php


    use OpenCloud\Rackspace;

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

2. Retrieve the server instances you want to add as nodes of the load balancer.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: php

    $computeService = $client->computeService('cloudServersOpenStack', 'DFW');

    $serverOne = $computeService->server('e836fc4e-056d-4447-a80e-fefcaa640216');
    $serverTwo = $computeService->server('5399cd36-a23f-41a6-bdf7-20902aec0e74');

The example above uses two server instances that have already been
created. It retrieves the server instances using their IDs. See also:
`creating server instances <>`__.

3. Obtain a Load Balancer service object from the client.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This object will be used to first define the load balancer nodes and
later create the load balancer itself.

.. code:: php

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

4. Define a load balancer node for each server.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: php

    $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';

In the example above, each node runs a service that listens on port
8080. Further, each node will start out as ``ENABLED``, which means it
will be ready to receive network traffic from the load balancer as soon
as it is created.

5. Create the load balancer with the two nodes.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: php

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

In the example above, the load balancer will have a virtual IP address
accessible from the public Internet. Also notice that the port the load
balancer listens on (80) does not need to match the ports of its nodes
(8080).

Next steps
----------

Once you have created a load balancer, there is a lot you can do with
it. See the `complete user guide for load balancers <USERGUIDE.md>`__.
