dynamic-load-balancer

A software-defined-networking load balancer. A Ryu controller speaking OpenFlow 1.3 sits behind a virtual IP and spreads client traffic across a pool of backend servers by installing header-rewriting flow rules in the switch, emulated with Mininet and Open vSwitch.

The problem

A conventional load balancer is a middlebox that every packet crosses. In SDN the control decision and the data path are separate: the controller makes the decision once, for the first packet of a flow, and then programs the switch to apply it to every following packet. That makes the balancing policy ordinary Python code that can be changed without touching the forwarding hardware, which is what this project explores.

Architecture

flowchart LR
    C["h1 client"] -->|"dst = virtual IP 10.0.0.1"| S{"OVS switch s1<br/>OpenFlow 1.3"}
    S -->|"table miss: PACKET_IN"| CTL["Ryu controller<br/>load_balancer.py"]
    CTL -->|"pick backend, install two flow rules"| S
    S -->|"rewrite dst IP/MAC"| B1["h2 10.0.0.2"]
    S -->|"rewrite dst IP/MAC"| B2["h3 10.0.0.3"]
    S -->|"rewrite dst IP/MAC"| B3["h4 10.0.0.4"]
    B1 -.->|"reverse rule: src rewritten back to virtual IP"| C

Loading

How it works

1. On connect, the controller installs a table-miss rule that sends unmatched packets to it.
2. A packet addressed to the virtual IP arrives as PACKET_IN. The controller chooses a backend with the configured algorithm.
3. It installs two flows with a 30 s idle timeout: client to virtual IP is rewritten to the chosen backend's IP and MAC and output on that backend's port; the reverse flow rewrites the backend's source address back to the virtual IP and MAC, so the client only ever sees one address.
4. The first packet is forwarded with the same actions via PACKET_OUT. Subsequent packets of the flow are handled in the switch without involving the controller until the flow idles out.
5. A background thread prints per-backend hit counts and current load every 10 seconds.

Algorithms

Name	Behaviour
round-robin (default)	Cycle through the backends in order.
dynamic	Pick the backend with the fewest assigned flows. Each assignment increments a per-backend counter, and every 10 seconds each counter decays by one to approximate connections ending. This is a connection-count proxy for load, not a CPU measurement.

Switch algorithm by setting self.algorithm in LoadBalancerController.__init__.

Stack

Python, Ryu (OpenFlow 1.3), Mininet, Open vSwitch, a Flask dashboard, Docker for platforms where Ryu does not install natively.

Run it

Needs Linux with Mininet and Open vSwitch (docs/SETUP.md covers Ubuntu natively and Arch through Docker).

./install.sh     # detects the OS and installs dependencies (or builds the Docker image)
./start.sh       # controller, dashboard on :5000, then an interactive Mininet CLI
./stop.sh

Or by hand, which is all start.sh does on Ubuntu:

ryu-manager load_balancer.py                                              # terminal 1
sudo mn --topo single,4 --mac --controller remote --switch ovsk           # terminal 2
sudo ovs-ofctl dump-flows s1                                              # inspect installed rules

Dashboard

dashboard/ is a Flask and Tailwind page that polls /api/stats. It is currently a UI prototype: the statistics are generated randomly and are not read from the controller.

Limitations

This is a learning project and a proof of the flow-rewrite mechanism, not a finished balancer. Known gaps, by reading the code:

• The controller handles IPv4 only: non-IP packets, including ARP, are dropped at the controller. Hosts cannot resolve MAC addresses through the switch unless ARP entries are pre-populated, and nothing answers ARP for the virtual IP.
• The demo topology (mn --topo single,4) numbers hosts 10.0.0.1 to 10.0.0.4, so the virtual IP 10.0.0.1 is also h1's own address. The virtual IP needs to be a separate address and the client a separate host for traffic to exercise the balancer.
• Backend health is not checked, and the backend-to-port map is fixed to h2, h3, h4 on ports 2 to 4.
• Load counters are an estimate (decay on a timer), not measurements of real connections or CPU.
• There are no automated tests and no measurements, so no performance numbers are claimed.

Layout

load_balancer.py   Ryu application: flow installation, backend selection, stats
dashboard/         Flask monitoring page (simulated data)
docs/              setup, usage, architecture and troubleshooting notes
install.sh, start.sh, stop.sh, Dockerfile

Further reading: docs/ARCHITECTURE.md, docs/USAGE.md, docs/TROUBLESHOOTING.md.