Skip to content

Use cases

pygslb answers one question: which of my backends should this client use right now? It answers with the client's source network, the health of each backend, and a YAML file you can read in a code review. This page lists what that buys an internal infrastructure team, with the configuration for each case.

Every scenario below is implemented by the code shipped in this repository; the file named at the end of each section is where it lives.

1. Two sites, clients routed by network

An internal service runs in Paris and in Lyon. A client in the Paris office must reach the Paris backends, not cross the WAN.

zone: app.example.com.
default_pool: paris
pools:
  paris: [{name: paris-1, ip: 192.0.2.10, healthcheck_url: http://192.0.2.10/health}]
  lyon:  [{name: lyon-1,  ip: 192.0.2.20, healthcheck_url: http://192.0.2.20/health}]
network_rules:
  - name: Lyon office
    cidr: 10.20.0.0/16
    pool: lyon
  - name: Paris office
    cidr: 10.10.0.0/16
    pool: paris

Longest prefix wins, and the sort is computed once at load, never taken from the file order — overlapping rules stay predictable when the file is edited. gslb/mapper.py.

2. A site goes down: fail over, do not black-hole

Backends are probed every interval seconds. Two consecutive failures mark a backend DOWN (fail_threshold: 2), one success brings it back. The asymmetry is deliberate: fail slowly so a single lost packet does not remove capacity, recover on the first good answer.

When every backend of the matched pool is DOWN, the query is served by default_pool and counted under the pool_unavailable reason. Only when the default pool is empty too does the DNS answer SERVFAIL — the client sees a failure instead of a stale address pointing at a dead host.

gslb/health.py, gslb/manager.py, gslb/resolver.py.

3. Planned maintenance without a false alarm

You want to drain a node for a kernel upgrade, without deleting it from the YAML and without an incident in the monitoring.

  - name: paris-2
    ip: 192.0.2.11
    healthcheck_url: http://192.0.2.11/health
    maintenance: true

The backend stays configured, keeps being probed, and no longer receives answers; no DOWN transition is recorded while it is withdrawn, and flipping the flag back returns it immediately on the next reload. The console shows the state as a badge, so "why is this node not answering?" has an answer other than a guess. gslb/backend.py, gslb/manager.py.

4. Progressive rollout with weights

A new backend generation comes in at 10 % of the traffic before it takes everything. Smooth weighted round-robin makes this a one-line change:

  - {name: old-1, ip: 192.0.2.10, healthcheck_url: http://192.0.2.10/health, weight: 9}
  - {name: new-1, ip: 192.0.2.30, healthcheck_url: http://192.0.2.30/health, weight: 1}

weight: 0 also withdraws a backend from the answers, but it is the routing way to say it: the weighted distribution is the knob, the console shows the weight, and the probe history continues. Use maintenance when the reason is an operator intervention — it is the flag the console exposes and the one that suppresses DOWN events while the node is out. Weights survive a reload, so a drain does not restart from an arbitrary distribution. gslb/manager.py, gslb/backend.py.

5. IPv6 without breaking IPv4

A backend can answer A and AAAA with one configuration:

  - name: paris-1
    ip: 192.0.2.10
    ipv6: 2001:db8::10
    healthcheck_url: http://192.0.2.10/health

A backend without ipv6 is simply absent from AAAA answers; a pool where no backend has one answers NOERROR with an empty answer set, not an error. Health is per backend, not per family: one node, one verdict. The routing events record the address family, so the console can tell an AAAA question from an A one. gslb/resolver.py, gslb/backend.py.

6. Several services, one process

A larger team often ends up with a handful of internal names, each with its own pools. They can share one deployment with isolated pools: a zone cannot reference another zone's pool, and a query for a name outside every configured apex is REFUSED rather than answered by a neighbouring zone.

zones:
  app.example.com.:
    ttl: 30
    default_pool: central
    pools: {central: [...]}
  api.example.com.:
    ttl: 60
    default_pool: edge
    pools: {edge: [...]}

gslb/zones.py, gslb/runtime.py.

7. The console may be down; resolution may not

The management stack (API, SQLite, React console) is not on the resolution path: a DNS node asks it for its configuration, never for an answer. Stop the API and the nodes keep answering what they already have; start it again and they pick up the next save. That is the whole reason the deployment is split in three containers rather than one process.

gslb/sync.py, docs/ha.md.

8. Find out what your clients really do

Two features make the routing decision auditable instead of hopeful:

  • dig @<gslb> _whoami.<zone> TXT returns the client address as the DNS sees it — the only way to know whether your CIDR rules describe clients or a central recursive resolver;
  • the counters bucket clients by /24 (never a raw address) and per fallback reason, so the console can show which networks fall back to the default pool and why.

The learning detector turns that into a proposal: a network that keeps falling back appears as a candidate rule, with its hit count and its number of distinct hosts, ready to pre-fill the configuration form. gslb/resolver.py, gslb/mapper.py, api/detectors.py.

9. Protect a pool from a query storm

An opt-in circuit breaker counts queries per pool, compares the window with an exponential moving average of the previous ones, and, above factor times that reference, answers from default_pool for cooldown seconds. It reroutes; it never marks a backend DOWN, so probing and the health model are untouched.

circuit_breaker:
  factor: 4
  window: 10
  cooldown: 60

Off by default, because a breaker that trips on normal traffic is worse than no breaker. gslb/breaker.py.

What the operator sees

The console is not decoration: every screen answers a question an operator asks during an incident.

The configuration is edited in place, and the YAML stays the source of truth. Weights, IPv6 addresses, maintenance flags and probes are changed from the pages that own them; every edit joins a pending list, the console shows the canonical diff, and only the save writes — validate, write atomically, wait for every node to acknowledge, roll back on refusal.

Every node is accounted for. Settings lists the nodes with their configuration state, worker count and snapshot age; a node that stopped reporting is visible before a client complains.

Health is computed per backend, per probe. The Backends page shows the state each backend reports — up, down, unknown, degraded, maintenance — and the alerts bell surfaces the ones that need attention. The API also samples availability once per minute per backend, so an outage is a gap in the history, never a false green.

And the counters answer "who asks what". Answers per pool, per rule and per fallback reason, plus the per-backend distribution and the top client networks — the evidence behind a rule you are about to add.

Where it is not the right tool

  • Public-facing DNS at Internet scale. pygslb is authoritative and modest: one Python process per node, no anycast, no DNSSEC, no DoT/DoH. A managed provider or a specialised high-QPS server is a better fit.
  • Routing by geography or by measured latency. The routing key is the client source network. Behind a single central resolver every client collapses to one address, and no amount of configuration changes that (ECS is out of scope).
  • Replacing a full DDI suite. No DHCP, no IPAM, no zone transfer, no registrar glue: one YAML file, one computed zone content.

The comparison page puts these limits next to what the alternatives do, and the security page lists what is hardened and what stays the operator's job.