Decisions

Architecture decision records (ADRs): one short file per decision, with the problem, the options that were considered, what was chosen and what it costs. The README’s technology table says what is used; these files say why, and what was rejected. The format is MADR, shortened.

ADRDecisionStatus
0001Kubernetes on bare-metal nodes, not VMsAccepted
0002TrueNAS as a VM on ProxmoxAccepted
0003Flux for GitOps, not Argo CDAccepted
0004ingress-nginx for traffic into the clusterSuperseded by 0006
0005Secrets in AWS SSM through External SecretsAccepted
0006Envoy Gateway (Gateway API) instead of ingress-nginxAccepted
0007restic for laptop backups, not KopiaAccepted
0008Renovate for dependency updatesAccepted
0009A GitHub App for Flux’s commit statusesAccepted
0010No bot account or auto-approval for Claude’s pull requestsAccepted
0011Alerts from Alertmanager to Telegram, and Uptime Kuma moved to ProxmoxAccepted
0012Pi-hole stays in an LXC on Proxmox, not in KubernetesAccepted
0013Uptime Kuma installed with Node.js in its LXC, not in DockerAccepted
0014Services needed to run or fix the cluster stay outside KubernetesAccepted
0015A Hugo website built from docs/, published to GitHub PagesAccepted

0001 to 0006 were written down after the fact, in November 2026.

When to write one

  • A new technology is added, or one replaces another.
  • A choice between real alternatives that would be expensive to undo.

Not for version bumps, config changes or small fixes. The ADR goes in the same pull request as the change.

How

  1. Copy template.md to NNNN-short-title.md with the next number.
  2. Keep it short. The options and their reasons matter most.
  3. Add it to the table above, and link it from the technology choices if it is there.

An accepted ADR is not rewritten. When a decision changes, write a new ADR and set the old one’s status to superseded by [NNNN](NNNN-...md).