CoreDNS-GSLB is a plugin that provides Global Server Load Balancing functionality in CoreDNS. It intelligently routes your traffic to healthy backends based on geographic location, priority, or load balancing algorithms.
What it does:
- Health monitoring of your backends with HTTP(S), TCP, ICMP, MySQL, gRPC, or custom Lua checks
- Reusable healthcheck profiles: Define health check templates globally (in the Corefile) or per zone, and reference them by name in your backends
- Geographic routing using MaxMind GeoIP databases or custom location mapping
- Load balancing with failover, round-robin, random, weighted, IP-hash, GeoIP or GeoIP-affinity selection
- Adaptive monitoring that reduces healthcheck frequency for idle records
- Live configuration reload without restarting CoreDNS
- Bulk backends management via API: Instantly enable or disable multiple backends by location or IP prefix
- Supported record types: Serving dynamic responses for standard
A,AAAA,CNAME,SRV,TXT,SVCB, andHTTPSqueries based on backend status - CNAME Redirection for FQDN Backends: Support hostname/FQDN targets in backend pools, running healthchecks normally and automatically responding with CNAME records if selected
- Wildcard record support: Support for standard DNS wildcard records (
*.domain.tld) - Configurable failover policies: Choose how GSLB answers when all backends are unhealthy (fail-open, fail-closed with custom rcode, or fail-specific with fallback IPs)
- Distributed HA Synchronization: Optional Redis-backed shared health checking with distributed locks (
SETNX), offloaded probing support, and real-time Pub/Sub propagation to synchronize status across multiple CoreDNS instances. - No external database: Records are defined using a YAML file.
- Dynamic backend discovery: Automatic backend pool construction via Consul, HTTP, or DNS (SVCB/HTTPS)
Unlike many existing solutions, this plugin is designed for non-Kubernetes infrastructures — including virtual machines, bare metal servers, and hybrid environments.
- Non-Kubernetes focused: Designed for VMs, bare metal, and hybrid environments
- Multiple health check types: From simple TCP to complex Lua scripting
- Real client IP detection: EDNS Client Subnet support for accurate GeoIP routing
- Resource efficient: Adaptive healthchecks reduce load on unused backends
- Production ready: Prometheus metrics and comprehensive observability
To get up and running quickly using Docker Compose or to compile the plugin locally, check out the Getting Started Guide.
| Topic | Description |
|---|---|
| Getting Started | Quickstart guide and Docker setup |
| Corefile Reference | Complete Corefile parameter reference |
| Supported Records | Supported record types (A, AAAA, SRV, SVCB/HTTPS, TXT, wildcards) |
| Selection & Failover | Failover, round-robin, random, IP-hash, GeoIP, weighted, and failover policies |
| GeoIP Setup | MaxMind databases and custom location mapping |
| Health Checks | Active health checking (HTTP/S, TCP, ICMP, MySQL, gRPC, Lua) and profiles |
| Backend Discovery | Static configs, defaults, tags, and dynamic discovery (Consul, HTTP, SVCB) |
| ECS Compliance | EDNS Client Subnet compliance and caching scope |
| Architecture & Deployments | Standalone and Cluster deployments, Anycast/BGP (RHI), and Consul integration |
| API Reference | REST API endpoints and OpenAPI schema |
| CLI Guide | Command-line client tool |
| Observability | Prometheus metrics |
| Performance Benchmarks | Resource usage and local benchmarking guides |
| Troubleshooting | Troubleshooting and debugging |
| Developer Guide | Development rules, docker environment, compilation, and testing |
Contributions are welcome! Please read the Contributing Guide for local setup and testing instructions.
Tip
Check out these other open-source DNS utilities to enhance your DNS infrastructure monitoring and testing:
- DNS-collector: A high-performance DNS traffic analyzer and collector. Grab your DNS logs, detect anomalies, and finally understand what's happening on your network in real-time.
- DNS-tester: A comprehensive DNS testing and verification toolkit designed to validate DNS response behavior under various network conditions.