Architecture
Architecture Decision Records
The major platform choices, the alternatives actually considered, and the tradeoffs accepted rather than solved.
Each record follows the same shape: Context (what problem, what options), Decision, Reasoning, Tradeoffs, and Outcome — written after the decision had been lived with long enough to know whether it held up.
The Tradeoffs section is the one that matters. Any choice can be justified; the useful question is what it cost.
The records are ordered as the platform came together — foundational choices first — and every one links to the next at its foot, so you can read straight through.
GitOps with ArgoCD — App of Apps
One root Application bootstraps the entire cluster. Git is the only supported way to change anything — the paradigm everything else lives under.
ADR 002 · Jul 2025Self-hosted Gitea with in-cluster CI
Git, CI runners, and the container registry all live inside the cluster they deploy — the self-hosted substrate the GitOps loop runs on.
ADR 003 · Aug 2025Vault + ESO as the only secrets path
One source of truth, synced at runtime, with manual Shamir unsealing accepted as the cost of owning the root of trust.
ADR 004 · Aug 2025Authentik as the identity provider
One login for everything — including Vault, ArgoCD, and Proxmox — declared entirely in Terraform.
ADR 005 · Oct 2025Synology iSCSI as primary storage
Centralized NAS block storage over distributed storage I'd operate badly — the single point of failure named and accepted.
ADR 006 · Nov 2025Kubernetes nodes as Proxmox VMs
The virtualization pivot that made nodes disposable, backups whole, and GPU passthrough finally work.
ADR 007 · Nov 2025Talos Linux as the Kubernetes OS
An immutable, API-driven OS with no SSH and no package manager — so nodes become genuinely disposable.
ADR 008 · Nov 2025Cilium as the CNI
eBPF networking, no kube-proxy at all, and an egress-lanes model where internet access is an explicit Git change.
ADR 009 · Nov 2025Istio in ambient mode, not sidecars
Cluster-wide mTLS without per-pod proxies. Lower overhead and a one-label rollout, against a younger ecosystem.
ADR 010 · Dec 2025CloudNative PG for managed Postgres
Operator-managed Postgres with WAL archiving to MinIO, replacing one database container per application.
ADR 011 · Dec 2025Local LLM inference on a dedicated GPU worker
GPU passthrough from Proxmox through Talos into Kubernetes, so no prompt ever leaves the network.
ADR 012 · 2025–2026A layered backup strategy
Four independent recovery layers with different failure domains — what changed after losing data once.
ADR 013 · Mar 2026MCP servers as the AI-ops interface
Eleven scoped, in-cluster MCP servers give AI tooling live platform access without credentials ever leaving the cluster.
ADR 014 · Aug 2026vLLM for served generation
A throughput-first runtime — a quantized 30B tensor-parallel across both GPUs — alongside Ollama, which moved to embeddings. Documented mid-migration.