Health: Warmup Gates

Member Warm-up Gates

When a new member is added to a pool or a disabled member is re-enabled, it immediately enters the live DNS rotation. For backends that take time to initialise — JVM warm-up, cache population, connection pool priming — this can result in the first few seconds of traffic hitting an endpoint that is not yet ready to serve at full capacity.

Warm-up gates hold a member back from DNS responses until it has accumulated a configurable number of consecutive passing health checks, giving the backend time to initialise before it receives production traffic.

How it works

  1. Set warmupThreshold on a member (e.g. 3).
  2. When the member is (re-)enabled or first created, its consecutive-pass counter resets to zero.
  3. On each health check probe cycle, if the probe passes the counter increments; if it fails the counter resets to zero.
  4. While consecutivePasses < warmupThreshold, the member is excluded from DNS candidate selection — it will not appear in any DNS response even if it passes individual health checks.
  5. Once the member reaches warmupThreshold consecutive passes it exits warm-up and enters normal rotation.

The feature is disabled by default (warmupThreshold = 0). Members with no health check configured skip the gate and enter rotation immediately regardless of threshold.

Configuration

REST API

Set on create or update:

<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 class="fu">{</span><span class="er">poolId</span><span class="fu">}</span><span class="er">/members</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;web-03&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;ipAddress&quot;</span><span class="fu">:</span> <span class="st">&quot;10.0.0.3&quot;</span><span class="fu">,</span></span>
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;port&quot;</span><span class="fu">:</span> <span class="dv">80</span><span class="fu">,</span></span>
<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;weight&quot;</span><span class="fu">:</span> <span class="dv">100</span><span class="fu">,</span></span>
<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;warmupThreshold&quot;</span><span class="fu">:</span> <span class="dv">3</span></span>
<span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span>
<span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="er">PUT</span> <span class="er">/api/v1/members/</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;warmupThreshold&quot;</span><span class="fu">:</span> <span class="dv">5</span></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span>

The warmupThreshold field is returned in all member responses.

gslbctl

Add a member with a threshold:

<span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="co"># warmupThreshold is set via the API; gslbctl displays it in member listings</span></span>
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="ex">gslbctl</span> members list <span class="at">--pool</span> <span class="op"><</span>pool-id<span class="op">></span></span>
<span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a><span class="co"># → ID  NAME  IP  PORT  W  PRI  STATUS  REGION  warmup:3</span></span>

Full update (including threshold) is available via the WebUI or API.

WebUI — Topology editor

Open the member slide-over (click any member node), scroll to Warm-up threshold, and set the desired value. A value of 0 disables the gate.

While a member is warming, its node shows an amber "warming X/N" label instead of the usual health state label, where X is the current consecutive-pass count and N is the threshold.

Observability

Member status endpoint

GET /api/v1/members/{id}/status includes three additional fields when warmupThreshold > 0:

<span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;memberId&quot;</span><span class="fu">:</span> <span class="st">&quot;...&quot;</span><span class="fu">,</span></span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;healthy&quot;</span><span class="fu">:</span> <span class="kw">true</span><span class="fu">,</span></span>
<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;warming&quot;</span><span class="fu">:</span> <span class="kw">true</span><span class="fu">,</span></span>
<span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;warmupPasses&quot;</span><span class="fu">:</span> <span class="dv">2</span><span class="fu">,</span></span>
<span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;warmupThreshold&quot;</span><span class="fu">:</span> <span class="dv">5</span></span>
<span id="cb4-7"><a href="#cb4-7" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span>
  • warming — true while the member is in the warm-up gate
  • warmupPasses — consecutive passing probes so far
  • warmupThreshold — the configured target

Pool status endpoint

GET /api/v1/pools/{id}/status includes the same three fields in each member's health entry:

<span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;poolId&quot;</span><span class="fu">:</span> <span class="st">&quot;...&quot;</span><span class="fu">,</span></span>
<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;members&quot;</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a>    <span class="dt">&quot;10.0.0.3&quot;</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb5-5"><a href="#cb5-5" aria-hidden="true" tabindex="-1"></a>      <span class="dt">&quot;healthy&quot;</span><span class="fu">:</span> <span class="kw">true</span><span class="fu">,</span></span>
<span id="cb5-6"><a href="#cb5-6" aria-hidden="true" tabindex="-1"></a>      <span class="dt">&quot;score&quot;</span><span class="fu">:</span> <span class="fl">1.0</span><span class="fu">,</span></span>
<span id="cb5-7"><a href="#cb5-7" aria-hidden="true" tabindex="-1"></a>      <span class="dt">&quot;warming&quot;</span><span class="fu">:</span> <span class="kw">true</span><span class="fu">,</span></span>
<span id="cb5-8"><a href="#cb5-8" aria-hidden="true" tabindex="-1"></a>      <span class="dt">&quot;warmupPasses&quot;</span><span class="fu">:</span> <span class="dv">2</span><span class="fu">,</span></span>
<span id="cb5-9"><a href="#cb5-9" aria-hidden="true" tabindex="-1"></a>      <span class="dt">&quot;warmupThreshold&quot;</span><span class="fu">:</span> <span class="dv">5</span></span>
<span id="cb5-10"><a href="#cb5-10" aria-hidden="true" tabindex="-1"></a>    <span class="fu">}</span></span>
<span id="cb5-11"><a href="#cb5-11" aria-hidden="true" tabindex="-1"></a>  <span class="fu">}</span></span>
<span id="cb5-12"><a href="#cb5-12" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span>

Topology canvas

The member node label transitions through three states:

Label Meaning
warming 2/5 (amber) In warm-up gate; 2 of 5 passes accumulated
healthy (green) Warmed up and in active rotation
unhealthy (red) Failing health checks

Relationship to other health features

Feature Interaction
Health checks Warm-up uses raw probe results, not the smoothed score. Each individual probe pass increments the counter; a single failure resets it to zero.
Score window Score smoothing affects the healthy flag but not the warm-up counter. A member can be in warm-up while simultaneously being considered "healthy" by the score window.
Min healthy Warming members do not count toward minHealthy. If adding a warm-up member would bring the healthy count above the threshold, traffic does not shift until the member exits warm-up.
Composite health Warming members are fully excluded from candidate selection — the same as disabled members — until the gate is passed.

Choosing a threshold

The threshold is in probe cycles, not seconds. Multiply by the health check interval to get wall-clock time.

Health check interval Threshold Time to enter rotation
10s 3 ~30s
10s 5 ~50s
5s 6 ~30s
30s 2 ~60s

For most JVM applications, 3–5 probes at a 10s interval (30–50 seconds) is sufficient. For cold-start containers, consider a longer interval combined with a low threshold.

Re-enable behaviour

When a member is re-enabled after being disabled, its consecutive-pass counter resets to zero and the warm-up gate restarts. This is the intended behaviour — a member returning from maintenance should prove stability before receiving traffic, just like a new member.

When a member's weight, priority, region, or name is changed without toggling enabled, the counter is preserved and warm-up is not restarted.

Was this article helpful?