> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leviacloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Load balancer

> Load balancer L4 (TCP/UDP) dengan IP publik, listener, health check, dan target VM.

Endpoint load balancer butuh `load_balancer:read` (baca) atau `load_balancer:write` (ubah). Scope ini terpisah dari `network:*`.

Load balancer Levia bekerja di **L4** (TCP/UDP): satu IP publik, satu atau lebih **listener** (port masuk → `target_port` di setiap backend), dan **target** berupa VM di VPC yang sama atau alamat privat di subnet VPC itu. Trafik dibagi ke target yang sehat.

## Harga

`GET /load-balancers/plans` menampilkan tarif per load balancer dalam Rupiah. IP publiknya sudah termasuk; listener dan target tidak menambah biaya. Ditagih per jam sejak `active` sampai dihapus.

## Buat load balancer

```bash theme={null}
curl -s -X POST "$LEVIA_API/load-balancers" \
  -H "Authorization: Bearer $LEVIA_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "web-lb",
    "region_id": "'$REGION'",
    "vpc_id": "'$VPC'",
    "listeners": [
      {"protocol": "tcp", "port": 80, "health_check": {"protocol": "http", "path": "/"}}
    ],
    "targets": [{"vm_id": "'$VM1'"}, {"vm_id": "'$VM2'"}]
  }'
```

1. Tunggu `GET /load-balancers/{id}` sampai `ready: true` (status `active`, IP publik ada). Biasanya kurang dari satu menit.
2. Tunggu `GET /load-balancers/{id}/targets` sampai setiap target `health_status: healthy`.
3. Kirim trafik ke `public_ip`.

| Field | Arti |
| - | - |
| `listeners` | Minimal satu. `protocol`: `tcp` atau `udp`; `port`; `target_port` (bawaan = `port`); `health_check` opsional |
| `targets` | Opsional, bisa ditambah nanti. Isi `vm_id` **atau** `ip_address` per target, plus `weight` 1–256 |
| `subnet_id` | Subnet **publik** VPC. Tanpa ini: subnet target VM pertama, lalu subnet publik di `zone_id`, lalu subnet default VPC. Backend boleh di subnet lain dalam VPC. |
| `session_affinity` | `none` (bawaan) atau `client_ip`: klien yang sama selalu ke backend yang sama |
| `source_ranges` | IPv4/CIDR klien yang boleh masuk; kosong = semua |
| `health_check` | Health check untuk setiap listener yang tidak punya health check sendiri |

**Health check bawaan**: `tcp` ke `target_port` (UDP: `none`), interval 5 detik, timeout 3 detik, sehat setelah 2 kali berhasil, tidak sehat setelah 3 kali gagal. `protocol: http` memeriksa `path`.

## Security group backend

> [!WARNING]
>
> Backend melihat semua trafik datang dari `snat_ip` load balancer, bukan alamat klien. Izinkan port backend dari `snat_ip` atau dari CIDR VPC di security group VM, atau health check dan trafik tidak akan sampai.

## Listener

| Aksi | Endpoint | Catatan |
| - | - | - |
| Daftar | `GET /load-balancers/{id}/listeners` | `health_check.port: 0` = `target_port` |
| Tambah | `POST /load-balancers/{id}/listeners` | Maks. 64 listener; pasangan protokol + port tidak boleh ganda (`422`) |
| Ubah | `PATCH /load-balancers/{id}/listeners/{listener_id}` | `port`, `target_port`, `health_check`. Mengganti `port` memberi listener **id baru** (ada di jawaban). Protokol tidak bisa diubah. |
| Hapus | `DELETE /load-balancers/{id}/listeners/{listener_id}` | Tanpa listener, load balancer tidak menerima trafik |

## Target

```bash theme={null}
curl -s -X POST "$LEVIA_API/load-balancers/$LB/targets" \
  -H "Authorization: Bearer $LEVIA_KEY" -H "Content-Type: application/json" \
  -d '{"vm_id": "'$VM3'", "weight": 2}'
```

* Isi tepat satu dari `vm_id` (VM organisasi di VPC load balancer yang sudah punya alamat privat, bukan jaringan `isolated`) atau `ip_address` (alamat host salah satu subnet VPC itu). Maks. 256 target.
* `GET /load-balancers/{id}/targets`: `health_status` keseluruhan (`healthy` hanya bila sehat di semua listener; `unknown` = belum ada laporan, mis. tepat setelah ditambahkan) dan `health` per listener (mis. `tcp/80`).
* `DELETE /load-balancers/{id}/targets/{target_id}` mengeluarkan backend (VM-nya tidak disentuh). `target_id` boleh `id` target atau `vm_id`-nya.

## Ubah load balancer

`PATCH /load-balancers/{id}` hanya mengubah field yang dikirim:

```bash theme={null}
curl -s -X PATCH "$LEVIA_API/load-balancers/$LB" \
  -H "Authorization: Bearer $LEVIA_KEY" -H "Content-Type: application/json" \
  -d '{"session_affinity": "client_ip", "source_ranges": ["203.0.113.0/24"]}'
```

* `name`, `session_affinity`, `tags`.
* `source_ranges` menggantikan seluruh daftar (`[]` = semua klien).
* `health_check` menggantikan health check **semua** listener. Untuk satu listener, pakai `PATCH …/listeners/{listener_id}`.

## Hapus

`DELETE /load-balancers/{id}` menghapus load balancer beserta listener dan daftar targetnya (VM tidak disentuh) dan menghentikan tagihan. IP publiknya kembali ke pool. Jawaban `202`; status `deleting` lalu hilang (`404`).

## Load balancer milik Kubernetes

Load balancer yang dibuat cluster Kubernetes tampil di daftar dengan `source: kubernetes` dan hanya bisa dibaca. Mengubah atau menghapusnya lewat API ditolak `409`; ubah lewat Service di cluster.

## Belum didukung

Ditolak `422`: listener HTTP/HTTPS (L7), sertifikat TLS, routing rule, redirect HTTPS, proxy protocol, sticky session cookie, dan algoritma selain pembagian merata. Field yang tidak dikenal (mis. `algorithm`) juga ditolak `422 validation_error`. Untuk web, pakai listener `tcp` port 80/443 dengan health check `http`, dan terminasi TLS di VM.

Floating IP tidak bisa dipasang ke load balancer (load balancer sudah punya IP publik sendiri), dan belum ada opsi lintas zona.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.