Getting started with load balancers

A Nextify load balancer gives your service one public IPv4 address and spreads its traffic across your instances. It terminates HTTPS with certificates it gets and renews by itself, checks the health of every instance, and reaches the instances over your private network, so they need no public address of their own.

This guide sets one up for a website or API, then covers health checks, routing rules and the API. It takes about ten minutes, most of it waiting for DNS.

Before you start

• Instances to put behind it. One or more instances in the region, on the same private network, serving your application on a port (for example 80). They can be running already; you can also add them later.
• A domain you control (for HTTPS), and access to its DNS records at your DNS provider.
• If the instances have security groups, allow the application port from your private network's address range. The load balancer connects to the instances from its address on that network.

At launch every load balancer is one node in one region. It is billed per node for the hours it exists, never more than the monthly price; its public IPv4 address is included. See Pricing.

1. Create the load balancer

In the portal, open Load balancers and choose Create load balancer. Everything is on one screen:

1. Name and region. Lowercase letters, digits and dashes, starting with a letter (for example web-lb).
2. What does it serve?
   • A website or API: enter the domain (for example www.example.com). The load balancer listens for HTTPS on port 443 with an automatic certificate and redirects HTTP on port 80 to HTTPS.
   • No domain: TCP or UDP only: choose the protocol and the port clients connect to. Plain TCP and UDP are forwarded in the Linux kernel. Use this for databases, mail, MQTT, game servers or DNS.
3. Backend instances. Choose the private network the load balancer joins and the port your instances listen on. Then either tick the instances, or choose Every instance with a tag: instances you tag later join by themselves.

The Defaults box shows what the rest starts with:

Change defaults lets you pick another balancing method or health check path now; everything can be changed later. Choose Create. The load balancer shows creating and then active, with its public IPv4 address.

2. Point your domain at it

The load balancer's Overview shows the DNS record to create:

Create it at your DNS provider (an A record works for the bare domain example.com too). Once the name resolves to the load balancer, it gets a Let's Encrypt certificate for it; the Overview turns green and the domain is served over HTTPS. Certificates are renewed 30 days before they expire.

• To add more domains, add them to the HTTPS listener (Listeners) and create an A record for each. Wildcard names (*.example.com) cannot be issued automatically; upload a certificate for them under Certificates.
• While you move an existing site, lower the record's TTL a day ahead so the switch takes effect quickly.

3. Backends on a private network

The load balancer has an address on the private network you chose and connects to your instances there. An instance can be a backend when it is on that network, or on another network of the same VPC that a VPC route leads to (see Private networks and site-to-site VPN).

On the Backends tab each pool lists its servers:

• Add an instance by picking it, or give a pool a tag: every instance with the tag is a server, and new ones join by themselves.
• Weight sends a server more or less of the traffic; a backup server only gets traffic when the others are down.
• Stickiness keeps a client on one server, with a cookie (NXLB by default) or by source address.
• Your application sees the load balancer's address as the client. The original client address is in the X-Forwarded-For header (HTTP and HTTPS). For TCP, turn on the PROXY protocol for the pool if your server reads it.

4. Health checks

Every pool checks its servers. A server that fails its check is taken out of rotation, and put back when it passes again. Set the check on the pool in Backends:

Interval, timeout, rise and fall set how often it checks (default every 5 s, 2 s timeout) and how many results in a row change a server's state (2 to come back, 3 to go down).

The Backends and Metrics & logs tabs show every server's state (up, down, drain or maint), the time of its last check and the reason for the last result, for example HTTP 200, a timeout or a refused connection. A dedicated health path such as /healthz, which also checks your application's own dependencies, makes the result mean more than "the web server answers".

5. Routing rules

Without rules, every request on a listener goes to its default pool. Rules on the Routing tab send requests elsewhere. They are checked in order, and the first one that matches wins; drag a rule to reorder it.

A rule matches on any combination of:

• host (api.example.com) and path (prefix, exact or regular expression),
• method, headers, query parameters and cookies (exists, equals, prefix or regular expression),
• source address (203.0.113.0/24), and for TCP with TLS, the SNI name.

And then does one thing: forward to a pool, redirect (code, scheme, host, path), respond with a fixed status and body, or deny. A forward can also rewrite the path, set or remove request and response headers, or require basic authentication.

Example: send version 2 of an API to its own instances. Create a pool api-v2 on the Backends tab, then add the rule If host is api.example.com and path starts with /v2 → pool api-v2.

The Test a request box shows which rule and pool a given URL would reach before you apply anything.

6. Review, apply and roll back

Edits are staged until you apply them. Review changes lists what changes and checks the whole configuration; Apply puts it in force without dropping open connections. Every apply is a new numbered version. To go back, open Settings → Versions and choose Restore on an earlier version: it is checked against your current instances, networks and certificates and applied as a new version.

7. Protection

The Security tab holds the per-client limits from the Defaults table, the maximum body size, a deny list and trusted clients (addresses and networks), and the list of bans. Trusted clients are never rate-limited or banned; everyone else still gets in. To let only certain clients in, add a routing rule that denies requests whose source is not in your list. A ban stops the address in front of the load balancer until it expires; you can lift a ban or add one yourself.

These limits stop request floods, slow clients and connection exhaustion aimed at your service. A flood big enough to fill the network itself has to be stopped before it reaches the region; contact us if you are under one.

8. The API

Everything above is also in the API (see the API documentation). The whole configuration is one JSON document:

# Create (the private network id is on the network's page in the portal)
curl -s -X POST https://api.nextifynow.com/v1/load-balancers \
  -H "Authorization: Bearer $NEXTIFY_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "web-lb", "private_network_id": "<network id>"}'

# Read the configuration in force, edit it, check it, then apply it as a new version
curl -s https://api.nextifynow.com/v1/load-balancers/<id>/config \
  -H "Authorization: Bearer $NEXTIFY_TOKEN" > lb.json
curl -s -X POST https://api.nextifynow.com/v1/load-balancers/<id>/config/validate \
  -H "Authorization: Bearer $NEXTIFY_TOKEN" -H "Content-Type: application/json" -d @lb.json
curl -s -X PUT https://api.nextifynow.com/v1/load-balancers/<id>/config \
  -H "Authorization: Bearer $NEXTIFY_TOKEN" -H "Content-Type: application/json" -d @lb.json

# Every server's state and every certificate
curl -s https://api.nextifynow.com/v1/load-balancers/<id>/health -H "Authorization: Bearer $NEXTIFY_TOKEN"

Creating, changing the configuration and deleting answer 202 with a job_id; follow it with GET /v1/jobs/{job_id}. A configuration with a problem answers 422 with the path of each field at fault, for example listeners[0].tls.min_version.

Deleting a load balancer

Settings → Delete removes the load balancer, its certificates and its bans, and releases its public IPv4 address. Billing stops when it is deleted. Your instances are not touched.