Pools & members

A pool is a named group of endpoints with a selection method. Records reference pools; the engine picks the answer at query time based on the pool’s method, member priorities, and live health.

This is the GSLB primitive that powers POOL, GEO, and CANARY records.

Anatomy

Pool  (name, selection method)
  └─ Members  (weight, priority, enabled)
       └─ Endpoint  (what to health-check + the IP to return)
            └─ Health status  (up / down)

• Pool: a name plus a selection method (weighted, active-passive, round-robin).
• Member: attaches one endpoint to a pool with a weight, priority, and an enabled flag. The same endpoint can be a member of many pools, with different settings in each.
• Endpoint: the thing we health-check (http/https/tcp, with a target URL or host:port) and the IP we return in DNS answers when it’s up. You can point the probe at a different host/port than the answer.
• Health monitor: an optional, reusable probe policy (interval, timeout, healthy/unhealthy thresholds, expected status). Attach one to many endpoints; leave it off to use the defaults.

Selection methods

Weighted

Distribute traffic across healthy members proportional to weight. Member with weight 100 gets twice the traffic of a member with weight 50.

• Use for: split traffic between regions or providers (60/40 AWS/GCP).
• Down members are skipped; remaining members keep their relative weights.

Active-passive

Always serve the lowest-priority healthy member. Lower number = higher priority. Ties broken by member id.

• Use for: warm-standby setups. Members behind your primary stay idle until it goes down.
• When the primary recovers, traffic shifts back. (Set unhealthy_after high on the primary to avoid flapping.)

Round-robin

Each consecutive query gets the next healthy member in rotation.

• Use for: client-side load balancing where every query lands on a different host (useful for cache warming / spreading bot traffic).
• Note: real-world DNS resolvers cache per name, so rotation only matters across distinct resolvers.

Member weight + priority

Both fields live on the membership, not on the endpoint, so the same endpoint can carry a different weight and priority in each pool it belongs to.

enabled = false removes a member from selection without deleting it, useful for draining for a deploy.

Health monitors

Default behavior (when an endpoint has no health_monitor_id): 30 s interval, 5 s timeout, 2 successive passes to mark up, 3 successive fails to mark down, expected status 200 for HTTP.

Create a named monitor at Load balancing → Health checks to override the defaults across many endpoints in one place. Endpoints that reference it inherit the policy; changes flow live to all of them.

Attaching to records

A pool isn’t visible in DNS until a record references it. Three record types do:

• POOL: direct pool lookup. data = { "pool_id": "<uuid>" }.
• GEO: per-region pool selection. Regions are continents (AF/AS/EU/NA/OC/SA/AN); each region picks a pool, with a default pool for unmatched queries.
• CANARY: time-ramped split between two pools (primary and canary) over ramp_seconds.

See Record types for the exact JSON shapes.

When a pool has zero healthy members

The record returns NODATA (NOERROR with no answer section). DNS doesn’t have a “service unavailable” rcode at the record level, NODATA is the right semantic and is what your TLS load balancer / SDK should retry against another resolver.

This is also surfaced on the dashboard as “zone has a pool with 0 healthy members”, the per-zone health attribution depends on this signal.

Common questions

Can a pool be empty? Yes, but it’s effectively a NODATA-only record. The pool exists; no member to return. You’ll see this during initial setup before adding endpoints.

Can one endpoint be in multiple pools? Yes. The same endpoint can be a member of many pools, carrying a different weight in each, that’s the most common setup.

Does pool selection get cached? No. Every query is evaluated against the current health and member state. When a health check flips a member, the change reaches the DNS edge within about a second.