tegwick
b32dfd4f5a
- docs/verification.md: explains spec/server-baseline.yaml, goss/baseline.yaml, make verify workflow, assertion mapping table, and how to add new checks - docs/convergence.md: replace manual spot-check snippet with make verify reference - workplans/RAIL-HO-WP-0002: mark completed (all tasks done, workstream closed) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
50 lines
1.6 KiB
Markdown
50 lines
1.6 KiB
Markdown
# 🔧 Server Convergence
|
|
|
|
After provisioning servers with Terraform, RailianceHosts 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 sensible defaults (deny incoming, allow SSH)
|
|
- **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
|
|
|
|
```bash
|
|
make converge
|
|
```
|
|
|
|
This will:
|
|
1. Decrypt secrets locally (with your age key)
|
|
2. Run the Ansible playbooks against all hosts in your `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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
make status
|
|
```
|
|
|
|
## Notes
|
|
|
|
- Convergence is **idempotent**: re-running it will not break your server.
|
|
- Only your workstation (control node) needs the age private key; hosts never see it.
|
|
- Additional roles (e.g. WireGuard, Kubernetes, apps) can be layered later.
|