Load Balancers

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
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
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[1][instance_id]=88245f98-905c-428f-97db-c6da8246ca9a \
  -d backends[1][port]=80 \
  -d backends[1][protocol]=http

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

http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/loadbalancers', 'hostname=test.example.com&' +
  'backends[1][instance_id]=88245f98-905c-428f-97db-c6da8246ca9a&' +
  'backends[1][port]=80&backends[1][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

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

http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  '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

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

http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  '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 202 Accepted.

{
  "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

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

http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/loadbalancers/dc9ffcf8-c2ff-4c38-b297-30f790cf56fa', headers)