API

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