https://github.com/easzlab/ezlb
A lightweight Layer-4 TCP load balancer based on Linux IPVS, using declarative reconcile mode to dynamically manage IPVS services.
https://github.com/easzlab/ezlb
Last synced: 4 months ago
JSON representation
A lightweight Layer-4 TCP load balancer based on Linux IPVS, using declarative reconcile mode to dynamically manage IPVS services.
- Host: GitHub
- URL: https://github.com/easzlab/ezlb
- Owner: easzlab
- License: mit
- Created: 2026-02-08T13:45:13.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-09T00:37:14.000Z (4 months ago)
- Last Synced: 2026-02-09T06:25:44.704Z (4 months ago)
- Language: Go
- Size: 80.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ezlb
English | [中文](README_CN.md)
A lightweight Layer-4 TCP load balancer based on Linux IPVS, using declarative reconcile mode to dynamically manage IPVS services.
## Features
- **IPVS Kernel-Level Load Balancing**: High-performance Layer-4 forwarding powered by Linux IPVS
- **Declarative Reconcile**: Automatically compares desired state with actual IPVS rules and applies incremental changes
- **Multiple Scheduling Algorithms**: Round Robin (rr), Weighted Round Robin (wrr), Least Connection (lc), Weighted Least Connection (wlc), Destination Hashing (dh), Source Hashing (sh)
- **TCP Health Checks**: Independent health check configuration per service, with option to disable
- **Hot Config Reload**: File changes automatically trigger reconciliation without restart
## Quick Start
### Build
```bash
make build
```
Cross-compile for Linux:
```bash
make build-linux
```
### Configuration
Create a config file `config.yaml`:
```yaml
global:
log_level: info
services:
- name: web-service
listen: 10.0.0.1:80
protocol: tcp
scheduler: wrr
health_check:
enabled: true
interval: 5s
timeout: 3s
fail_count: 3
rise_count: 2
backends:
- address: 192.168.1.10:8080
weight: 5
- address: 192.168.1.11:8080
weight: 3
```
### Usage
```bash
# Daemon mode
sudo ezlb start -c config.yaml
# Single reconcile pass
sudo ezlb once -c config.yaml
# Show version
ezlb -v
```
## Testing
```bash
# Run unit tests (macOS/Linux)
make test
# Run all tests (Linux, requires root)
make test-linux
# Run e2e tests (Linux, requires root)
make test-e2e
```
## Project Structure
```
ezlb/
├── cmd/ezlb/ # Entry point, CLI commands
├── pkg/
│ ├── config/ # Config management (loading, validation, hot reload)
│ ├── lvs/ # IPVS management (operations, reconcile)
│ ├── healthcheck/ # Health checking (TCP probes)
│ └── server/ # Server orchestration (lifecycle management)
├── tests/e2e/ # End-to-end tests
├── examples/ # Example configurations
└── Makefile
```