| --- |
| site_name: Deltacloud API |
| title: Load balancers |
| --- |
| |
| <br/> |
| |
| <div class="alert alert-info"> |
| <a class="close" data-dismiss="alert" href="#">×</a> |
| This section is currently being updated. |
| </div> |
| |
| <div class="row"> |
| <div class="span8"> |
| |
| <h3 id="load">Load balancers</h3> |
| |
| <p> |
| Load balancers allow distribution of ingress network traffic received by a specified IP address to a number of running instances. For example, a number of instances that are fulfilling the role of web servers can be attached to a single load_balancer. It allows you to handle a large number of requests without influence on website performance. |
| </p> |
| |
| <p> |
| This collection is not supported by all back-end cloud providers and at present, it is implemented for the Gogrid and Amazon EC2 cloud drivers. A load_balancer is launched into a specific realm and typically only instances within this realm may be 'attached' to the balancer. Each load_balancer also has a <strong>list of instances</strong>, a <strong>public address</strong> representing the IP address that the balancer will respond on to client requests, a <strong>created_at</strong> timestamp and a list of <strong>listeners</strong>. Each <strong>listener</strong> has a <strong>protocol</strong> (e.g. TCP), a <strong>load balancer port</strong> and an <strong>instance port</strong>. The load balancer represents the port on which the balancer accepts connections. The instance port represents the port on which network traffic is forwarded to instances in the <strong>instance list</strong>. |
| </p> |
| |
| <h4>Get a list of all buckets</h4> |
| |
| <p> |
| To retrieve details of all load_balancers use call <strong>GET /api/load_balancers</strong>. |
| </p> |
| |
| </div> |
| <div class="span4"> |
| |
| <ul class="nav nav-list well"> |
| <li class="nav-header"> |
| REST API |
| </li> |
| <li><a href="/rest-api.html">Introduction</a></li> |
| <li><a href="/api-entry-point.html">API entry point</a></li> |
| <li><a href="/compute-resources.html">Compute resources</a></li> |
| <ul class="nav nav-list"> |
| <li><a href="/realms.html">Realms</a></li> |
| <li><a href="/hardware-profiles.html">Hardware profiles</a></li> |
| <li><a href="/images.html">Images</a></li> |
| <li><a href="/instance-states.html">Instance states</a></li> |
| <li><a href="/instances.html">Instances</a></li> |
| <li><a href="/keys.html">Keys</a></li> |
| <li><a href="/firewalls.html">Firewalls</a></li> |
| <li><a href="/addresses.html">Addresses</a></li> |
| <li class="active"><a href="#load">Load balancers</a></li> |
| </ul> |
| <li><a href="/storage-resources.html">Storage resources</a></li> |
| </ul> |
| |
| </div> |
| </div> |
| |
| <ul class="nav nav-pills"> |
| <li class="active"><a href="#tab1" data-toggle="tab">Get details</a></li> |
| <li><a href="#tab2" data-toggle="tab">Get the deteails of an address</a></li> |
| <li><a href="#tab3" data-toggle="tab">Create/delete an address</a></li> |
| <li><a href="#tab4" data-toggle="tab">Associate/disassociate an address</a></li> |
| </ul> |
| |
| <div class="tab-content"> |
| <div class="tab-pane active" id="tab1"> |
| |
| |
| <h4>Get a list of all buckets</h4> |
| |
| <p> |
| To retrieve details of all load_balancers use call <strong>GET /api/load_balancers</strong>. |
| </p> |
| |
| <p> |
| Example request: |
| </p> |
| |
| <pre> |
| GET /api/load_balancers?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3001 |
| Accept: */* |
| </pre> |
| |
| <p>Server response:</p> |
| |
| <pre> |
| HTTP/1.1 200 OK |
| Content-Type: application/xml |
| Date: Thu, 28 Jul 2011 13:37:19 GMT |
| Content-Length: 1844 |
| |
| <?xml version='1.0' encoding='utf-8' ?> |
| <load_balancers> |
| <load_balancer href='http://localhost:3001/api/load_balancers/webtraffic-balancer' id='webtraffic-balancer'> |
| <actions> |
| <link href='http://localhost:3001/api/load_balancers/webtraffic-balancer' method='delete' rel='destroy' /> |
| <link href='http://localhost:3001/api/load_balancers/webtraffic-balancer/register' method='post' rel='register' /> |
| </actions> |
| <public_addresses> |
| <address>webtraffic-balancer-1306196965.us-east-1.elb.amazonaws.com</address> |
| </public_addresses> |
| <created_at>Thu Jul 28 13:29:52 UTC 2011</created_at> |
| <realm href='http://localhost:3001/api/realms/us-east-1a' id='us-east-1a'></realm> |
| <listeners> |
| <listener protocol='HTTP'> |
| <load_balancer_port>80</load_balancer_port> |
| <instance_port>3001</instance_port> |
| </listener> |
| </listeners> |
| <instances> |
| </instances> |
| </load_balancer> |
| <load_balancer href='http://localhost:3001/api/load_balancers/secure-site-balancer' id='secure-site-balancer'> |
| <actions> |
| <link href='http://localhost:3001/api/load_balancers/secure-site-balancer' method='delete' rel='destroy' /> |
| <link href='http://localhost:3001/api/load_balancers/secure-site-balancer/register' method='post' rel='register' /> |
| </actions> |
| <public_addresses> |
| <address>secure-site-balancer-1347100846.us-east-1.elb.amazonaws.com</address> |
| </public_addresses> |
| <created_at>Thu Jul 28 13:36:29 UTC 2011</created_at> |
| <realm href='http://localhost:3001/api/realms/us-east-1a' id='us-east-1a'></realm> |
| <listeners> |
| <listener protocol='HTTP'> |
| <load_balancer_port>443</load_balancer_port> |
| <instance_port>443</instance_port> |
| </listener> |
| </listeners> |
| <instances> |
| </instances> |
| </load_balancer> |
| </load_balancers> |
| </pre> |
| |
| <h4>Get the details for a load balancer</h4> |
| |
| <p>To retrieve details for a specific load balancer use call <strong>GET /api/load_balancers/:id</strong>.</p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| GET /api/load_balancers/secure-site-balancer?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3001 |
| Accept: */* |
| </pre> |
| |
| <p>Server response:</p> |
| |
| <pre> |
| HTTP/1.1 200 OK |
| Content-Type: application/xml |
| Date: Thu, 28 Jul 2011 18:11:49 GMT |
| Content-Length: 1361 |
| |
| <?xml version='1.0' encoding='utf-8' ?> |
| <load_balancer href='http://localhost:3001/api/load_balancers/secure-site-balancer' id='secure-site-balancer'> |
| <actions> |
| <link href='http://localhost:3001/api/load_balancers/secure-site-balancer' method='delete' rel='destroy' /> |
| <link href='http://localhost:3001/api/load_balancers/secure-site-balancer/register' method='post' rel='register' /> |
| </actions> |
| <public_addresses> |
| <address>secure-site-balancer-1347100846.us-east-1.elb.amazonaws.com</address> |
| </public_addresses> |
| <created_at>Thu Jul 28 13:36:29 UTC 2011</created_at> |
| <realm href='http://localhost:3001/api/realms/us-east-1a' id='us-east-1a'></realm> |
| <listeners> |
| <listener protocol='HTTP'> |
| <load_balancer_port>443</load_balancer_port> |
| <instance_port>443</instance_port> |
| </listener> |
| </listeners> |
| <instances> |
| <instance href='http://localhost:3001/api/instances/i-4f06b52e' id='i-4f06b52e'> |
| <link href='http://localhost:3001/api/load_balancers/secure-site-balancer/unregister?instance_id=i-4f06b52e' rel='unregister' /> |
| </instance> |
| <instance href='http://localhost:3001/api/instances/i-d706b5b6' id='i-d706b5b6'> |
| <link href='http://localhost:3001/api/load_balancers/secure-site-balancer/unregister?instance_id=i-d706b5b6' rel='unregister' /> |
| </instance> |
| </instances> |
| </load_balancer> |
| </pre> |
| |
| <h4>Create a load balancer</h4> |
| |
| <p> |
| To create a new load_balancer use call <strong>POST /api/load_balancers</strong>. Clients must provide the load_balancer <strong>name</strong>, the <strong>realm_id</strong> to which the balancer is applied, a <strong>listener_protocol</strong> which the balancer will respond to (one of <strong>HTTP</strong> or <strong>TCP</strong>), the <strong>listener_balancer_port</strong> which specifies the port that the load_balancer will be expecting network traffic on and finally the <strong>listener_instance_port</strong> which specifies the port on which instances will be receiving network traffic forwarded by the load_balancer. As with other operations in the Deltacloud API, parameters may be specified by a requesting client using multipart/form-data or as application/x-www-form-urlencoded data. |
| </p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| OST /api/load_balancers?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3001 |
| Accept: */* |
| Content-Length: 121 |
| Content-Type: application/x-www-form-urlencoded |
| |
| name=webtraffic-balancer&realm_id=us-east-1c&listener_protocol=HTTP& |
| listener_balancer_port=80&listener_instance_port=3001 |
| </pre> |
| |
| <p>Server response:</p> |
| |
| <pre> |
| HTTP/1.1 201 Created |
| Content-Type: application/xml |
| Date: Thu, 28 Jul 2011 13:30:05 GMT |
| Content-Length: 884 |
| |
| <?xml version='1.0' encoding='utf-8' ?> |
| <load_balancer href='http://localhost:3001/api/load_balancers/webtraffic-balancer' id='webtraffic-balancer'> |
| <actions> |
| <link href='http://localhost:3001/api/load_balancers/webtraffic-balancer' method='delete' rel='destroy' /> |
| <link href='http://localhost:3001/api/load_balancers/webtraffic-balancer/register' method='post' rel='register' /> |
| </actions> |
| <public_addresses> |
| <address>webtraffic-balancer-1306196965.us-east-1.elb.amazonaws.com</address> |
| </public_addresses> |
| <created_at>Thu Jul 28 13:29:52 UTC 2011</created_at> |
| <realm href='http://localhost:3001/api/realms/us-east-1a' id='us-east-1a'></realm> |
| <listeners> |
| <listener protocol='HTTP'> |
| <load_balancer_port>80</load_balancer_port> |
| <instance_port>3001</instance_port> |
| </listener> |
| </listeners> |
| <instances> |
| </instances> |
| </load_balancer> |
| </pre> |
| |
| <h4>Delete a load balancer</h4> |
| |
| <p>To delete the specified load_balancer from the back-end cloud provider use call <strong>DELETE /api/load_balancers/:id</strong>. The Deltacloud server will respond with <strong>HTTP 204 No Content</strong> for a succesful operation:</p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| DELETE /api/load_balancers/webtraffic-balancer?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3001 |
| Accept: */* |
| </pre> |
| |
| <p>Server response:</p> |
| |
| <pre> |
| HTTP/1.1 204 No Content |
| Date: Thu, 28 Jul 2011 13:23:33 GMT |
| </pre> |
| |
| <h4>Register an instance with a load balancer</h4> |
| |
| <p> |
| To register a running instance with a specified load_balancer use call <strong>POST /api/load_balancers/:id/register</strong>. Clients must provide the <strong>instance_id</strong> as a parameter to the request. The Deltacloud server will respond with a <strong>HTTP 204 No Content</strong> after a succesful operation. The Deltacloud server will accept client request parameters encoded as multipart/form-data or as application/x-www-form-urlencoded data. |
| </p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| POST /api/load_balancers/secure-site-balancer/register?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3001 |
| Accept: */* |
| Content-Length: 22 |
| Content-Type: application/x-www-form-urlencoded |
| |
| instance_id=i-4f06b52e |
| </pre> |
| |
| Server response: |
| |
| <pre> |
| HTTP/1.1 204 No Content |
| Date: Thu, 28 Jul 2011 18:20:03 GMT |
| </pre> |
| |
| <h4>Unreagister an instance from a load balancer</h4> |
| |
| <p> |
| To unregister a specified instance from the given load_balancer use call <strong>POST /api/load_balancers/:id/unregister</strong>. The client must supply the <strong>instance_id</strong> parameter to identify the instance, either as multipart/form-data or as application/x-www-form-urlencoded data. |
| </p> |
| |
| <p>Example request:</p> |
| |
| <pre> |
| POST /api/load_balancers/secure-site-balancer/unregister?format=xml HTTP/1.1 |
| Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== |
| User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) |
| Host: localhost:3001 |
| Accept: */* |
| Content-Length: 22 |
| Content-Type: application/x-www-form-urlencoded |
| |
| instance_id=i-4f06b52e |
| </pre> |
| |
| <p>Server response:</p> |
| |
| <pre> |
| HTTP/1.1 204 No Content |
| Date: Thu, 28 Jul 2011 19:09:17 GMT |
| </pre> |
| |
| <a class="btn btn-inverse btn-large" style="float: right" href="/storage-resources.html">Storage resources <i class="icon-arrow-right icon-white" style="vertical-align:baseline"> </i></a> |
| |
| <br/> |
