Guides - Configure NodeBalancers with the Linode API
Programmatic access to the Linode platform, allowing you to automate tasks through a fully-documented REST API.
NodeBalancers can be used to provide high availability load balancing for almost any type of website or service hosted on a Compute Instance. This guide will demonstrate how to use the Linode API to create a NodeBalancer with two back end nodes.
Create a NodeBalancer
Store your Personal Access Token as a shell variable:
export TOKEN=<token-string>
Using a text editor, create a file to store configuration options:
- File: nodebalancer.json
1 2 3 4 5
{ "region": "us-central", "label": "nodebalancer-1", "client_conn_throttle": 10 }
Create a NodeBalancer by making a POST request to the
/nodebalancers
endpoint:curl https://api.linode.com/v4/nodebalancers \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -X POST -d @nodebalancer.json
If the NodeBalancer is successfully created, the response will include its ID. Copy the ID to use in subsequent requests.
Add Configuration
NodeBalancers are created without any configuration profiles attached. Each profile configures a single port on the NodeBalancer. Once the port is configured, the NodeBalancer will begin listening for traffic on that port.
Create a new configuration file:
- File: nodebalancer-config.json
1 2 3 4 5
{ "label": "nodebalancer-1", "port": 80, "check": "connection" }
Substitute the NodeBalancer’s ID into the URL below:
curl https://api.linode.com/v4/nodebalancers/$NODEBALANCER_ID/configs \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -X POST -d @nodebalancer-config.json
Add Backend Compute Instances
Even with a working configuration profile, the NodeBalancer isn’t doing anything yet, since it has no backends connected to it. Repeat the steps in this section for each backend you would like to add; usually you will want at least two.
Create Compute Instances
Add the following options to a new config file. Adjust the type, image, and region to suit your needs; make sure the new Compute Instance is in the same region as your NodeBalancer and choose a secure root password.
- File: create-instance.json
1 2 3 4 5 6 7
{ "region": "us-central", "type": "g5-standard-2", "image": "linode/debian9", "root_pass": "password", "booted": false }
Use the API to create the instance:
curl https://api.linode.com/v4/linode/instances/ \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -X POST -d @create-instance.json
Make a note of the new Linode’s ID.
Add configuration options for adding a private IPv4 address:
- File: ip-address.json
1 2 3 4 5
{ "type": "ipv4", "public": false, "linode_id": 7449584 }
Add a private IP address to the new instance:
curl https://api.linode.com/v4/networking/ips \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -X POST -d @ip-address.json
Boot the Compute Instance:
curl -X POST https://api.linode.com/v4/linode/instances/$LINODE_ID/boot \ -H "Authorization: Bearer $TOKEN"
Add Backends to the NodeBalancer
Add the new Compute Instances as backends to the NodeBalancer.
Add configuration options for each backend. Substitute the private IP address of the Compute Instance into the
address
field and give each backend a unique label.- File: add-node.json
1 2 3 4
{ "label": "node-1", "address": "$node-private-ip:80" }
Use the
/nodes
endpoint to add these backends:curl https://api.linode.com/v4/nodebalancers/$NODEBALANCER_ID/configs/$CONFIG_ID \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -X POST -d @add-node.json
Repeat this process for each additional backend.
Check Backend Status
Check the status of the two backend nodes:
curl https://api.linode.com/v4/nodebalancers/$NODEBALANCER_ID/configs/$CONFIG_ID \
-H "Authorization: Bearer $TOKEN"
. . .
"nodes_status": {
"up": 0,
"down": 2
},
. . .
Both backends are down because there is no process for the NodeBalancer to connect to on the designated port. As a demonstration, a basic install of NGINX will listen on port 80 automatically. SSH into each Compute Instance and install NGINX:
apt update && apt upgrade && apt install nginx
If you check the NodeBalancer config again, it should report that both backends are now up. You can also navigate to the NodeBalancer’s public IP address in a browser; the default NGINX landing page should be displayed.
Configure HTTPS
NodeBalancers can also be configured to use HTTPS. You will need to have a TLS certificate before enabling this option.
If you do not have an existing TLS certificate, generate a self-signed certificate using OpenSSL:
openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out MyCertificate.crt -keyout MyKey.key
Note Provide values for country name, common name, etc. when prompted. The Linode API will reject the certificate if these are left blank.Edit your
nodebalancer-config.json
configuration file:- File: nodebalancer-config.json
1 2 3 4 5 6
{ "protocol":"https", "port": 443, "ssl_cert": "-----BEGIN CERTIFICATE-----\nCERTIFICATE_INFORMATION\n-----END CERTIFICATE-----", "ssl_key": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY_INFORMATION\n-----END PRIVATE KEY-----" }
Note Line breaks in SSL certificate and private key strings must be represented by\n
.Use a PUT request to update your NodeBalancer’s configuration:
curl -X PUT https://api.linode.com/v4/nodebalancers/$NODEBALANCER_ID/configs/$CONFIG_ID \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d @nodebalancer-config.json
More Information
You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.
This page was originally published on