github/glb-director: a stateless L4 director for BGP and ECMP datacenters

The problem GLB Director solves: ECMP reshuffling on bare metal

When several servers announce the same IP address over BGP, datacenter routers spread traffic across them with ECMP. That sharding is per-flow and uses consistent hashing, so it is stable while the set of nodes is stable. Add or remove a node and flows get remapped. Connections land on machines that never saw their first packet.

The usual fix is to store flow state on the director nodes and share it between them. The README describes that as the traditional approach, naming LVS as an example. GLB Director takes the other route. It keeps no flow state on the director and instead hashes each flow to a pair of servers with a pre-determined order, then relies on state that already exists on those servers. The README calls this the second chance design, documented under docs/development/second-chance-design.md.

Who this is for: operators running their own metal, with control over BGP announcements and router configuration. The README states the project is used in production to serve all traffic from GitHub's datacenters, which tells you the intended scale. It is not for someone who wants a reverse proxy they can point a DNS record at.

How the director tier fits a split L4/L7 design

GLB Director implements only the L4 tier of a split L4/L7 load balancer. The README's component overview image shows the shape: directors in front, proxy layer servers behind, clients on the other side.

Ingress is the only direction the director handles. It processes incoming packets and encapsulates them inside an extended Generic UDP Encapsulation packet, with the header format described in docs/development/gue-header.md. Return traffic does not pass back through the director. Proxy layer servers send egress packets straight to clients using Direct Server Return.

The consequence is that the director is a packet forwarder rather than a connection terminator. It never completes a TCP handshake with the client, so it cannot inspect HTTP, terminate TLS, or rewrite headers. Anything that needs to understand the request has to happen on the proxy layer behind it. That split is what lets the L4 tier stay stateless and cheap per packet, and it is also the reason a single GLB Director deployment cannot replace an ingress controller on its own.

Installing GLB Director packages and running the Vagrant example

The README does not put install commands in the top-level document. It points to docs/setup/packages-quick-start.md for the packages provided and how to install them, and to docs/setup/example-setup-vagrant.md for a local instance with all required components. The repository ships a Vagrantfile at the top level, so the example setup is the intended first contact.

The Makefile builds Debian packages for each component. Note the escape hatch: setting GLB_SKIP_DPDK_DIRECTOR=1 skips the DPDK glb-director package, and in that mode the build still produces glb-director-cli, which the Makefile comments describe as a runtime dependency of glb-director-xdp. The comment says this mode exists for distros where DPDK 17 or KNI is unavailable, naming Ubuntu noble as an example.

# Build all packages, including the DPDK director
make mkdeb

# Build without the DPDK director (e.g. on Ubuntu noble)
make mkdeb GLB_SKIP_DPDK_DIRECTOR=1

The test dependencies are pinned in requirements.txt and are installed with pip. They include pyroute2, scapy, siphash and netaddr, which hints at what the tests manipulate: routes, packets and the hash function.

pip install -r requirements.txt

After that, the practical next step is the Vagrant guide rather than a production rollout, because the guide is the only complete wiring the repository documents.

Where GLB Director is the wrong tool

The design assumes ECMP. If your routers do not shard traffic across equal-cost paths to the same announced address, the whole premise of hashing flows to a pair of servers falls apart. The README frames the project as being for datacenter environments where multiple servers announce the same IP via BGP, and that is a precondition, not a suggestion.

It also assumes a proxy layer that already keeps per-flow state, because the second chance mechanism depends on state stored on those servers to let flows complete while a server drains. Deploy GLB Director with a backend that does not hold that state and you lose the property the design is built around.

The build story is a second constraint. The Makefile comment about DPDK 17 and KNI being unavailable on some distros is a signal that the DPDK director path is tied to a particular kernel and userspace generation. Running this on a cloud VM or a managed Kubernetes cluster is not what it is for. There is no documented path in the README for those environments, and the README does not document rollback or upgrade procedures for a running director.

GLB Director compared with LVS and with an L7 proxy

The README names LVS directly as the traditional alternative. The difference is where flow state lives. LVS stores flow state on each director node and shares it between nodes; GLB Director stores none on the director and pushes the problem to the hashing scheme plus the backend's existing state. The README describes the hash as a derivative of rendezvous hashing, with the details in docs/development/glb-hashing.md.

A second comparison is with an L7 proxy such as nginx or HAProxy. Those terminate connections, so they can do TLS, path routing, retries and health-based ejection of a backend. GLB Director does none of that at the director tier, by design: it forwards encapsulated packets and lets the proxy layer do the rest. If your requirements stop at spreading TCP flows across a fleet of metal servers and your routers already do ECMP, the L4 approach avoids the state-synchronisation problem entirely. If your requirements include reading the request, it is the wrong layer and no amount of configuration changes that.

Maintenance, packaging and the licence split

The last push to the default branch was on 2026-09-28, and the repository is not archived. The most recent release listed is v1.0.7 from 2020-09-16, so tagged releases are rare even though the branch still receives commits. Plan for building from the branch rather than waiting for a release artifact.

The Makefile is the upgrade surface. It builds packages for glb-redirect, glb-healthcheck and glb-director-xdp, and conditionally for the DPDK director. Upgrading means rebuilding those packages and redeploying them; the README does not describe a rolling upgrade procedure for a live director fleet, and it does not document rollback. Treat that as an open question to answer in your own environment before you depend on it.

On licensing, the README states that components in the repository are licensed under BSD 3-Clause except where required to be GPL v2 depending on their dependencies and usage, and points to LICENSE.md for the detail. The repository metadata reports the licence as NOASSERTION, which means GitHub could not classify it automatically. The practical effect is that the licence of a given component depends on what it links against, so read LICENSE.md before redistributing a built package. This is not legal advice.

Editorial conclusion

Adopt GLB Director only if you run bare metal servers that can announce the same IP over BGP and you already have an L7 proxy tier behind it; the example Vagrant setup is the cheapest way to see whether that shape fits before committing hardware. If you need a single box that terminates TLS and routes HTTP, this is the wrong layer. Verify first that your routers shard by ECMP, that your kernel and distro can build the packages (the Makefile exposes GLB_SKIP_DPDK_DIRECTOR=1 for distros where DPDK 17 or KNI is unavailable), and that you accept the BSD 3-Clause and GPL v2 split described in LICENSE.md.

Frequently asked questions

Official sources

1. github/glb-director on GitHub
2. Issues
3. README
4. Releases