---
url: https://ibee.ai/docs/network-security/load-balancer/attach-vms
last_updated: 2026-10-26
---

> For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://ibee.ai/docs/llms.txt (full text of every page: https://ibee.ai/docs/llms-full.txt). For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://ibee.ai/docs/_mcp/server.

# Attach VMs

> Put your Cloud VMs or GPU VMs behind an IBEE load balancer — which address to use, which firewall port to open, how to add or remove a VM later with the API, and how to check that traffic reaches every VM.

A **backend** is an address and port that a load balancer sends traffic to. Attaching a VM to a load balancer means adding the VM's address as a backend; there is no separate "attach" button. You list each VM's address in the load balancer's backends, and the load balancer starts health-checking and sending traffic to it.

## When to use each backend type

| Backend **Type** | **Target** example | Use it for                                                                  |
| ---------------- | ------------------ | --------------------------------------------------------------------------- |
| **IP address**   | `203.0.113.10`     | A Cloud VM or GPU VM. Use the VM's **public** IPv4 address.                 |
| **Hostname**     | `app1.example.com` | A server you reach by a DNS name, for example a VM whose address may change |
| **Service**      | `orders-service`   | A Kubernetes service name inside IBEE's platform. Not for your own VMs.     |

The load balancer isn't inside any of your VPCs, so it can't reach a VM's VPC private address (for example `10.144.0.5`). A VM in a **Private only** VPC, or one that reaches the internet only through a **Managed NAT Gateway** (shared outbound address), needs its own public address before it can be a backend: attach a [Reserved IP](/docs/network-security/vpc-ip-management/reserved-ips) to it.

## How it works

1. You add one backend per VM: its public IPv4 address and the port your app listens on.
2. The load balancer sends a health check to each VM on that port.
3. VMs that pass get traffic, in proportion to their **Weight**.
4. Your app on each VM sees the connections coming from the load balancer, not from the visitor.

## Before you begin

* **Two or more running VMs** with the same app, listening on the **same port** on every VM. See [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm).
* **Each VM's public IPv4 address**, shown in the **IP Address** column of the VM list and on the VM's detail page.
* **The app port open in each VM's firewall group.** The default firewall group accepts TCP `80`, `443` and `8000`–`8080` from anywhere. For any other port, add an **accept** rule. See [Create firewall rules](/docs/network-security/firewalls/create-firewall-rules). Also check the firewall inside the VM (`ufw`, `firewalld` or Windows Firewall).
* **A health endpoint** on each VM, such as `/health` returning HTTP `200`. See [Health checks](/docs/network-security/load-balancer/health-checks).

## Add VMs when you create the load balancer

### Collect the addresses

In the sidebar, under **Infrastructure**, click **Cloud VMs** (or **GPU VMs**). Note each VM's public IPv4 address from the **IP Address** column.

### Check each VM answers

From your computer, request the health endpoint on each VM:

```bash
curl -i http://203.0.113.10:8080/health
curl -i http://203.0.113.11:8080/health
```

Each should return `HTTP/1.1 200 OK`. If a request times out, open the port in the VM's firewall group first.

### Open the create form

Under **Network & Security**, click **Load Balancer**, then **Create Load Balancer**. Set the name, layer and protocol.

### Add one backend row per VM

In **Backends**, fill in the first row, then click **Add backend** for each extra VM:

| Field      | Value                                                         |
| ---------- | ------------------------------------------------------------- |
| **Type**   | **IP address** (the form starts on **Service**, so change it) |
| **Target** | The VM's public IPv4, for example `203.0.113.10`              |
| **Port**   | The port your app listens on, for example `8080`              |
| **Weight** | `100` on every VM for an even split                           |

Leave **Encrypt traffic from the load balancer to this backend** unticked: it isn't applied yet, and the load balancer connects without encryption.

### Create

Set the health check under **Routing and health**, then click **Create Load Balancer**.

## Add or remove a VM later

The portal can't edit a load balancer's backends. Use the API's `PATCH`, which keeps the load balancer's hostname. The `backends` list you send **replaces** the current list, so include every VM you want to keep.

This request adds a third VM to an L7 load balancer:

```bash
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 '{
    "backends": [
      {"type": "ip", "target": "203.0.113.10", "port": 8080, "weight": 100},
      {"type": "ip", "target": "203.0.113.11", "port": 8080, "weight": 100},
      {"type": "ip", "target": "203.0.113.12", "port": 8080, "weight": 100}
    ]
  }'
```

To remove a VM, send the list without it. For an L4 load balancer, use `/networking/load-balancers/l4/LB-ID`. The token needs `load-balancer.write`.

Without the API, create a new load balancer with the new list, point your DNS record at its new **Host**, and then delete the old one.

> **Warning**
>
> Before you delete or rebuild a VM that is a backend, remove it from the list (or let its health check fail). A deleted VM's address can later be given to someone else's server, and the load balancer would keep sending traffic to it. Keep VM addresses stable with [Reserved IPs](/docs/network-security/vpc-ip-management/reserved-ips).

## Verify

1. Open the load balancer's detail page. **Backends** lists every VM with its **Port**, **Weight** and **Backend TLS** setting.
2. Make each VM identify itself, for example with a `/whoami` page that returns the VM's hostname.
3. Send several requests to the load balancer and count the answers:

   ```bash
   for i in $(seq 1 20); do curl -s https://LB-HOST/whoami; echo; done | sort | uniq -c
   ```

   With equal weights and round robin, each VM answers about the same number of times.

## Maintenance without downtime

You don't need to remove a VM for a short restart. Its health check fails, and with the default settings it stops getting traffic after about 30 seconds. It gets traffic again about 20 seconds after it recovers. To avoid errors during those 30 seconds, take it out first with a `PATCH` that leaves it out of the list, restart it, then add it back.

## Limits

| Item                                          | Value                                                                     |
| --------------------------------------------- | ------------------------------------------------------------------------- |
| Backends per load balancer                    | At least `1`                                                              |
| Backend port                                  | `1`–`65535`                                                               |
| Weight                                        | `1`–`1000` (default `100`)                                                |
| Backend address                               | IPv4 or IPv6, reachable from the load balancer (a public address for VMs) |
| Time for a failing VM to stop getting traffic | About 30 seconds with the default health check                            |

## Troubleshooting

| You see                                                                       | What it means                                            | What to do                                                                             |
| ----------------------------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| "Service backends must use a Kubernetes service name without a slash or port" | The row is still on the default **Service** type         | Change **Type** to **IP address**.                                                     |
| A VM never gets traffic                                                       | Its health check fails                                   | Run `curl -i http://VM-IP:PORT/health` from outside. Fix the firewall rule or the app. |
| Every VM fails its check, but `curl` from your computer works                 | The rule allows only your address, not the load balancer | Set the rule's **Source** to **Anywhere** for the app port.                            |
| You entered a VPC address like `10.144.0.5` and the VM never gets traffic     | The load balancer can't reach VPC private addresses      | Use the VM's public IPv4, or attach a Reserved IP to the VM.                           |
| Your app logs show the load balancer's address for every visitor              | The load balancer opens its own connection to each VM    | Expected. Proxy protocol isn't applied yet.                                            |
| After a `PATCH`, some VMs disappeared from **Backends**                       | The list replaces the old one                            | Send every VM you want to keep.                                                        |

## Related pages

* [Create a load balancer](/docs/network-security/load-balancer/create-a-load-balancer)
* [Health checks](/docs/network-security/load-balancer/health-checks)
* [Algorithms](/docs/network-security/load-balancer/algorithms)
* [Create firewall rules](/docs/network-security/firewalls/create-firewall-rules)
* [Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms)