Skip to content

Config schema: health

This page lists the fields for the optional health: block on a pool and per-backend probe overrides. For behavior — probes, passive fast-trip, Route eligibility, operator controls — see Backend health.

Location

pools:
  - name: default
    health:          # pool-level health settings
      enabled: true
      ...
    backends:
      - address: "10.0.0.1:53"
        probe_qname: "probe.example."   # optional per-backend override

When health is absent or enabled is false, Conduit does not run health checks for that pool — selection stays weight-based only.

Pool health object

FieldTypeRequiredDefaultDescription
enabledbooleannofalseWhen true, start active probing and health-aware routing for this pool.
interval_msintegerno1000Target time between probe attempts per backend (milliseconds). Minimum 100.
timeout_msintegernosame as interval_msProbe reply timeout (milliseconds). Must be ≥ 1 when set.
riseintegerno3Consecutive successful probes required to mark a backend up. Must be ≥ 1.
fallintegerno2Consecutive failed probes required to mark a backend down. Must be ≥ 1.
probe_qnamestringno.DNS name sent in probe queries (pool template).
probe_qtypestringnoNSQuery type for probes (for example A, AAAA, NS).
acceptable_rcodeslist of stringsno(any well-formed response)When set, only listed RCODE names count as probe success (for example NOERROR, NXDOMAIN). Empty list means any well-formed DNS response proves liveness.
initial_statestringnooptimisticEligibility policy for new backends — see Initial state.
latency_weightingbooleannofalseWhen true, scale effective weight by probe latency EWMA among eligible backends.
min_eligibleintegerno0Fail-open floor — when eligible count in the pool is below this value, Route ignores health and treats all backends as eligible. Must be ≥ 0.
passive_fast_tripbooleannotrueWhen true, live forward timeouts/errors can mark a backend down before probe fall completes.
passive_fallintegerno2Consecutive passive (forward) failures required to mark a backend down. Must be ≥ 1 when set.

Internal constants (not YAML keys): latency EWMA alpha = 0.2; latency weight floor = 0.25 relative to the pool's fastest EWMA.

Initial state

Value Behavior for a new backend
optimistic Eligible immediately until probes or passive fast-trip prove otherwise (default).
require_1_good Not eligible until one successful probe.
require_full_rise Not eligible until rise consecutive successful probes.

At process start, the fail-open floor covers pools where every backend is still unknown.

Per-backend overrides

Nested under pools[].backends[] when health is enabled for the pool:

Field Type Required Default Description
probe_qname string no pool probe_qname Override probe query name for this backend only.
probe_qtype string no pool probe_qtype Override probe query type.
probe_source string no (system bind) Local IPv4 or IPv6 address to bind for probes to this backend.
transport string no — Reserved / forward-compatible only. Not honored when it diverges from forward.upstream_transport. Probes always use the global forward transport.

The backend label on health metrics uses the configured name when set, otherwise address.

Validation summary

Rule Error if violated
interval_ms ≥ 100 health.interval_ms … is below the 100ms floor
timeout_ms ≥ 1 when set health.timeout_ms must be >= 1 when set
rise / fall ≥ 1 health.rise must be >= 1 / health.fall must be >= 1
passive_fall ≥ 1 when set health.passive_fall must be >= 1 when set
Valid probe_qtype health.probe_qtype: …
Valid acceptable_rcodes names health.acceptable_rcodes: …
Valid initial_state health.initial_state '…' must be optimistic, require_1_good, or require_full_rise
Valid probe_source address per-backend parse errors

Validate with conduitctl validate --file … or at load time.

Reload behavior

  • Hot: probe configuration fields reload with the runtime snapshot.
  • Preserved: health state for unchanged backends (same address and probe semantics).
  • Reset: new backend, address change, or probe-semantics change.

See Backend health — Reload and health state.

Example

pools:
  - name: default
    health:
      enabled: true
      interval_ms: 1000
      timeout_ms: 500
      rise: 3
      fall: 2
      probe_qname: "health.example."
      probe_qtype: A
      acceptable_rcodes:
        - NOERROR
        - NXDOMAIN
      initial_state: optimistic
      latency_weighting: true
      min_eligible: 1
      passive_fast_trip: true
      passive_fall: 2
    backends:
      - address: "10.0.0.1:53"
        name: resolver-a
        weight: 70
      - address: "10.0.0.2:53"
        name: resolver-b
        weight: 30
        probe_qname: "resolver-b.health.example."