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

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
• Node.js
• Ruby

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
• Node.js
• Ruby

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
• Node.js
• Ruby

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 202 Accepted.

{
  "result": "success"
}

Example of deleting a load balancer

• Curl
• Node.js
• Ruby

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)