railiance-infra/docs/convergence.md

🔧 Server Convergence

After provisioning servers with Terraform, railiance-infra uses Ansible to bring them into a secure and usable baseline state.
This process is called convergence.

What Convergence Does

When you run make converge, Ansible connects to all declared hosts and applies baseline roles:

• User setup → ensures the admin user exists with your SSH key and passwordless sudo
• Firewall → configures ufw with deny incoming, SSH, declared extras (Nydus), and a tunnel-only k3s API (ADR-005). Use make converge-firewall HOST=Railiance01 to apply only those tasks.
• Hardening → basic SSH daemon hardening, disable root login, disable password auth
• Tooling → installs essential packages (htop, vim, git, curl, fail2ban, etc.)
• SOPS agent → ensures decryption tooling (age, sops) is available on the host

Running Convergence

make converge

This will:

1. Validate and resolve each host's baseline profile from source
2. Run the Ansible playbooks against all hosts in inventory/servers.yaml
3. Apply the baseline security and tooling configuration

Verifying

After convergence, run the automated test suite to assert the node matches the baseline spec:

make verify

This runs Goss assertions against all hosts and exits non-zero on failure. TAP reports are written to reports/. See docs/verification.md for details.

For a quick human-readable summary without assertions:

make status

Notes

• Convergence is idempotent: re-running it will not break your server.
• Convergence does not load provider credentials. The sops_agent role installs SOPS/age clients but does not place an age private key on a host.
• Additional roles (e.g. WireGuard, Kubernetes, apps) can be layered later.