Skip to content

Add a host that serves reads

A site answers on one hostname, and every host whose instance carries the read role runs a replica of that site's tunnel. Adding one is a declaration and a converge; no DNS record moves and no host is ever pushed to.

Before you start

The host is adopted already — Adopt a host — and the site has a pin (Move a site's pin). The tunnel exists, with its connector token in the vault.

Declare it

In Nerthus.Infra, three edits in one merge request:

  1. inventory/hosts.yaml: the host's row names the site under sites: and carries site-host among its roles.
  2. inventory/sites.yaml: an instance row for it — site, host, kind: site, and roles including read.
  3. The site's vault directory for that host holds the connector token, under the name the minter wrote it as: CLOUDFLARE_TUNNEL_TOKEN_<TUNNEL>, with - as _ and uppercased.

The plan on the merge request shows the instance appearing. Merge on green.

What converges, and what decides the connector

On its next tick the host's agent renders two compose projects:

  • nerthus-<env>-<site> — the instance itself. It publishes no port.
  • nerthus-<env>-<site>-edge — the cloudflared connector, only when the instance's roles include read. The connector joins the instance's network namespace, so its origin is plain loopback, and it dials out to Cloudflare; the host opens nothing inbound.

A site-host whose instance has no read role gets the first and not the second. That is not a special case — the dev site's worker box is exactly that, and the condition is what keeps a connector off it.

The token reaches the container as a file mount, never as an environment variable: the variable's own name would say what it holds, and nerthus secrets scan-env reports that as a finding.

Check it

  • nerthus-config cookbook plan site-host --host <host> is empty after the tick.
  • The apex answers, and stopping the connector on one host leaves it answering from another.
  • docker inspect of the instance shows no secret in its environment.

Removing one

Take the read role off its instance row, or the instance row off the host, and merge. The next tick brings the edge project down; the tunnel and the hostname are untouched, because they belong to the site rather than to the host. Retiring the machine itself is Retire a host.