Superclouds
Create account

Load balancers

Spread HTTP(S), TCP and TLS traffic across your services, route it with rules, and put a firewall in front.

A load balancer gives your app one public address and shares incoming traffic between your machines, containers, databases, storage endpoints or plain IP addresses. You build and manage load balancers in the Load Balancer Studio: Super Load BalancerLoad Balancer.

Before you start

Your account must be set up (profile, payment method and an attached prefix), see Set up your account. To create or change a load balancer you need the MODIFY role on the prefix; to delete one you need MANAGE. Buttons you can't use are greyed out with the tooltip "Needs MODIFY role on this prefix" (or MANAGE). See Users and roles.

How a request flows

  1. A listener accepts traffic on one protocol and port, for example HTTPS on 443.
  2. The listener's rules are checked from top to bottom. The first rule whose condition matches wins.
  3. That rule's action decides what happens: forward the request, redirect it, answer it directly, or deny it. If no rule matches, the listener's default action applies.
  4. A forward action sends the request to a target group, which picks one healthy target (a machine, container, database, storage endpoint or IP) using its balancing algorithm.

A web application firewall can sit in front of all of this and inspect every request before it reaches a listener.

Choose a prefix

Load balancers, permissions and billing belong to a prefix. Pick one in the Prefix list at the top of the studio. The studio remembers your last choice, and if you only have one prefix it is selected for you. The badge next to it shows your role on that prefix.

If you see No access to this prefix, your role doesn't include READ on it. Ask a prefix admin for access.

Create a load balancer

  1. Open Super Load BalancerLoad Balancer and select a prefix.
  2. Click New load balancer.
  3. Enter a Name, for example shop-lb (up to 64 characters).
  4. Choose a Region, close to your targets.
  5. Optionally add a Description.
  6. Pick a blueprint under Start from a blueprint (see below).
  7. Click Create.

You'll see a message that your load balancer is provisioning and that this can take a minute. The studio waits for the load balancer to be ready and then opens it. If it is still getting ready after about 90 seconds, you'll see a message that it is still provisioning: click Refresh on the list in a moment. If provisioning fails, the message includes the reason; the load balancer stays in the list so you can delete it and try again.

Blueprints

BlueprintWhat you get
BlankNothing. Build listeners and rules yourself.
Web appHTTP on port 80 sending traffic to a web target group, with /static and common file types (css, js, images, fonts) sent to a static group.
API + canary/api split 90/10 between a stable and a canary group. Requests with the header x-beta: 1 or the cookie canary=yes always go to canary. Anything else gets a 404.
Database (TCP)TCP on port 5432 to a database pool, reachable from private address ranges only.

The blueprint fills in Initial configuration, which you can edit before you click Create.

Add targets after creating

Blueprints create empty target groups. Your load balancer serves nothing until you add targets.

Find a load balancer

The Load balancers panel shows one card per load balancer with its status, public IP and region, how many listeners, rules, target groups and targets it has, whether a firewall protects it (WAF with its mode, or unprotected), its configuration version, and one chip per listener such as https:443. Type in Search… to filter the cards, and click a card to open it.

StatusMeaning
runningServing traffic.
stoppedNot serving traffic. Configuration is kept.
terminatedDeleted.
failedSomething went wrong. Try Restart, or contact support.

The load balancer screen

The header shows the ID (click it to copy), Region, Public and Private addresses, and the configuration version with its state: applied, failed, or in progress. Hover over the state to read its message. Use the back arrow to return to the list.

TabWhat you do there
TopologySee the whole setup as a diagram. Click any node to edit it.
Listeners & rulesAdd listeners and the rules that route their traffic.
Target groupsGroup your targets, set balancing and health checks.
WAF & accessPut a firewall in front and see which ports are open.
CertificatesUpload TLS certificates for HTTPS listeners.
JSON & HAProxyEdit the whole configuration as one JSON document.
Health & activityTarget health and recent events.

Saving and applying

Every time you save a listener, rule, target group or target, the change is saved and pushed to the load balancer straight away. You'll see "Saved & applied (config vN)". If you see "Saved, but apply failed: …", your change is stored but not live: fix the problem named in the message and save again, or click Apply to retry.

Topology

The diagram reads left to right: Clients, Shield (the firewall), Listeners, Routing rules, Target groups / actions, Targets. Targets are coloured by health, and weighted splits show their percentages on the lines. Tiles at the top count your listeners, rules, groups and healthy targets, and show whether the firewall shield is on.

Use the quick buttons Listener, Routing rule, Target group and Protect with WAF to add things from here.

Add a listener

A listener accepts traffic on one port and protocol.

  1. Open the Listeners & rules tab and click Add next to Listeners.
  2. Pick a Protocol: HTTP, HTTPS, TCP or TLS (passthrough). The port changes to the usual one for that protocol.
  3. Check the Port (1 to 65535) and optionally give it a Name.
  4. Set the Default action (no rule matched), see Actions.
  5. Fill in the protocol options below if you need them.
  6. Click Create listener.
OptionApplies toWhat it does
Certificates (SNI picks the matching one)HTTPSTick the certificates to serve. Upload them first on the Certificates tab.
HTTP/2HTTPSOn by default.
Redirect all requests to HTTPSHTTPSends every request to the HTTPS version of the same URL.
Allow only these CIDRs / Deny these CIDRsAllRestrict which addresses can connect, e.g. 203.0.113.0/24.
Rate limit (requests), per seconds, key, statusAllLimit how often one client can call, counted per IP, header or cookie. Leave the limit blank to turn it off. Clients over the limit get status 429 by default.
HTTP optionsHTTP, HTTPSCompression, request IDs, the X-Forwarded-For header, HSTS, maximum body size, client timeout, and extra request or response headers.

TCP and TLS listeners can only forward or deny: they can't look inside the request, so their rules and actions are limited.

To change a listener later, select it and click Listener settings. Deleting a listener (trash icon) also deletes its rules.

Add a routing rule

Rules decide where each request goes. They are checked from top to bottom and the first match wins.

  1. On the Listeners & rules tab, select the listener and click Add rule.
  2. Enter a Rule name, e.g. api canary.
  3. Optionally set a Priority. Leave it blank and a priority is set for you.
  4. Build the condition under If the request matches, see Conditions.
  5. Under Then, choose the action.
  6. For HTTP listeners, optionally open Request & response rewrites to change the path, host header or headers on the way through.
  7. Click Create rule.

A rule needs at least one condition. For "everything else", use the listener's Default action instead of a rule.

To manage rules, use the buttons on each rule: move it up or down (or drag it), enable or disable it, edit it (or double-click), or delete it. The row Default action, when no rule matches is always last.

Build a condition

The condition builder is shared with the web application firewall. You can build a condition by clicking, as JSON, or as a text expression: switch with Visual, JSON and Expression.

  1. Click Condition to add a row.
  2. Choose a Field to look at, for example the path, a header or the client IP. Fields are grouped by Client, Request line, Query & body, and Headers & cookies. Some fields need a name, such as the header name; the box turns red until you fill it in.
  3. Choose an Operator, such as equals or starts with, and enter the value.
  4. Add more rows. Click ALL or ANY on a group to switch between "all of these must match" and "one of these is enough".
  5. Use Nested group to combine AND and OR, and NOT to invert a group or a row.

More controls on each row:

  • The wand button applies transformations in order before matching, for example URL-decode then lowercase, so attackers can't slip past with encoded text.
  • Aa makes the match case-sensitive. Matching ignores case by default.
  • Drag the handle to move a row, even into another group.

The chip in the title bar shows valid or how many problems there are, listed below the builder. READS AS at the bottom shows your condition as an expression. Click Explain for a plain-English description and the compiled rules, or Copy JSON to reuse it elsewhere. You can't switch views while the JSON or expression has errors: fix them first.

Actions

ActionWhat happensSettings
ForwardSends the request to a target group.Choose the group. Turn on Weighted split (canary / blue-green) to share traffic between groups by weight, e.g. 90/10. Use Add another group for more.
RedirectTells the client to go elsewhere.Redirect by scheme (e.g. to https), a full Location URL, or a Prefix (keeps the path). Status 301 (default), 302, 303, 307 or 308. The URL can include placeholders, listed under the field, such as {path} and {query}.
Fixed responseAnswers directly, without a target.Status (default 200), Content type, Body and Headers. Useful for maintenance pages or health endpoints.
DenyRejects the request.Status, default 403.

TCP and TLS listeners offer only Forward and Deny. If the target group list is empty, create a group on the Target groups tab first.

Target groups and targets

A target group is a pool of targets that share a protocol, a balancing algorithm and a health check.

Create a target group

  1. Open the Target groups tab and click New target group.
  2. Enter a Name and choose a Protocol: http, https or tcp.
  3. Choose a Balancing algorithm. The options come from the service; round robin is the default. Some algorithms ask for a parameter or header name.
  4. Set up the Health check: its type and, for HTTP checks, the Path (default /), Expect status (e.g. 200-399) and Method. Leave interval, timeout, rise and fall blank for the defaults.
  5. Optionally use the settings under Advanced for sticky sessions, retries, connection limits, a host header override, upstream TLS settings or the PROXY protocol.
  6. Click Create. The target picker opens next.

Add targets

  1. Under What do you want to balance?, pick a target type, for example machine, container, database, storage or IP address.
  2. Tick the services you want from the list of that type in your prefix. Use Filter… to search.
  3. Optionally set the Port (blank uses the service's default), the Weight (default 100) and Backup (used only when the others are down).
  4. Click Add targets.

For IP addresses, enter one target per line, e.g. 10.0.5.20:8080 100 (port and weight are optional).

Typed targets (everything except raw IPs) find their address automatically. If a service's address changes, click the refresh button on the group to look the addresses up again.

In the targets table you can change a target's Weight or turn it off with Enabled; changes save as you make them. Health shows UP, DOWN or another state with the result of the last check. Click Refresh health to check again.

You can't delete a target group that a rule or default action still uses: change those first.

TLS certificates

To serve HTTPS, upload a certificate and tick it in an HTTPS listener.

  1. Open the Certificates tab and click Upload certificate.
  2. Enter a Name, e.g. shop.example.com.
  3. Paste the certificate chain and the unencrypted private key into PEM bundle (certificate chain + unencrypted private key), or click Load from file.
  4. Click Upload.
  5. Open the HTTPS listener's settings and tick the certificate under Certificates (SNI picks the matching one).

You'll see "Certificate stored". The private key is never shown again. The table shows each certificate's domains, which listeners use it, and how many days until it expires: amber under 21 days, red when expired. Upload a renewed certificate before then.

Protect with a firewall

  1. Open the WAF & access tab.
  2. Choose a Web ACL. If you don't have one, click Create a Web ACL, see Web application firewall.
  3. Choose a Deployment mode: Inline (default) keeps the same public IP, so no DNS change is needed. Edge gives the firewall its own public IP; point your DNS at it when you are ready.
  4. Click Protect this load balancer.

You'll see Provisioning the WAF in front of followed by the name, then WAF is active in front of the load balancer when it is done. If it fails, the message gives the reason. You need the MODIFY role on the prefix.

The real client IP still reaches the load balancer, so rules, logs and sticky sessions keep working. To stop inspecting traffic, click Detach WAF and confirm.

The Ingress (traffic profiles) panel on the same tab lists which ports are open on the public IP. Per-listener allow and deny lists and rate limits are in each listener's settings.

Edit the configuration as JSON

The JSON & HAProxy tab holds the whole configuration (listeners, rules, target groups and settings) in one document.

  • Format tidies the JSON. Import loads a .json file; Export downloads the current configuration.
  • Validate & preview checks your changes and shows the compiled HAProxy configuration on the right, without applying anything.
  • Save & apply saves and pushes the configuration (also Ctrl+S or ⌘S).

Use this to copy a setup to another load balancer or keep it in version control.

Health and activity

The Health & activity tab shows how many targets are up and down, the health of every target in each group, and the latest 60 events. Use it first when something isn't reaching your app.

Start, stop, restart and delete

Use the buttons in the load balancer's header:

  • Apply pushes the current configuration again. You'll see "Configuration applied".
  • Stop stops serving traffic on the public IP. Confirm with Stop. Your configuration is kept.
  • Start (shown when stopped) starts serving again.
  • Restart restarts the load balancer.
Deleting can't be undone

Delete terminates the load balancer and releases its public IP: you won't get the same address back. A firewall attached to it is detached. Type the load balancer's name to confirm, then click Delete. You need the MANAGE role.

Troubleshooting

  • Requests time out or return an error. Check the Health & activity tab. If targets are DOWN, check that the service listens on the target port and that the health check path returns a status in the expected range.
  • Nothing is served after creating from a blueprint. The blueprint's target groups are empty. Add targets.
  • "Add a listener first" You tried to add a rule before any listener exists.
  • "Saved, but apply failed: …" Your change is stored but not live. Fix what the message names and save again, or click Apply.
  • "You do not have permission for this action on this prefix" Your role on the prefix is too low. Ask a prefix admin.
  • "Your session expired, please sign in again" Sign in and open the studio again.