Composite Health Policy

Each pool can require a minimum number of healthy members before it will serve any DNS responses. When the healthy member count drops below the threshold, the pool is treated as fully unavailable — the service returns no answer rather than a degraded one.

Configuration

Set minHealthy on a pool. The default (0) disables the feature.

REST API

POST /api/v1/pools
{
  "name": "web-prod",
  "minHealthy": 2
}

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

The field is also returned in all pool responses:

{
  "id": "abc123",
  "name": "web-prod",
  "minHealthy": 2,
  "createdAt": 1715000000,
  "updatedAt": 1715000001
}

TUI (gslbctl)

When creating or editing a pool, the form includes a Min Healthy (0=off) field. Use ↑/↓ to navigate between fields, Enter to submit.

Web UI

Pool Settings → General section → Min Healthy (0 = disabled) input.

Behaviour

The check runs after the health-filtered candidate list is built, before algorithm selection. If minHealthy > 0 and len(healthy candidates) < minHealthy, the DNS resolver returns no answer for that query family (A or AAAA). The service is still considered to exist (no NXDOMAIN), so the client receives an empty answer with the service TTL.

Use cases

• Quorum gate: require at least 2 of 3 backends before serving traffic. Below quorum, let upstream failover or the client retry rather than routing to an overloaded single node.
• Canary protection: a pool with one production node and one canary node — set minHealthy: 2 to stop serving if the canary fails, preventing the production node from absorbing 100% load unexpectedly.
• All-or-nothing: set minHealthy equal to the total member count to enforce that every member must be healthy before the pool participates in DNS resolution.

Interaction with other features

• Failover algorithm: the composite check runs before algorithm dispatch. If the composite check fails, the failover algorithm never runs. Configure a fallback service at the DNS level (e.g. a second service pointing at a backup pool) to handle the unavailable case.
• Score window: per-member health scores are computed independently. The composite count uses the same binary IsHealthy threshold as normal resolution (score > 0 when scoreWindow is set).
• Multi-tenancy: minHealthy is a pool-level setting, scoped to the owning tenant. It is included in NATS state-sync snapshots and replicated to peer nodes.