Skip to content

GSLB

An authoritative DNS server that answers with a healthy backend chosen from the client's source network, and a console to configure and observe it.

It is built for internal, multi-site services: a client in Paris gets the Paris pool, a client in Lyon gets Lyon, and a pool with no healthy backend falls back to the central one instead of answering nothing. Health comes from HTTP probes (or typed probes: TCP, PromQL), and the DNS process never stores a raw client address.

Three ways to run it

Shape Containers Use it when
Single host DNS + API + web (docker-compose.lot2.yml) One DNS instance is enough
Fleet (HA) one API + web, N DNS nodes (docker-compose.ha-*.yml) Several DNS hosts behind a VIP
DNS only one DNS container, no API You only need resolution, no console

The DNS image installs dnslib, requests and PyYAML only. The API, SQLite and the React console live in their own images and never sit on the resolution path: if the console or the API is down, the DNS keeps answering.

Where to start

  • Install — a working single-host deployment in three commands, then the HA topology.
  • Configuration — the YAML reference and the environment variables.
  • Command line — init, check, routes and probe on the DNS itself, without a console.
  • Probes and health — what makes a backend up, down or unknown.
  • High availability — N DNS nodes, one API, and the optional VIP with keepalived.
  • Operations — saves, reloads, rollback, backups, retention.
  • API — the versioned HTTP surface.
  • Troubleshooting — the failure modes seen in practice.
  • Releases — how versions are numbered, and the tag history.

How an answer is built

client 192.0.2.7
   |
   | A app.example.com
   v
 DNS node ──► zone of the qname
   │            │
   │            ├─ longest-prefix match on the client /24 → pool
   │            ├─ weighted pick among the healthy backends
   │            └─ no healthy backend → default pool, then SERVFAIL
   v
 A 192.0.2.10 (TTL 30)

Every query is counted, including REFUSED, NXDOMAIN, AAAA and the all-down paths, so the console can show what clients actually ask and which networks fall back. Counters are process-lifetime and survive a reload.