Skip to content

Retire a host

nerthus-config host retire ends a host's membership of the estate. It is the last of the three times the tool reaches a host over SSH. Use it when a machine is returned to its provider, reinstalled for another purpose, or replaced.

What retire does, in order

  1. Refuses while anything else names the host. A site whose hub it is, an instance running on it, a WireGuard peer: each is moved or retired first, and retire lists them. Tunnels and DNS records are not in that list, because retire removes them itself.
  2. Takes the agent off the host, over SSH, with the host key the row names: the timer, the agent, its identity and read key, its configuration, its checkout and its decrypted secrets. --unreachable skips this half for a machine that is already gone.
  3. Declares the retirement on your checkout's branch: the row moves under retired: in inventory/hosts.yaml with the date and your reason; the host's sops_recipient and its read key's deploy key are removed; vault/hosts/<host>/ is deleted; the tunnels the host runs and the DNS records pointing at it or at those tunnels are removed from the declaration. validate judges the result.

Nothing is deleted at a provider by retire. The deploy key, the tunnels and the DNS records disappear from the declaration; the next plan shows them as delete rows, and nerthus-config apply . --from laptop carries those out after you have read them.

The procedure

Dry run first. It lists what would be removed and changes nothing:

cd ~/gitlab/margonem/nerthus/it/Nerthus.Infra
nerthus-config host retire nerthus-host-11 --reason "returned to the provider"

Then the retirement itself, which pushes the branch and opens the merge request:

nerthus-config host retire nerthus-host-11 --reason "returned to the provider" --no-dry-run

After the merge, plan and apply the deletions:

nerthus-config plan --against live .
nerthus-config apply . --from laptop --only gitlab_deploy_key

What stays

The retired row keeps the host's name readable: an agent that is still running somewhere refuses with host.retired, and a later host adopt of the same name refuses too. Git keeps the history of vault/hosts/<host>/, and removing a file does not recall the copies taken while it existed: a secret that host held is rotated, not just forgotten.