tegwick
a680fb51af
ADR-003 formalises the 5-repo structure aligned with OAS Stack S1-S5: railiance-infra, railiance-cluster, railiance-platform, railiance-enablement, railiance-apps. Defines boundary rule, pre-condition chain, and content relocation table. ADR-002 marked superseded. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
# ADR-002 — Repository Boundary: railiance-hosts vs railiance-bootstrap
|
|
|
|
**Status:** Superseded by ADR-003
|
|
**Date:** 2026-03-09
|
|
**Superseded:** 2026-03-10 — see `ADR-003-railiance-5repo-stack-architecture.md`
|
|
**Deciders:** Bernd Worsch
|
|
|
|
---
|
|
|
|
## Context
|
|
|
|
Two repositories exist in the Railiance domain that both touch server
|
|
configuration:
|
|
|
|
- **`railiance-hosts`** — manages the OS baseline, security hardening,
|
|
inventory, secrets, and test suite for every managed node.
|
|
- **`railiance-bootstrap`** — installs Kubernetes (k3s), Helm, GitOps
|
|
tooling, and platform services on top of an already-converged base node.
|
|
|
|
Prior to this ADR, `railiance-bootstrap` contained Ansible playbooks
|
|
(`harden.yml`, `bootstrap.yml`) that overlapped with OS-level tasks now
|
|
owned by `railiance-hosts`. This created a split responsibility that could
|
|
cause drift and conflicting configuration.
|
|
|
|
---
|
|
|
|
## Decision
|
|
|
|
### Ownership table
|
|
|
|
| Concern | Owner | Notes |
|
|
|---------|-------|-------|
|
|
| SSH hardening (PermitRootLogin, PasswordAuthentication) | `railiance-hosts` | Defined in `spec/server-baseline.yaml` |
|
|
| UFW firewall rules (including k3s/Flannel ports) | `railiance-hosts` | Spec section: `firewall.rules` |
|
|
| fail2ban installation and SSH jail | `railiance-hosts` | Spec section: `security.fail2ban_jails` |
|
|
| Required OS packages (ufw, fail2ban, git, curl, age, sops) | `railiance-hosts` | Spec section: `packages.installed` |
|
|
| Admin user + sudo config | `railiance-hosts` | Spec section: `users` |
|
|
| HISTCONTROL and shell security defaults | `railiance-hosts` | Spec section: `security` |
|
|
| SOPS/age key agent | `railiance-hosts` | `roles/sops_agent` |
|
|
| k3s installation | `railiance-bootstrap` | Consumes a converged base node |
|
|
| Helm + GitOps tooling | `railiance-bootstrap` | |
|
|
| Application-layer Kubernetes resources | `railiance-bootstrap` | |
|
|
|
|
### Rule
|
|
|
|
> **Any item present in `spec/server-baseline.yaml` MUST NOT be managed
|
|
> by `railiance-bootstrap`.**
|
|
|
|
`railiance-bootstrap` may add UFW rules for Kubernetes components (e.g.
|
|
NodePort ranges, cluster-internal ports) but must not remove or override
|
|
the base rules defined in this repo's spec.
|
|
|
|
### Superseded files in `railiance-bootstrap`
|
|
|
|
The following files in `railiance-bootstrap` are superseded by the roles
|
|
and spec in `railiance-hosts` and should not be used for new work:
|
|
|
|
- `ansible/harden.yml`
|
|
- `ansible/bootstrap.yml` (the OS-hardening portions)
|
|
|
|
An ecosystem todo (`[repo:railiance-bootstrap]`) should be filed to
|
|
formally retire these files or scope them down to k3s-only tasks.
|
|
|
|
---
|
|
|
|
## Consequences
|
|
|
|
- `railiance-hosts` converge step (`make converge`) must run and pass
|
|
before `railiance-bootstrap` deploys anything.
|
|
- Changes to the OS security baseline (new packages, firewall rules,
|
|
SSH settings) go into `spec/server-baseline.yaml` → update the Ansible
|
|
role → update `goss/baseline.yaml` — all in this repo.
|
|
- `make verify` provides a machine-readable assertion that the converge
|
|
step produced the expected state, suitable for CI gating.
|