arca-lb is a Kubernetes-native control plane for VPP-based Layer 4 load balancing, designed for environments that demand line-rate performance, operational simplicity, and horizontal scalability.
arca-lb is one component of Arca, an open-source infrastructure stack for self-hosted clouds, Kubernetes/OpenStack environments, edge clusters, labs, and small service providers.
Related projects:
- arca-router: VPP/FRR-based software router
- arca-dns: Anycast DNS infrastructure with DNSSEC support
- arca-storage: software-defined storage and CSI/Cinder/Manila integration
Modern private-cloud and edge operators often need vendor-neutral networking components that are reproducible, inspectable, and automatable. arca-lb focuses on Kubernetes-native L4 load balancing using VPP while keeping the control plane explicit and auditable.
- Operator:
ghcr.io/akam1o/arca-lb-operator - Agent:
ghcr.io/akam1o/arca-lb-agent
- Kubernetes-native: Declarative VIP management via
VirtualIPCustom Resource (CRD) - Operator pattern: Kubernetes Operator handles validation, status, and lifecycle
- High-performance data plane: Wire-rate packet processing powered by the VPP L4 LB plugin
- Pluggable interfaces: DataPlane and Router interfaces for testability and extension
- Flexible health checks: Supports HTTP/HTTPS, TCP, Ping, and TLS hello probes with per-VIP configuration
- Automatic route announcements: BGP advertisements through FRR integration
- Scalable: One Agent per LB node, deployed as a DaemonSet
- Observable: OpenTelemetry traces/metrics, Prometheus endpoint, structured logging
- OpenStack Octavia: Provider driver for integration with OpenStack LBaaS API
┌─────────────────────────────────────────┐
│ kubectl / GitOps │
│ (apply VirtualIP CRD manifests) │
└────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ Kubernetes API Server │
│ - VirtualIP CRD (arca.io/v1alpha1) │
│ - CRD admission validation │
└──────┬──────────────────────┬───────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────────────┐
│ Operator │ │ Agent (per LB node) │
│ - Reconcile │ │ - K8s Informer │
│ - Status │ │ - Per-VIP Reconciler │
│ - Validation│ │ - Health Checks │
└──────────────┘ │ - VPP DataPlane │
│ - FRR Router │
│ - bbolt Local Store │
│ - OTel Telemetry │
└──────────────────────┘
apiVersion: arca.io/v1alpha1
kind: VirtualIP
metadata:
name: web-vip
spec:
address: 203.0.113.10
port: 80
protocol: TCP
encapType: L3DSR
dscp: 10
backends:
- address: 10.0.1.1
weight: 1
- address: 10.0.1.2
weight: 1
healthCheck:
type: http
intervalSeconds: 5
timeoutSeconds: 3
riseCount: 3
fallCount: 2
http:
port: 8080
path: /healthzarca-lb/
├── api/
│ └── v1alpha1/ # VirtualIP CRD types (kubebuilder)
├── cmd/
│ ├── operator/ # Operator (K8s controller) binary
│ └── arcalb-agent/ # Agent binary
├── config/ # K8s manifests (generated + hand-written)
│ ├── crd/ # CRD YAML (controller-gen output)
│ ├── rbac/ # RBAC roles
│ ├── manager/ # Operator Deployment
│ ├── agent/ # Agent DaemonSet
│ └── samples/ # Example VirtualIP resources
├── internal/
│ ├── operator/ # Operator reconciler + optional webhook
│ ├── agent/ # Agent implementation
│ │ ├── config/ # Agent configuration
│ │ ├── dataplane/ # DataPlane interface (VPP, Noop)
│ │ ├── routing/ # Router interface (FRR, Noop)
│ │ ├── store/ # bbolt local persistence
│ │ ├── watcher/ # K8s informer-based CRD watcher
│ │ ├── reconciler/ # Per-VIP reconciler
│ │ └── healthcheck/ # Health check engine
│ └── pkg/otel/ # OpenTelemetry setup
├── octavia-driver/ # OpenStack Octavia provider driver (Python)
├── deploy/ # Deployment artifacts
├── docs/ # Documentation
└── test/ # Tests
- Go: 1.25+ (development)
- Kubernetes: 1.28+ (runtime)
- VPP: 24.10 (recommended, Agent runtime)
- FRRouting: 8.0+ (Agent runtime, optional)
- controller-gen: For CRD/deepcopy code generation
- Docker: 20.10+ (optional)
git clone https://github.com/akam1o/arca-lb.git
cd arca-lb
make deps
make buildmake manifests
kubectl apply -f config/crd/bases/kubectl apply -f config/rbac/
kubectl apply -f config/manager/kubectl apply -f config/agent/kubectl apply -f config/samples/virtualip_sample.yaml
kubectl get vipmake help # Show available targets
make deps # Download dependencies
make build # Build operator and agent binaries
make test # Run tests
make lint # Run linters
make manifests # Generate CRD manifests (controller-gen)
make generate # Generate deepcopy methods (controller-gen)
make proto # Generate Protocol Buffers code (v1)
make docker # Build Operator and Agent images
make clean # Remove build artifactsFor detailed documentation, see the docs/ directory:
- Installation Guide - Installation steps and setup
- Configuration Guide - How to configure Operator and Agent
- API Reference - CRD API reference and REST API (v1)
- OpenStack Octavia Integration - Octavia provider driver setup
- Octavia Operations Guide - Octavia status checks and route ERROR recovery
- Troubleshooting - Common issues and fixes
- Backend Server Setup Guide - How to configure backend servers
- Architecture - System architecture and design
- Development Environment - Dev environment setup and workflow
- Contribution Guide - How to contribute to the project
Contributions are welcome! See docs/contributing.md.
For inquiries, open an issue on GitHub Issues. For security reports, use GitHub Security Advisories.
Apache License 2.0