Health: 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

  1. Set fallbackCname on a pool (e.g. maintenance.example.com).
  2. 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.
  3. The CNAME TTL is inherited from the service's configured TTL (default 60s).
  4. 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:

<span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="er">POST</span> <span class="er">/api/v1/pools</span></span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;name&quot;</span><span class="fu">:</span> <span class="st">&quot;prod-web&quot;</span><span class="fu">,</span></span>
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;minHealthy&quot;</span><span class="fu">:</span> <span class="dv">1</span><span class="fu">,</span></span>
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;fallbackCname&quot;</span><span class="fu">:</span> <span class="st">&quot;maintenance.example.com&quot;</span></span>
<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span>

Set on pool update:

<span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="er">PUT</span> <span class="er">/api/v1/pools/</span><span class="fu">{</span><span class="er">id</span><span class="fu">}</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;name&quot;</span><span class="fu">:</span> <span class="st">&quot;prod-web&quot;</span><span class="fu">,</span></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;minHealthy&quot;</span><span class="fu">:</span> <span class="dv">1</span><span class="fu">,</span></span>
<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;fallbackCname&quot;</span><span class="fu">:</span> <span class="st">&quot;maintenance.example.com&quot;</span></span>
<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span>

Clear the fallback (disable circuit breaker):

<span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="er">PUT</span> <span class="er">/api/v1/pools/</span><span class="fu">{</span><span class="er">id</span><span class="fu">}</span></span>
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;name&quot;</span><span class="fu">:</span> <span class="st">&quot;prod-web&quot;</span><span class="fu">,</span></span>
<span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;fallbackCname&quot;</span><span class="fu">:</span> <span class="st">&quot;&quot;</span></span>
<span id="cb3-5"><a href="#cb3-5" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span>

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

gslbctl

<span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="co"># Create pool with circuit breaker</span></span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="ex">gslbctl</span> pools create <span class="at">--name</span> prod-web <span class="at">--min-healthy</span> 1 <span class="at">--fallback-cname</span> maintenance.example.com</span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a><span class="co"># Update existing pool to add circuit breaker</span></span>
<span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a><span class="ex">gslbctl</span> pools update <span class="op"><</span>id<span class="op">></span> --name prod-web <span class="at">--fallback-cname</span> maintenance.example.com</span>
<span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb4-7"><a href="#cb4-7" aria-hidden="true" tabindex="-1"></a><span class="co"># Clear the fallback</span></span>
<span id="cb4-8"><a href="#cb4-8" aria-hidden="true" tabindex="-1"></a><span class="ex">gslbctl</span> pools update <span class="op"><</span>id<span class="op">></span> --name prod-web <span class="at">--fallback-cname</span> <span class="st">&quot;&quot;</span></span>
<span id="cb4-9"><a href="#cb4-9" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a><span class="co"># List — fallback is shown when set</span></span>
<span id="cb4-11"><a href="#cb4-11" aria-hidden="true" tabindex="-1"></a><span class="ex">gslbctl</span> pools list</span>
<span id="cb4-12"><a href="#cb4-12" aria-hidden="true" tabindex="-1"></a><span class="co">#   <id>  prod-web  minHealthy:1  fallback:maintenance.example.com</span></span>

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 &quot;nexus_pool&quot; &quot;web&quot; {
  name           = &quot;prod-web&quot;
  min_healthy    = 1
  fallback_cname = &quot;maintenance.example.com&quot;
}

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.

Was this article helpful?