Skip to content

Relay Fleet

The relay fleet is a set of forwarding nodes that give gateways without a public address a way to receive inbound connections. Each relay is a small VM (Scaleway DEV1-S) running relayd. A gateway that publishes a service is assigned to a relay, and visitors reach the service through that relay's address.

The fleet page at Admin > Relays (/admin/relays) is visible only to platform administrators. It shows every relay in the fleet with its health, hostname, version, session counts, and drain state.

Fleet configuration

Each environment with a fleet (dev and prod) declares it in infra/terraform/environments/<env>/relay.tf:

Variable Meaning
relay_count How many relays to run. Default 0 provisions nothing.
relay_zone_suffix Zone holding per-gateway names; empty turns published names and certificates off. Prod uses r.prod.digilan-edge.com.
relay_subdomain Prefix of the relay host records in the main zone (prod default prod-relay).
relay_instance_type, relay_ports Instance size (default DEV1-S) and WireGuard UDP ports (default 51820).
relayd_package_url, relayd_package_token The relayd release to install, and the read-only registry token (supplied as TF_VAR_relayd_package_token).

Each environment's fleet is independent: a gateway is only ever handed relays by its own environment's nexus.

Relay states

Each row shows one state, checked in this order:

State Meaning
Gone quiet No heartbeat for more than 90 seconds. Not assigned new gateways. A brief quiet window can follow a restart or a network blip; a relay whose instance was destroyed stays here until it is reaped.
Reports itself unwell Heartbeating, but reporting itself unhealthy.
Draining Marked for maintenance. No new gateways are assigned; gateways already on it move off as they check in.
Well Heartbeating and healthy. Available for new gateways.

Older instances that share a hostname with a live relay (left behind by a replacement) are grouped under Replaced instances (n), collapsed by default.

Draining a relay

Click Drain on the relay's row, then Drain it to confirm. The dialog says how many gateways will move. The effect is immediate in the allocator but gradual on the fleet:

  • New gateways are assigned to other relays right away.
  • Existing gateways keep their tunnel and their published services continue to work through this relay. They re-evaluate their relay assignment every 5 minutes (the Keeper tick). On the next tick, the gateway sees that its relay is draining, asks for a new one, and migrates.
  • Worst-case migration time for one gateway is approximately 6.5 minutes: one 5-minute Keeper tick, plus about 35 seconds for the new relay to learn the gateway's WireGuard peer, plus up to 60 seconds of DNS propagation for visitors.

The drain flag is sticky: the relay's own heartbeat cannot clear it. Only the fleet page's Put back in service button clears it.

Do not destroy a relay before its gateways have migrated

Confirm the relay's Gateways count is 0 before replacing it. Destroying a relay with gateways still on it drops their published services for up to 6 minutes.

Putting a relay back in service

Click Put back in service on the relay's row. The relay becomes available for new gateway assignments within 30 seconds (on its next heartbeat).

Gateways that already migrated to another relay stay there — the allocator's stickiness keeps a gateway on its current relay as long as that relay is well. Only a quiet, unwell, draining or full relay triggers a move.

What users see during a migration

While a gateway is moving between relays:

  1. Published services continue working on the old relay until the gateway's Keeper tick fires.
  2. The gateway climbs to its new relay — this takes a few seconds.
  3. Visitors may see a brief interruption of up to 60 seconds while DNS records propagate to the new relay's address (TTL is 60 seconds).

The gateway's published URL does not change. The URL is tied to the gateway, not the relay.

Mixed-version fleet

The fleet page shows each relay's version. During a rolling replacement, a mixed-version fleet is normal and expected. The allocator handles mixed versions correctly: a gateway assigned to a relay without rung 3 support falls back to rung 1 or 2, and a gateway assigned to a relay with rung 3 can use it.

Stale relay cleanup

A relay that has been silent for 7 days and has no attached gateways is reaped by nexus's hourly sweep. The sweep first withdraws the relay's tunnel.<relay-id>.<zone> DNS record, then deletes the row. If the record cannot be withdrawn, the row is kept and the next sweep retries. The relay's host record belongs to Terraform and is not touched.

See also