README.md

What is CoreDNS-GSLB?

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, and HTTPS queries 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

🚀 Getting Started

To get up and running quickly using Docker Compose or to compile the plugin locally, check out the Getting Started Guide.

📚 Documentation

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

Contributions are welcome! Please read the Contributing Guide for local setup and testing instructions.

🧰 Related Projects