docs(adr): restructure ADRs 001,002,004,005,012,014,015 to ADR-023 conformance
Add dated Status sections and (where missing) Consequences sections assembled from each ADR's already-stated implications. No decision substance changed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
9b1502cf7d
commit
188882449d
7 changed files with 129 additions and 2 deletions
|
|
@ -1,5 +1,9 @@
|
||||||
# ADR-001 — Architecture overview
|
# ADR-001 — Architecture overview
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
Accepted (2026-05-30)
|
||||||
|
|
||||||
## Context
|
## Context
|
||||||
|
|
||||||
This document describes the overall architecture of the homelab infrastructure
|
This document describes the overall architecture of the homelab infrastructure
|
||||||
|
|
@ -65,3 +69,21 @@ This architecture prioritises:
|
||||||
- **Simplicity**: few moving parts, no orchestration layer (no Kubernetes, no Swarm)
|
- **Simplicity**: few moving parts, no orchestration layer (no Kubernetes, no Swarm)
|
||||||
- **Reproducibility**: any host can be rebuilt from scratch via Ansible
|
- **Reproducibility**: any host can be rebuilt from scratch via Ansible
|
||||||
- **Legibility**: a human reading the repo can understand what runs where
|
- **Legibility**: a human reading the repo can understand what runs where
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
Drawn from the boundaries this ADR already states:
|
||||||
|
|
||||||
|
- The small fleet (2–5 VMs) is treated as individuals, not cattle (per Infrastructure),
|
||||||
|
and forgoing an orchestration layer is the cost of the simplicity priority (per
|
||||||
|
Decision).
|
||||||
|
- The control node `ubongo` cannot be created by the Terraform it hosts, so it is
|
||||||
|
provisioned manually — the one documented exception to Terraform-owned VM existence
|
||||||
|
(per Infrastructure / Host groups; ADR-009, ADR-015).
|
||||||
|
- Management scope is deliberately bounded: Proxmox configuration itself (storage,
|
||||||
|
clustering, networking) is out of scope, and the `control` group never runs the
|
||||||
|
`docker_host` role (per Host groups).
|
||||||
|
- Compose files are always regenerated by Ansible on deploy; no hand-edited Compose
|
||||||
|
files exist on hosts (per Service interaction model).
|
||||||
|
- The "What this repo manages" table describes the *intended* design — STATUS.md
|
||||||
|
records what is actually built (per that section).
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,9 @@
|
||||||
# ADR-002 — Security baseline and strategy
|
# ADR-002 — Security baseline and strategy
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
Accepted (2026-05-30)
|
||||||
|
|
||||||
## Context
|
## Context
|
||||||
|
|
||||||
Security here is not a single control but the sum of several combined efforts —
|
Security here is not a single control but the sum of several combined efforts —
|
||||||
|
|
@ -183,3 +187,27 @@ This posture was chosen to be:
|
||||||
Out-of-scope items and conscious trade-offs are recorded in
|
Out-of-scope items and conscious trade-offs are recorded in
|
||||||
`docs/security/accepted-risks.md` rather than here, so this decision record stays
|
`docs/security/accepted-risks.md` rather than here, so this decision record stays
|
||||||
stable while the risk posture evolves.
|
stable while the risk posture evolves.
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
Drawn from the trade-offs, scoping, and follow-on work this ADR already states:
|
||||||
|
|
||||||
|
- Targeted/physical adversaries are out of scope at this scale, and supply chain is
|
||||||
|
consciously deprioritized — active vuln scanning is deferred as an accepted risk
|
||||||
|
(per Threat model; `docs/security/accepted-risks.md`).
|
||||||
|
- SELinux is not used (non-native to Debian, redundant with AppArmor), recorded as an
|
||||||
|
accepted risk (per Mandatory access control).
|
||||||
|
- Some CIS L2 items require separate partitions with restrictive mount options, which
|
||||||
|
reaches into VM disk layout — a provisioning concern (Terraform / cloud-init, ADR-006),
|
||||||
|
not just the `base` role (per Hardening standard). Any impractical CIS item is exempted
|
||||||
|
into the accepted-risk register with rationale, recording named exceptions rather than a
|
||||||
|
blanket opt-out.
|
||||||
|
- Several controls and governance mechanisms are stated as planned, not yet built:
|
||||||
|
Suricata network IDS, active alerting wiring AIDE/`auditd`/`fail2ban`/Suricata plus
|
||||||
|
log-source-silence into Grafana, the `/security-review` skill and its aggregation of
|
||||||
|
every `roles/*/SECURITY.md`, and the periodic security review (per File integrity /
|
||||||
|
Governance; STATUS.md / `docs/TODO.md`).
|
||||||
|
- The per-service security bar is enforced manually in review today, pending the planned
|
||||||
|
`/security-review` automation (per Governance).
|
||||||
|
- The accepted-risk register is kept out of this ADR so the record stays stable while the
|
||||||
|
risk posture evolves (per Decision; `docs/security/accepted-risks.md`).
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,9 @@
|
||||||
# ADR-004 — Docker and Compose service model
|
# ADR-004 — Docker and Compose service model
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
Accepted (2026-05-30)
|
||||||
|
|
||||||
## Context
|
## Context
|
||||||
|
|
||||||
All services run as Docker containers managed via Docker Compose. This document
|
All services run as Docker containers managed via Docker Compose. This document
|
||||||
|
|
@ -107,3 +111,22 @@ Docker Compose was chosen over Kubernetes/Swarm because:
|
||||||
- Compose files are human-readable and easily auditable
|
- Compose files are human-readable and easily auditable
|
||||||
- No distributed state to manage
|
- No distributed state to manage
|
||||||
- Straightforward to back up and restore
|
- Straightforward to back up and restore
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
Drawn from the trade-offs and deferred items this ADR already states:
|
||||||
|
|
||||||
|
- A shared `compose_service` engine role is intentionally not built: the ~5 standard
|
||||||
|
tasks are duplicated per role in favour of legible, self-contained roles, with a stated
|
||||||
|
revisit trigger — extract a shared engine if maintaining the duplicated mechanics
|
||||||
|
becomes painful (a pattern change touching many roles, or drift this standard alone
|
||||||
|
isn't preventing) (per "Why not a shared engine").
|
||||||
|
- Forgoing Kubernetes/Swarm is the deliberate cost of matching complexity to a 2–5 host
|
||||||
|
fleet with no distributed state to manage (per Decision).
|
||||||
|
- User-namespace remapping is not enabled by default — evaluated per use case (per Docker
|
||||||
|
daemon configuration).
|
||||||
|
- Bare `latest` is acceptable only on the stateless tier; the stateful tier is always
|
||||||
|
pinned `tag@digest`, and image updates are a deliberate operation (per Image management;
|
||||||
|
ADR-011).
|
||||||
|
- Backup strategy is stated as defined separately, not in scope of this ADR (per Persistent
|
||||||
|
data).
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,9 @@
|
||||||
# ADR-005 — Host bootstrapping
|
# ADR-005 — Host bootstrapping
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
Accepted (2026-05-30)
|
||||||
|
|
||||||
## Context
|
## Context
|
||||||
|
|
||||||
This document defines the **cloud-init template** that managed VMs are cloned
|
This document defines the **cloud-init template** that managed VMs are cloned
|
||||||
|
|
@ -81,3 +85,19 @@ Cloud-init with Proxmox templates provides:
|
||||||
- No manual installer interaction
|
- No manual installer interaction
|
||||||
- A clean handoff point to Ansible
|
- A clean handoff point to Ansible
|
||||||
- Easy rebuilds — destroy VM, clone template, run Ansible
|
- Easy rebuilds — destroy VM, clone template, run Ansible
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
Drawn from the trade-offs and special cases this ADR already states:
|
||||||
|
|
||||||
|
- The cloud-init image was chosen over a manual Debian installer (slow, error-prone,
|
||||||
|
not reproducible) and over preseed/netboot (powerful but complex to maintain) (per
|
||||||
|
Approach).
|
||||||
|
- Template creation is a one-time manual procedure per Proxmox cluster, and the template
|
||||||
|
is never booted directly (per Template creation).
|
||||||
|
- There is no manual `qm clone` path for managed hosts; the full create → inventory →
|
||||||
|
configure pipeline and the Terraform↔Ansible contract live in ADR-009 (per VM
|
||||||
|
provisioning / Ansible handoff).
|
||||||
|
- The control node is the sole documented exception — `ubongo`, a physical machine
|
||||||
|
installed by hand because it cannot be created by the Terraform it hosts (chicken-and-egg);
|
||||||
|
its hardware target and recovery model live in ADR-015 (per Control node bootstrapping).
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,9 @@
|
||||||
# ADR-012 — Hardware reference & capacity evaluation
|
# ADR-012 — Hardware reference & capacity evaluation
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
Accepted (2026-06-01)
|
||||||
|
|
||||||
## Context
|
## Context
|
||||||
|
|
||||||
The repo modelled the logical/network layer (Terraform VM specs, ADR-007
|
The repo modelled the logical/network layer (Terraform VM specs, ADR-007
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,9 @@
|
||||||
# ADR-014 — Sourcing technical knowledge (docs and best practices)
|
# ADR-014 — Sourcing technical knowledge (docs and best practices)
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
Accepted (2026-06-04)
|
||||||
|
|
||||||
## Context
|
## Context
|
||||||
|
|
||||||
Most work in boma is done by AI agents drawing on training memory, which is stale
|
Most work in boma is done by AI agents drawing on training memory, which is stale
|
||||||
|
|
@ -100,5 +104,27 @@ above keeps the policy working.
|
||||||
- Commit to the principle, not a tool — degrade to `WebFetch`/`WebSearch` when plugins
|
- Commit to the principle, not a tool — degrade to `WebFetch`/`WebSearch` when plugins
|
||||||
are absent.
|
are absent.
|
||||||
|
|
||||||
See also: ADR-013 (heritage / translate-don't-transplant), ADR-011 (version pinning),
|
## Consequences
|
||||||
ADR-008 (testing/verification).
|
|
||||||
|
Drawn from the follow-on work and limitations this ADR already states:
|
||||||
|
|
||||||
|
- Verified facts carry a durable, greppable stamp; a stamp binds a fact to a pinned
|
||||||
|
version, so a `requirements` change or image upgrade marks exactly what to re-check
|
||||||
|
(per Capture / Re-verification).
|
||||||
|
- Stale-stamp detection — a `/review-repo` or `/security-review` check flagging stamps
|
||||||
|
whose recorded version no longer matches what is pinned — is a noted enhancement, not
|
||||||
|
built yet (per Re-verification).
|
||||||
|
- Any version-specific claim given from memory must be marked "from memory, unverified"
|
||||||
|
as a transparency backstop, since agent self-assessed certainty is unreliable (per
|
||||||
|
When consulting is required).
|
||||||
|
- The policy commits to the principle rather than a specific plugin, so it degrades to
|
||||||
|
`WebFetch`/`WebSearch` on a bare install; reproducing the plugin toolchain from the
|
||||||
|
repo is done via `.claude/settings.json` and `docs/runbooks/claude-code-setup.md`,
|
||||||
|
with the graceful-degradation fallback covering a fresh clone until bootstrap runs
|
||||||
|
(per Source hierarchy / Reproducibility of the toolchain).
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- ADR-013 — heritage / translate-don't-transplant.
|
||||||
|
- ADR-011 — version pinning.
|
||||||
|
- ADR-008 — testing / verification.
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,9 @@
|
||||||
# ADR-015 — Control / development / AI-worker host (`ubongo`)
|
# ADR-015 — Control / development / AI-worker host (`ubongo`)
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
Accepted (2026-06-05)
|
||||||
|
|
||||||
## Context
|
## Context
|
||||||
|
|
||||||
Earlier ADRs framed the control node — the host that runs Terraform and Ansible —
|
Earlier ADRs framed the control node — the host that runs Terraform and Ansible —
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue