Powered by eniston
  1. Overview
  2. Getting Started
  3. Architecture Overview

Architecture Overview

Nexus GSLB is a DNS-based Global Server Load Balancer (GSLB). It answers A/AAAA queries and selects backend IPs using a health-aware, client-IP-aware load balancer.

The data model has three clearly-separated layers:

  • Data-plane objects (pools, members, services, health checks, geo rules, users, …) live in rqlite — a Raft-replicated SQLite cluster — and are managed via the REST API / WebUI / Terraform / gslbctl. rqlite handles cross-node replication.

  • Configuration (YAML) is owned by git and applied per-node via GitOps self-restart: each node independently detects a repo change, validates it, rewrites its own config, and gracefully restarts. No coordinator.

  • Ephemeral cluster state (health transitions, membership heartbeats, RTT samples, sessions) is exchanged over NATS + JetStream with TTLs. NATS carries nothing durable.

Metrics are exposed for Prometheus. Licensing enforces request rate limits.

Core components

DNS Server

  • Listens for DNS queries for a configured domain.

  • Extracts the DNS client's IP from the UDP remote address.

  • Service-aware resolution: on each query, the DNS server first looks up the queried name in the services table. If a matching service has a pool assigned, members of that pool are used (enabled members only). Falls back to the static load balancer for domains not found in the DB.

  • Enforces licensing limits before answering.

  • Emits Prometheus metrics.

TUI (gslbctl)

  • Standalone terminal client; connects directly to the rqlite datastore (no API server required).

  • Tab navigation between Pools and Services.

  • Pool view: list, create, rename, delete; drill into pool for Members, Health Check, Geo Rules sub-screens.

  • Service view: list, create, edit, delete; pool assignment uses a dedicated picker screen.

Load Balancer

  • Multiple selection algorithms: round-robin, weighted round-robin, geo-ip, map-file, and failover. Each algorithm is selectable per service.

  • Member mutations from the REST API are reflected immediately in the running balancer — no restart required.

Storage

  • rqlite (Raft-replicated SQLite) cluster. All nodes form one rqlite Raft cluster over the WireGuard / private network.

  • Foreign keys enabled, so cascade deletes fire automatically when a pool is removed.

  • Schema migrations are additive and idempotent — safe to run across upgrades; the previous binary can still read the new schema.

  • All connection details are configured under rqlite: in config.yaml.

REST API

  • Full CRUD for pools, members, services, health checks, and geo rules.

  • Input validation for IP addresses, ports, and CIDR blocks.

  • Member mutations are reflected immediately in the running balancer.

  • Empty collections return [] (not null) for JSON compatibility.

Health Checker

  • Active health checks (TCP, HTTP/HTTPS, ICMP, script, webhook) at intervals with timeouts.

  • Per-endpoint status, aggregated into pool and member health endpoints.

GitOps Controller

  • Polls a Git repo at intervals.

  • Enforces GPG-signed commit policy.

  • Validates and applies config with safe rollback (last-good retained in-process).

State Sync

  • NATS + JetStream for ephemeral cluster state only (health transitions, membership heartbeats, RTT samples, sessions).

  • TTL'd KV buckets ensure stale data is automatically evicted.

  • Composite health policies (prefer-local, local-only, global-any-healthy, global-quorum) merge local and peer views.

Metrics

  • Prometheus endpoint at /metrics when enabled.

  • All metrics carry cluster and node labels when configured.

Licensing

  • Validates signed license tokens.

  • Enforces per-tier RPS limits in the DNS path.

  • Credentials loaded from environment variables or the config file.

Data flows

DNS query path

  1. Request enters DNS server; client IP extracted from UDP remote address.

  2. Licensing check for RPS.

  3. Service lookup: if a service with an assigned pool is found, enabled members of that pool are used.

  4. If no DB match, the Balancer selects the next healthy IP from the static endpoint set.

  5. Response constructed as A/AAAA answer.

Health checking

  1. Checker loops across endpoints at configured interval.

  2. Performs the configured probe.

  3. Stores last-known status in memory and publishes transitions.

REST API → Balancer live update

Mutations to members are reflected in the running balancer immediately. The next DNS query picks up the change without restart.

GitOps reconciliation

  1. Fetch repo; verify GPG signature.

  2. Parse YAML; validate configuration.

  3. Apply the new config and graceful restart.

State synchronization

Each node publishes local health and heartbeats and subscribes to peer events. A composite health view merges per-node reports; the configured policy drives routing decisions.

Operations at a glance

  • Configure via YAML (local file or fetched by GitOps).

  • Manage pools/members/services at runtime via REST API; changes take effect immediately.

  • Optional NATS settings enable global state sync and config distribution.

  • Prometheus metrics served at /metrics when enabled.

  • Secure-by-default HTTP health checks (TLS verification on unless explicitly disabled).

Was this article helpful?
© 2026