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 |
Instance usage¶
Field |
Explanation |
|---|---|
name |
Name of the instance |
id |
Instance id |
stats |
A set of three values:
|
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, …]
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
- Has Token
No
Create interface to the virtual machine.
Get Bandwidth stats from balancer¶
- Method
GET
- Url
/balancer/<id>/bw_stats
- Success Code
200
- Returned Data
- 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
- 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
- Has Token
No
Activate segregation
Delete segregation from balancer¶
- Method
DELETE
- Url
/balancer/<origin_id>/segregation/<target_id>
- Success Code
200
- Returned Data
- Has Token
No
Deactivate segregation
List balancers¶
- Method
GET
- Url
/account/<account_id>/balancers
- Success Code
200
- Returned Data
- Has Token
No
Get the list of user’s balancers
Edit Balancer’s Virtual Machine¶
- Method
PUT
- Url
/account/<account_id>/balancer/<virtual_machine_id>/vm
- Success Code
200
- Returned Data
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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 is 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
- 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
- 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
- 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
- Has Token
No
List backend resources
Filters:
ip_address
port
name
weight
minconn
maxconn
check_interval
Add Virtual IP¶
- Method
POST
- Url
/account/<account_id>/balancer_virtual_ip
- Success Code
201
- Returned Data
- 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
- Has Token
No
List all virtual ips
Parameters:
ip_address