Guides - Configure NodeBalancers with the Linode 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.

Note

You need a Personal Access Token for the Linode API to complete the steps in this guide. See Manage Personal Access Tokens for more information.

1. Store your Personal Access Token as a shell variable:

   export TOKEN=<token-string>

2. 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 }

3. 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

4. If the NodeBalancer is successfully created, the response will include its ID. Copy the ID to use in subsequent requests.

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.

1. Create a new configuration file:

   File: nodebalancer-config.json

   1 2 3 4 5

   { "label": "nodebalancer-1", "port": 80, "check": "connection" }

2. 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

Note

For more information about configuration options, see our NodeBalancer Reference Guide.

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.

1. 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 }

2. 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.

3. 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 }

4. 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

5. Boot the Compute Instance:

   curl -X POST https://api.linode.com/v4/linode/instances/$LINODE_ID/boot \
   -H "Authorization: Bearer $TOKEN"

Add the new Compute Instances as backends to the NodeBalancer.

1. 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" }

2. 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

3. Repeat this process for each additional backend.

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.

NodeBalancers can also be configured to use HTTPS. You will need to have a TLS certificate before enabling this option.

1. 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.

2. 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.

3. 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.

• Getting Started with NodeBalancers