Why the cluster is built the way it is. Each record states the context, the decision, the alternatives that were rejected and the consequences that follow — including the unpleasant ones, because a decision record that only lists benefits is marketing rather than engineering.
These were extracted from the architecture review’s target design and implementation brief and from the migration plan and its ownership model — both kept in the private archive and not part of the published tree. Where those documents carry the full reasoning, an ADR is the durable summary — the plans are working documents and will be superseded; these should not need to be.
Every record has: Status, Date, Context, Decision, alternatives rejected with the reason, Consequences, and Evidence (the files that prove the decision is real rather than aspirational). Status is one of Accepted, Superseded, or Accepted, partially implemented — the last is used when the decision stands but the cluster does not yet match it, and the gap is named explicitly rather than left to be discovered.
Records are append-only in spirit: a changed decision gets a new record that supersedes the old one, so the reasoning that was once good enough stays visible.
| # | Decision | Status |
|---|---|---|
| 0001 | GitOps with ArgoCD (app-of-apps), and three AppProjects as the trust boundary | Accepted |
| 0002 | SOPS + age, decrypted by ksops in ArgoCD’s repo-server | Accepted |
| 0003 | Tenant model: the cluster repo registers tenants, tenant repos own their config | Accepted (contingent on the tenant team’s agreement) |
| 0004 | One Cloudflare Origin CA certificate via a Traefik TLSStore (no cert-manager) |
Accepted |
| 0005 | Authoritative data on /srv/data via static retained PVs |
Accepted, partially implemented |
| 0006 | Backups run from the host with restic, not inside the cluster | Accepted, partially implemented (no R2 leg; the workstation mirror runs on a daily timer) |
| 0007 | Scale-to-zero with KEDA and the HTTP add-on | Accepted |
| 0008 | Keep k3s’s bundled Traefik, configured via one HelmChartConfig |
Accepted |
| 0009 | The VCAP Postgres instances stay publicly reachable, on moved non-default ports | Accepted, partially implemented |
Copy the shape of an existing record. State the decision in the title as an assertion (“Backups run from the host”, not “Backup options”), and be specific in Consequences about what got worse — the accepted trade-offs are the part that a future reader actually needs.