Circuit Breaker

DNS Circuit Breaker

When a pool loses all healthy members — whether from failed health checks, warm-up gates holding members back, or the minHealthy threshold not being met — DNS queries for services that use that pool would normally return NXDOMAIN or an empty answer.

The DNS circuit breaker lets you configure a fallback CNAME target on a pool. When the pool collapses, DNS responses return a CNAME record pointing to the fallback target instead of NXDOMAIN. This allows a downstream resolver to reach a maintenance page, a static fallback, or a secondary service that can absorb traffic while the primary pool recovers.

How it works

Set fallbackCname on a pool (e.g. maintenance.example.com).
When all of the following are true, the fallback CNAME is returned:
- The pool has no healthy, warm, enabled members eligible for selection or the number of healthy members is below minHealthy.
The CNAME TTL is inherited from the service's configured TTL (default 60s).
When healthy members return, the pool recovers automatically and normal A/AAAA answers resume.

The feature is disabled by default (fallbackCname is empty). Pools without a configured fallback return NXDOMAIN or a NODATA response when collapsed (existing behaviour).

Configuration

REST API

Set on pool create:

POST /api/v1/pools
{
  "name": "prod-web",
  "minHealthy": 1,
  "fallbackCname": "maintenance.example.com"
}

Set on pool update:

PUT /api/v1/pools/{id}
{
  "name": "prod-web",
  "minHealthy": 1,
  "fallbackCname": "maintenance.example.com"
}

Clear the fallback (disable circuit breaker):

PUT /api/v1/pools/{id}
{
  "name": "prod-web",
  "fallbackCname": ""
}

The fallbackCname field is returned in all pool responses (omitted when empty).

gslbctl

# Create pool with circuit breaker
gslbctl pools create --name prod-web --min-healthy 1 --fallback-cname maintenance.example.com

# Update existing pool to add circuit breaker
gslbctl pools update <id> --name prod-web --fallback-cname maintenance.example.com

# Clear the fallback
gslbctl pools update <id> --name prod-web --fallback-cname ""

# List — fallback is shown when set
gslbctl pools list
#   <id>  prod-web  minHealthy:1  fallback:maintenance.example.com

WebUI — Topology editor

Open the pool slide-over (click any pool node), scroll to Fallback CNAME (circuit breaker), and enter a hostname. Leave blank to disable.

Terraform

resource "nexus_pool" "web" {
  name           = "prod-web"
  min_healthy    = 1
  fallback_cname = "maintenance.example.com"
}

DNS response example

When prod.example.com. is configured on a service backed by a collapsed pool with fallbackCname = maintenance.example.com:

;; ANSWER SECTION:
prod.example.com.  60  IN  CNAME  maintenance.example.com.

Resolvers that received the CNAME will follow it to whatever maintenance.example.com resolves to. The CNAME itself is not resolved by the GSLB daemon — the client's resolver handles the chain.

Relationship to other pool features

Feature	Interaction
Health checks	Fallback triggers when all health-checked members fail. Pools with no health check configured are always treated as healthy — the fallback never fires unless you add a health check.
Warm-up gates	Warming members do not count as available candidates. If every member is warming, the pool is treated as collapsed and the fallback fires.
Min healthy	If the healthy count is below `minHealthy`, the pool is treated as collapsed and the fallback fires even if some members are healthy.
IPv4 / IPv6	The circuit breaker applies independently per address family. If IPv4 members are all down but IPv6 members are healthy, IPv4 queries get the CNAME while IPv6 queries get normal answers.
Filter chains	The fallback applies after the filter chain fails to produce a candidate. The CNAME is emitted at the DNS layer, not by the filter chain executor.
DNSSEC	CNAME answers are signed normally when DNSSEC is enabled.

Choosing a fallback target

The fallback target must be reachable by your clients. Common patterns:

Maintenance page: a CDN-hosted origin (maintenance.cdn.example.com) that serves an HTTP 503 page.
Secondary region: another GSLB service or load balancer in a different region.
Static IP alias: a hostname that resolves to a known static IP (e.g. a dedicated fallback server).

Avoid pointing the fallback at another GSLB service backed by the same pool — that creates a circular dependency and the second CNAME lookup will also return a CNAME.