Load balancing

A “Balancer” is the virtual machine, while the “instance” is a single IP:PORT configuration listening for requests in that physical server.

Entities

Balancer

Balancer resource:

Field Explanation
id identifier
user_id user identifier
status online | offline | unbuilt

Balancer list:

[balancer resource 1, balancer resource 2, ...]

Instance

Field Explanation
id identifier
label instance label
ip_address instance ip address
port instance port
algorithm define the load balancing algorithm to be used in a backend: leastconn (default), roundrobin or source
hash-type specify a method to use for mapping hashes to servers: map-based (default) or consistent
mode set the running mode or protocol of the instance: http (default) or tcp
cookie Enable cookie-based persistence in a backend (use it in conjunction with http mode)
status instance’s status

Balancer usage

Field Explanation
instances balancer usage instance resource

Instance usage

Field Explanation
name Name of the instance
id Instance id
stats

A set of three values:

  • period related data:

    • date start (UNIX timestamp)
    • date end (UNIX timestamp)
    • interval
  • statistical data names

  • statistical data

Instance list:

[instance resource 1, instance resource 2, ...]

Backend

Backend resource:

Field Explanation
id backend identifier
name backend name (thin by default)
ip_address backend’s ip address
port backend’s port,
weight used to adjust the server’s weight relative to other servers [1-100]
minconn minimal number of concurrent connections that will be accepted by this server [1-20000]
maxconn maximal number of concurrent connections that will be sent to this server [1-20000]
check_interval sets the interval in miliseconds between two consecutive health checks on the server
instance_id instance’s id

Note

if set, minconn can’t be higher than maxconn

Backend resource list:

[backend resource 1, backend resource 2, ...]

Failover

Failover resource:

Field Explanation
id failover identifier
balancer_id balancer id
ha_status on/off

Failover list:

[failover resource 1, failover resource 2, ...]

Balancer Virtual IP

Virtual IP resource:

Field Explanation
id Virtual ip identifier
ip address Ip address

Virtual IP list:

[virtualip resource 1, virtualip resource 2, ...]

Operations

Create interface from balancer

Method:POST
Url:/balancer/<id>/network_interface
Success Code:200
Returned Data:Network interface resource list
Has Token:No

Create interface to the virtual machine.

Reboot Balancer Failover

Method:POST
Url:/balancer_failover/([0-9]+)/reboot
Success Code:202
Returned Data:Failover balancer resource
Has Token:Yes

Restart the load balancer failover’s virtual server

Edit Balancer Failover

Method:PUT
Url:/balancer_failover/<id>/vm
Success Code:200
Returned Data:Balancer resource
Has Token:No

Edit the underlying virtual machine of the balancer

Parameters:

  • label: user-friendly VM description
  • note: user notes for the vm
  • status: (‘online’, ‘offline’, ‘recovery’)
  • force: to do hard shutdown

Get Bandwidth stats from balancer

Method:GET
Url:/balancer/<id>/bw_stats
Success Code:200
Returned Data:balancer usage resource
Has Token:No

Bandwith Stats for a given balancer.

Get CPU stats from balancer

Method:GET
Url:/balancer/<id>/cpu_stats
Success Code:200
Returned Data:balancer usage resource
Has Token:No

CPU Stats for a given balancer.

Put segregation from balancer

Method:PUT
Url:/balancer/<origin_id>/segregation/<target_id>
Success Code:200
Returned Data:balancer usage resource
Has Token:No

Activate segregation

Delete segregation from balancer

Method:DELETE
Url:/balancer/<origin_id>/segregation/<target_id>
Success Code:200
Returned Data:balancer usage resource
Has Token:No

Deactivate segregation

List balancers

Method:GET
Url:/account/<account_id>/balancers
Success Code:200
Returned Data:Balancer resource list
Has Token:No

Get user’s balancers

Get balancer

Method:GET
Url:/account/<account_id>/balancer/<instance_id>
Success Code:200
Returned Data:Balancer resource
Has Token:No

Get a balancer resource

Edit Balancer’s Virtual Machine

Method:PUT
Url:/account/<account_id>/balancer/<virtual_machine_id>/vm
Success Code:200
Returned Data:Balancer resource
Has Token:No

Edit the underlying virtual machine of the balancer

Parameters:

  • label: user-friendly VM description
  • note: user notes for the vm
  • status: (‘online’, ‘offline’)

Start/Stop balancer

Method:PUT
Url:/account/<account_id>/balancer/<virtual_machine_id>/vm
Success Code:202
Returned Data:Load balancer resource
Has Token:Yes

Turn on/off the load balancer’s virtual server

Mandatory parameters:

  • status: online/offline.

Activate/deactivate instance

Method:PUT
Url:/account/<account_id>/balancer/<virtual_machine_id>/vm
Success Code:200
Returned Data:Instance resource
Has Token:No

Turn on/off an instance

Mandatory Parameters:

  • status: on/off

Reboot Balancer

Method:POST
Url:/account/<account_id>/balancer/<virtual_machine_id>/reboot
Success Code:202
Returned Data:Load balancer resource
Has Token:Yes

Restart the load balancer’s virtual server

Rebuild network

Method:POST
Url:/account/<account_id>/balancer/<virtual_machine_id>/rebuild_network
Success Code:202
Returned Data:Load balancer resource
Has Token:Yes

Rebuild the network to apply changes

Get interfaces from balancer

Method:GET
Url:/account/<account_id>/balancer/([0-9]+)/network_interfaces
Success Code:200
Returned Data:Network interface resource list
Has Token:No

List interfaces attached to the virtual machine.

Add instance

Method:POST
Url:/account/<account_id>/balancer_instance
Success Code:201
Returned Data:Instance resource
Has Token:No

Create a new instance on a balancer

Mandatory parameters:

  • balancer_id: balancer on which the instance will be built
  • label: instance description
  • ip_address: ip address where instance listens
  • port: port where the instance listens.

Optional parameters:

  • algorithm: Strategy to follow when balancing
  • hash-type: should it be hash-type consistent?
  • mode: TCP/HTTP
  • cookie: Cookie Jsession
  • vlan_id: Vlan on wich it listens to
  • http-server-close
  • http-keep-alive

List instances

Method:GET
Url:/account/<account_id>/balancer_instances
Success Code:200
Returned Data:Instance list
Has Token:No

List all the instances created.

Filters:

  • balancer_id
  • port
  • label
  • ip_address

Modify instance

Method:PUT
Url:/account/<account_id>/balancer_instance/<instance_id>
Success Code:200
Returned Data:Instance resource
Has Token:No

Changes configuration of target balancer instance.

Parameters:

  • label: instance description
  • ip_address: ip address where instance listens
  • port: port where the instance listens.
  • algorithm: Strategy to follow when balancing
  • hash-type: should it be hash-type consistent?
  • mode: TCP/HTTP
  • cookie: Cookie Jsession
  • http-server-close
  • http-keep-alive

Extra operation:

Optionally can create backends, but this operation will erase previous backend on the balancer for change the instance and create backends at the same time you have to add backend parameters:

  • backend_ip_address: ip address where the backend listens
  • backend_port: port where the backend listens
  • backend_name: name of the backend
  • backend_weight: priority of the backend
  • backend_minconn: minimum number of connections
  • backend_maxconn: maximum number of connections
  • backend_check_interval: time between checks

if we send this this struct multiple times we will create multiple backend

Note

To apply the changes in the instance you must use the call rebuild instance configuracion.

Get instance

Method:GET
Url:/account/<account_id>/balancer_instance/<instance_id>
Success Code:200
Returned Data:Instance resource
Has Token:No

Get a balancer instance resource.

Delete instance

Method:DELETE
Url:/account/<account_id>/balancer_instance/<instance_id>
Success Code:204
Returned Data:No data returned
Has Token:No

Destroys target balancer instance

Rebuild instance configuration

Method:POST
Url:/account/<account_id>/balancer_instance/<instance_id>/rebuild_config
Success Code:202/200
Returned Data:Instance resource
Has Token:Yes

Rebuild the configuration in the balancer.

You must use this call to apply the changes made in a balancer instance configuration.

If the balancer or the failover are booted, it will return a 202 code and the response will include a queue token.

Add backend

Method:POST
Url:/account/<account_id>/balancer_instance/<instance_id>/backend
Success Code:201
Returned Data:Backend resource
Has Token:No

Mandatory parameters:

  • ip_address: ip address where the backend listens
  • port: port where the backend listens

Optional parameters:

  • name: name of the backend
  • weight: priority of the backend
  • minconn: minimum number of connections
  • maxconn: maximum number of connections
  • check_interval: time between checks

Note

To apply the changes in the instance you must use the call rebuild instance configuracion.

Get backend

Method:GET
Url:/account/<account_id>/balancer_instance/<instance_id>/backend/<backend_id>
Success Code:200
Returned Data:Backend resource
Has Token:No

Get a backend resource

Edit backend

Method:PUT
Url:/account/<account_id>/balancer_instance/<instance_id>/backend/<backend_id>
Success Code:200
Returned Data:Backend resource
Has Token:No

Change a backend details

Parameters:

  • ip_address: ip address where the backend listens
  • port: port where the backend listens
  • name: name of the backend
  • weight: priority of the backend
  • minconn: minimum number of connections
  • maxconn: maximum number of connections
  • check_interval: time between checks

Note

To apply the changes in the instance you must use the call rebuild instance configuracion.

Delete backend

Method:DELETE
Url:/account/<account_id>/balancer_instance/<instance_id>/backend/<backend_id>
Success Code:204
Returned Data:No data returned
Has Token:No

Remove a backend

Note

To apply the changes in the instance you must use the call rebuild instance configuracion.

List backends

Method:GET
Url:/account/<account_id>/balancer_instance/<instance_id>/backends
Success Code:200
Returned Data:Backend resource list
Has Token:No

List backend resources

Filters:

  • ip_address
  • port
  • name
  • weight
  • minconn
  • maxconn
  • check_interval

List failovers

Method:GET
Url:/account/<account_id>/balancer_failovers
Success Code:200
Returned Data:Failover resource list
Has Token:No

Get failover resources

Filters:

  • balancer_id
  • status

Add Virtual IP

Method:POST
Url:/account/<account_id>/balancer_virtual_ip
Success Code:201
Returned Data:Virtual IP resource
Has Token:No

Mandatory parameters:

  • balancer_id

Optional parameters:

  • account_id
  • qty: 1..5

Delete Virtual IP

Method:DELETE
Url:/account/<account_id>/balancer_virtual_ip/<vip_id>
Success Code:204
Returned Data:No data returned
Has Token:No

Get Virtual IP

Method:GET
Url:/account/<account_id>/balancer_virtual_ip/<vip_id>
Success Code:204
Returned Data:No data returned
Has Token:No

Get a virtual ip

List Virtual IP

Method:GET
Url:/account/<account_id>/balancer_virtual_ips
Success Code:200
Returned Data:Virtual IP list
Has Token:No

List all virtual ips

Parameters:

  • ip_address

Get stats from balancer

Method:GET
Url:/account/<account_id>/balancer/<balancer_id>/stats
Success Code:200
Returned Data:balancer usage resource
Has Token:No

Stats for a given balancer.

Mandatory parameters:

  • period: period reported. Accepted values: -60min for one hour, -1M for one month.

Example:

{
    "instances": [
        {
            "stats": [
                [
                    1411862400,
                    1414540800,
                    86400
                ],
                [
                    "balancer_sessions",
                    "failover_sessions",
                    "sessions"
                ],
                [
                    [
                        1,
                        0,
                        1
                    ],
                    [
                        5,
                        0,
                        5
                    ],
                    [
                        12,
                        0,
                        12
                    ],
                    [
                        0,
                        0,
                        0
                    ],
                    [
                        0,
                        0,
                        0
                    ],
                    [
                        0,
                        0,
                        0
                    ],
                    [
                        0,
                        0,
                        0
                    ],
                    [
                        0,
                        0,
                        0
                    ],
                    [
                        0,
                        0,
                        0
                    ],
                    [
                        0,
                        0,
                        0
                    ],
                    [
                        0,
                        0,
                        0
                    ],
                    [
                        0,
                        0,
                        0
                    ]
                ]
            ],
            "name": "ochenta",
            "id": 190
        },
        {
            "stats": "",
            "name": "ochentayuno",
            "id": 191
        },
        {
            "stats": "",
            "name": "noventa",
            "id": 192
        }
    ],
    "balancer_id": 1103
}