ezlb

English | 中文

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

make build

Cross-compile for Linux:

make build-linux

Configuration

Create a config file config.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

# Daemon mode
sudo ezlb start -c config.yaml

# Single reconcile pass
sudo ezlb once -c config.yaml

# Show version
ezlb -v

Testing

# 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