Skip to navigation

Create a load balancer

Creating a load balancer gives you one public hostname that spreads traffic across the backends you list. It takes one form in the portal or one API call. The load balancer is ready, with status active, as soon as the request finishes.

If you’re new to load balancers, read the Load Balancers overview first.

When to use each protocol

You pick the layer and protocol once, at creation. To change them later, create a new load balancer.

Your trafficLayerProtocolClients connect to
A website or API, and you want IBEE to handle the certificateLayer 7HTTPShttps://HOST (port 443)
A website or API without encryption, for example for a testLayer 7HTTPhttp://HOST (port 80)
Any TCP service: a database, a queue, SSH, a game serverLayer 4TCPHOST:PORT, with a port IBEE assigns from 9000–19999
Encrypted traffic that your servers must decrypt themselvesLayer 4TLS passthroughHOST:8443

L7 (Layer 7) load balancers read each HTTP request, so they can route by path and header. L4 (Layer 4) load balancers forward whole TCP connections without reading them.

How it works

  1. You enter a name, a layer and protocol, and one or more backends.
  2. IBEE creates the routing on its shared load-balancing service, creates a DNS name for it, and sets the status to active. If any part fails, nothing is kept and you see an error.
  3. Health checks start, and traffic goes only to backends that pass them.
  4. Billing starts when the status becomes active.

Before you begin

  • A verified organization. Until it is verified, the portal shows Verify Identity instead of Create Load Balancer. See Verify your identity.
  • Your backends’ addresses and port. For VMs, use each VM’s public IPv4 address. See Attach VMs.
  • The backend port open in each VM’s firewall group. The default firewall group already accepts TCP 80, 443 and 8000–8080. See Firewalls.
  • A health-check endpoint on each backend, such as /health returning HTTP 200, if you use an HTTP check.
  • Room in your plan. Your plan sets how many load balancers you can have. See Limits and quotas.

Create a load balancer in the portal

1

Open Load Balancers

In the sidebar, under Network & Security, click Load Balancer. Then click Create Load Balancer. The Create Load Balancer page opens, with a Configuration summary on the right that updates as you fill in the form.

2

Set the traffic profile

FieldWhat to enter
Name1–128 characters, for example orders-gateway. No other load balancer in the workspace can have the same name.
LayerLayer 7 (HTTP and HTTPS, the default) or Layer 4 (TCP and TLS passthrough)
ProtocolLayer 7: HTTPS (default) or HTTP. Layer 4: TCP (default) or TLS passthrough.
3

Add backends

Each backend is one row. Click Add backend for each extra server.

FieldWhat to enter
TypeIP address for a VM, or Hostname for a server you reach by DNS name. The form starts on Service, which is a Kubernetes service name inside IBEE’s platform and isn’t for your own servers, so change it.
TargetThe address, for example 203.0.113.10, or a full hostname such as app1.example.com
PortThe port your app listens on, 1–65535 (default 8080)
WeightShare of traffic, 1–1000 (default 100). A backend with weight 200 gets twice the traffic of one with 100.

Leave Encrypt traffic from the load balancer to this backend unticked. The setting is saved but not applied yet, so the load balancer always connects to backends without encryption. A backend that only accepts TLS on that port will fail.

4

Set routing and health

Under Routing and health:

  • Routing algorithm: Round robin (default), Least request, Random or Consistent hash. See Algorithms.
  • Request timeout: how long one request may take, 100–300,000 ms (default 30000, 30 seconds). It applies to Layer 7 load balancers.
  • Active health check:
FieldDefaultAllowed
TypeHTTPHTTP, HTTPS, TCP
Path (HTTP and HTTPS)/healthAny path
Interval (ms)10000100–120,000 ms
Timeout (ms)2000100–120,000 ms
Healthy threshold21–20
Unhealthy threshold31–20

See Health checks for what these numbers mean.

5

Set advanced behavior (optional)

Under Advanced behavior:

  • Automatic retries: retries a request that failed with a 5xx response, a reset connection or a connection failure. Attempts 1–10 (default 3) and Per-retry timeout (ms) 100–120,000 (default 5000).
  • L7 routing rules (Layer 7 only): click Add rule for each rule, with a Priority (lower numbers are checked first), a Path prefix such as /api, and an optional Header name and Header value. With no rules, every request goes to your backends.
  • Sticky sessions and Proxy protocol: saved but not applied to traffic yet. Leave them off.
6

Create

Click Create Load Balancer. When it succeeds you see “Load balancer created successfully” and the load balancer’s detail page opens.

Create a load balancer with the API

Send a POST to /networking/load-balancers/l7 for HTTP or HTTPS, or to /networking/load-balancers/l4 for TCP or TLS passthrough. Replace 710995 with your workspace ID: the number after /workspaces/ in the portal’s address bar.

Every backend needs "type": "ip" (or "hostname"), because the API’s default type is service. An HTTPS load balancer also needs "tls": {"mode": "terminate"}, and a TLS passthrough one needs "tls": {"mode": "passthrough"}.

curl -X POST "https://api.ibee.ai/v1/networking/load-balancers/l7?workspace_id=710995" \
-H "Authorization: Bearer $IBEE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "web-lb",
"protocol": "https",
"tls": {"mode": "terminate"},
"backends": [
{"type": "ip", "target": "203.0.113.10", "port": 8080},
{"type": "ip", "target": "203.0.113.11", "port": 8080}
],
"routing": {"algorithm": "round_robin"},
"health_check": {
"active": {
"type": "http",
"path": "/health",
"interval_ms": 10000,
"timeout_ms": 2000,
"healthy_threshold": 2,
"unhealthy_threshold": 3
}
}
}'

The token needs the load-balancer.write scope. A successful call returns 201 with the new load balancer. These are the fields you need next:

{
"lb_id": "3f9c2b7e-5d1a-4c8e-9b6f-0a2d4e6f8a1c",
"name": "web-lb",
"layer": "l7",
"protocol": "https",
"status": "active",
"endpoint": {"host": "3f9c2b7e-5d1a-4c8e-9b6f-0a2d4e6f8a1c.lb.ibee.ai", "port": 443},
"endpoint_url": "https://3f9c2b7e-5d1a-4c8e-9b6f-0a2d4e6f8a1c.lb.ibee.ai"
}

If you leave out health_check in the API, no active health check is set up. The portal always sends one.

Verify

  1. Open the load balancer’s detail page. The header shows the layer, protocol and status, which should be active. Public endpoint shows the Host, the Listener port and the Public host URL, with copy buttons.

  2. Send a request to the endpoint:

    curl -i https://3f9c2b7e-5d1a-4c8e-9b6f-0a2d4e6f8a1c.lb.ibee.ai/

    For an L4 TCP load balancer, connect to the host and the listener port shown, for example nc -vz HOST 9012.

  3. Check the status at any time with GET /networking/load-balancers/LB-ID/status. It returns status, the endpoint, and an error_message if something failed.

To serve the load balancer on your own domain, add a CNAME record at your DNS provider that points to the Host. For an HTTPS load balancer, also see Use your own domain so that the certificate matches your domain.

Change a load balancer

The portal can’t edit a load balancer. You have two options:

  • Use the API. PATCH /networking/load-balancers/l7/LB-ID or PATCH /networking/load-balancers/l4/LB-ID changes only the fields you send: name, backends, routing, health_check, policy, tls, and for L7 also rules and custom_domain. A backends or rules list replaces the whole existing list. The hostname and port don’t change.
  • Recreate it. Create a new load balancer with the new settings, move your DNS record to its Host, then delete the old one. The new load balancer has a different hostname.
curl -X PATCH "https://api.ibee.ai/v1/networking/load-balancers/l7/3f9c2b7e-5d1a-4c8e-9b6f-0a2d4e6f8a1c?workspace_id=710995" \
-H "Authorization: Bearer $IBEE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"routing": {"algorithm": "least_request"}}'

Delete a load balancer

Deleting a load balancer is permanent. Its hostname stops working and won’t come back; a new load balancer gets a different hostname. Move your DNS records first. Your backend VMs are not deleted.

  1. On the Load Balancers list, click the delete icon on the load balancer’s row.
  2. In the Delete Load Balancer dialog, type the load balancer’s name.
  3. Click Delete Load Balancer. You see “Load balancer deleted successfully”.

With the API: DELETE /networking/load-balancers/LB-ID?workspace_id=710995 returns 204. Billing stops when the deletion completes.

Limits and timing

ItemValue
Time to createOne request. The load balancer is active when the call returns, or nothing is created.
Status valuesprovisioning, active, failed, deleting, deleted
Name1–128 characters, unique in the workspace
Ports clients useHTTP 80, HTTPS 443, TLS passthrough 8443, TCP one port from 9000–19999
BackendsAt least 1; port 1–65535; weight 1–1000
Request timeout100–300,000 ms, default 30 seconds (Layer 7)
Number of load balancersSet by your plan: see Limits and quotas

Troubleshooting

You seeWhat it meansWhat to do
”Complete account verification to create resources”Your organization isn’t verifiedComplete identity verification.
”Backend port must be between 1 and 65535”A backend’s port is empty or out of rangeEnter the port your app listens on.
”Backend weight must be between 1 and 1000”A weight is outside the rangeUse a whole number from 1 to 1000.
”Hostname backends must use a valid fully qualified hostname”A Hostname target has no dot, or starts or ends with oneEnter a full name such as app1.example.com.
”Service backends must use a Kubernetes service name without a slash or port”The row is still on the default Service typeChange Type to IP address or Hostname.
409 “load balancer with name ‘web-lb’ already exists”The name is taken in this workspaceChoose another name.
”You have reached your plan’s limit for this resource.” or 402 with resource_limit_reachedYour plan’s load balancer limit is used upDelete one you don’t need, or click Request a limit increase.
402 with insufficient_balance or credit_limit_exceededBilling refused the new resourceTop up your balance, then try again.
423 organization_suspendedYour organization is suspended, so changes are refusedSee Billing and usage.
”tls block is required for https protocol”An API request for HTTPS has no tlsAdd "tls": {"mode": "terminate"}.
”Failed to create load balancer: …” (500)Setting up the routing failed, and nothing was keptTry again. If it repeats, contact support with the message.
Status active, but requests failNo backend passes its health check, or the firewall blocks the portSee Health checks → Troubleshooting.