Load Balancer
If you want to create a load balancer for your instances, to spread your web traffic between them then you can easily launch a managed load balancer service on Civo. The pricing is described on our pricing page.
Setup a new load balancer
Any user can create a load balancer service to be managed by Civo.com. You should point a CNAME record for the hostname to lb.civo.com. If you are using a root/apex/named domain then you should use the list of IP addresses: 185.136.232.141, 185.136.233.100, 185.136.233.118, 185.136.233.131, 185.136.233.140.
New load balancers are setup by sending a POST request to https://api.civo.com/v2/loadbalancers.
Request
There are no URL parameters, but the following POST parameters should be sent
| Name | Description |
|---|---|
| hostname | the hostname to receive traffic for, e.g. "www.example.com" (optional: sets hostname to loadbalancer-uuid.civo.com if blank) |
| protocol | either http or https. If you specify https then you must also provide the next two fields, the default is "http" |
| tls_certificate | if your protocol is https then you should send the TLS certificate in Base64-encoded PEM format |
| tls_key | if your protocol is https then you should send the TLS private key in Base64-encoded PEM format |
| port | you can listen on any port, the default is "80" to match the default protocol of "http", if not you must specify it here (commonly 80 for HTTP or 443 for HTTPS) |
| max_request_size | the size in megabytes of the maximum request content that will be accepted, defaults to 20 with a minimum of 1 (if specified) and a maximum of 50 |
| policy | one of: least_conn (sends new requests to the least busy server), random (sends new requests to a random backend), round_robin (sends new requests to the next backend in order), ip_hash (sends requests from a given IP address to the same backend), default is "random" |
| health_check_path | what URL should be used on the backends to determine if it's OK (2xx/3xx status), defaults to "/" |
| fail_timeout | how long to wait in seconds before determining a backend has failed, defaults to 30 with a minimum of 1 (if specified) and a maximum of 60 |
| max_conns | how many concurrent connections can each backend handle, defaults to 10 |
| ignore_invalid_backend_tls | should self-signed/invalid certificates be ignored from the backend servers, defaults to true |
| backends | a list of backend instances, each containing an instance_id, protocol (http or https) and port |
Response
The response is a JSON object that confirms the details given.
{
id: "542e9eca-539d-45e6-b629-2f905d0b5f93"
default_hostname: false,
hostname: "www.example.com",
protocol: "https",
port: "443",
max_request_size: 20,
tls_certificate: "...base64-encoded...",
tls_key: "...base64-encoded...",
policy: "random",
health_check_path: "/",
fail_timeout: 30,
max_conns: 10,
ignore_invalid_backend_tls: true,
backends: [
{
instance_id: "82ef8d8e-688c-4fc3-a31c-41746f27b074",
protocol: "http",
port: 3000
}
]
}
Example of creating a load balancer
curl -H "Authorization: bearer 12345" https://api.civo.com/v2/loadbalancers \
-d hostname=test.example.com \
-d backends\[0\]\[instance_id\]=88245f98-905c-428f-97db-c6da8246ca9a \
-d backends\[0\]\[port\]=80 \
-d backends\[0\]\[protocol\]=http// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.post(
'https://api.civo.com/v2/loadbalancers',
{hostname: "test.example.com", backends: [{instance_id: "88245f98-905c-428f-97db-c6da8246ca9a", port: 80, protocol: "http"}]},
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.post('/v2/loadbalancers', 'hostname=test.example.com&' +
'backends[0][instance_id]=88245f98-905c-428f-97db-c6da8246ca9a&' +
'backends[0][port]=80&backends[0][protocol]=http', headers)Updating a load balancer
Updating a load balancer takes exactly the same parameters as setting up a load balancer, but instead the request is a PUT request to https://api.civo.com/v2/loadbalancers/:id.
Request
As per Setup a new load balancer.
Response
As per Setup a new load balancer.
Example of updating a load balancer
curl -X PUT -H "Authorization: bearer 12345" https://api.civo.com/v2/loadbalancers/7b378c32-6695-48b5-9e41-b95519611712 \
-d hostname=test.example.com \
-d backends[1][instance_id]=88245f98-905c-428f-97db-c6da8246ca9a \
-d backends[1][port]=80 \
-d backends[1][protocol]=http// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.put(
'https://api.civo.com/v2/loadbalancers/7b378c32-6695-48b5-9e41-b95519611712',
{hostname: "test.example.com", backends: [{instance_id: "88245f98-905c-428f-97db-c6da8246ca9a", port: 80, protocol: "http"}]},
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.put('/v2/loadbalancers/7b378c32-6695-48b5-9e41-b95519611712', 'hostname=test.example.com&' +
'backends[1][instance_id]=88245f98-905c-428f-97db-c6da8246ca9a&' +
'backends[1][port]=80&backends[1][protocol]=http', headers)List load balancers
A list of all load balancers within your account are available by sending a GET request to https://api.civo.com/v2/loadbalancers.
Request
This request takes no parameters.
Response
The response is a JSON array of objects that describes each load balancer.
[
{
id: "542e9eca-539d-45e6-b629-2f905d0b5f93"
hostname: "www.example.com",
protocol: "https",
port: "443",
max_request_size: 20,
tls_certificate: "...base64-encoded...",
tls_key: "...base64-encoded...",
policy: "random",
health_check_path: "/",
fail_timeout: 30,
max_conns: 10,
ignore_invalid_backend_tls: true,
backends: [
{
instance_id: "82ef8d8e-688c-4fc3-a31c-41746f27b074",
protocol: "http",
port: 3000
}
]
}
]Example of listing load balancers
curl -H "Authorization: bearer 12345" https://api.civo.com/v2/loadbalancers// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.get(
'https://api.civo.com/v2/loadbalancers',
{},
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.get('/v2/loadbalancers', headers)Deleting a load balancer
An account holder can remove a load balancer, which will within one minute stop serving traffic for that hostname.
Request
This request takes no parameters except the ID of the load balancer to delete is in the URL. No confirmation step is required, this step will remove the load balancer.
Response
The response from the server will be a JSON block. The response will include a result field and the HTTP status will be 200 OK.
{
"result": "success"
}Example of deleting a load balancer
curl -H "Authorization: bearer 12345" \
-X DELETE https://api.civo.com/v2/loadbalancers/dc9ffcf8-c2ff-4c38-b297-30f790cf56fa// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.del(
'https://api.civo.com/v2/loadbalancers/dc9ffcf8-c2ff-4c38-b297-30f790cf56fa',
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.delete('/v2/loadbalancers/dc9ffcf8-c2ff-4c38-b297-30f790cf56fa', headers)