The lab, in one picture
Everything below runs on hardware in my house, and every box is a thing that is actually running rather than a thing I plan to run. Click any region for what it is and why it is there. Layers read top to bottom: how traffic gets in, what it lands on, and what holds the truth underneath.
Addresses, segment numbers, and machine names are deliberately not on this picture. The internal copy of this diagram has them; that copy stays private, and the gate between the two repos is fail-closed rather than a habit. What is on this page is the shape, which is the part that is actually interesting.
The regions
Edge
Nothing is port-forwarded and nothing listens on the internet. A connector makes an outbound connection to the edge network, and traffic comes back down that tunnel to an ingress controller which routes it to a service inside the cluster. Every application hostname sits behind single sign-on at the edge, so an unauthenticated request is turned away before it reaches the app rather than by the app. The public landing page you are reading is the deliberate exception: it is the one thing with no login in front of it.
Certificates
Two certificate stories, on purpose. Public hostnames get a wildcard certificate issued automatically against a DNS challenge and renewed without anyone remembering to. Internal services that no public authority should ever vouch for get theirs from an internal certificate authority instead. The interesting part of running a CA is not issuing, it is that the templates are the privilege boundary: an over-permissive template that lets a low-privileged account choose its own subject is a well-known escalation path, so scoping them tightly is the actual work.
Network
Four segments, split by role rather than by convenience: platform infrastructure, the Kubernetes cluster, identity, and client machines. A firewall routes between them, so "which segment is this in" is a real answer with real consequences rather than a diagram label. Segmentation is also why provisioning has a pre-flight that refuses to build into a segment whose network path has not been proven: a machine on an unreachable segment looks fine right up until you need it.
Topology
This is the wiring under every region above: egress, the switch, and the five nodes. Traffic gets in through a tunnel that dials out from inside the lab, so the firewall has no open inbound ports. Below the firewall it is one switch, five small machines, and two NAS boxes. Cyan boxes link to the page that covers them.
Compute
Five nodes in a high-availability cluster, so a guest is not welded to the machine it happens to be running on. Two build paths sit on top: Windows clones a template that a weekly pipeline rebuilds from scratch (patching a golden image is a fiction, rebuilding it is not), and Linux boots a shared cloud image with no golden-template dependency at all. Every machine is built by a pipeline, never by hand.
Kubernetes
A K3s cluster: one control node, two workers. It is where the platform's own software runs, which is the part people usually leave out of a homelab picture. CI, GitOps reconciliation, image builds, dependency updates, the AI gateway, and the metrics stack are all workloads here, not pets on a VM somewhere.
CI/CD and GitOps
Git is the definition of the estate, and a change reaches it as a branch and a pull request with lint and security gates as required checks. CI runs on the cluster, with a separate dev instance so that changing the pipeline platform does not mean testing in production. Images are built in-cluster rather than on somebody's laptop, dependency bumps arrive as PRs, and a reconciler continuously drags the cluster back to what git says it should be. Drift has nowhere to live.
Secrets
One system owns every secret and nothing is written to disk: pipelines fetch what they need at run time and hold it in memory, and workloads authenticate by role rather than by carrying a password around. Two independent scanners backstop the rule, one at commit time and one at write time, so a secret has to beat both to reach the repository. This tier is also the one whose recovery I proved by destroying it outright and restoring it.
Addressing
One system is the source of truth for addresses, and provisioning asks it rather than a spreadsheet or a memory. That is what makes an automated build safe to run twice: the address is allocated, recorded, and released again by the same pipeline that created it, and released only once the machine it belonged to is genuinely gone.
Monitoring
Three tools with distinct jobs: agent-based monitoring for the traditional fleet, a metrics stack for the cluster and the hypervisors, and one visualization pane over both. Dashboards are code, so the repository is the source of truth and a dashboard edited in the UI has nowhere to hide. The overview screen is generated from the dashboards themselves and refuses to build if one is missing its domain tag. A tile with no signal renders grey, never green, because a green light meaning "I have no idea" is worse than no light.
AI
A local model does the high-volume, zero-cost, privacy-sensitive work and never leaves the network; a paid API is reserved for the harder reasoning where it earns its cost. A gateway fronts them so calls are routed, keyed, and metered in one place. Spend is governed by layered budgets where any layer can say no, and the innermost one fails closed: a budget that is missing or unreadable denies rather than allows.
Identity
An on-prem directory with two controllers is authoritative, and it synchronizes up to the cloud directory, never down. That direction is the whole design: edit an attribute in the cloud and the next sync quietly overwrites it from on-prem, with no error, so the rule is to change it where the authority is. Joiners and leavers are pipelines driven by declarative role definitions, and offboarding disables rather than deletes.
Backup
Nightly backups to a dedicated backup server, with bulk storage on a NAS. The part that matters is not the schedule, it is that the restore has actually been performed: the secrets VM was destroyed on purpose and restored from that night's snapshot, and a canary written minutes before the destroy survived. A backup you have never restored is a hypothesis.
Alerting
Every alert leaves by one path: a self-hosted mail platform, into role-based groups. That is a deliberate constraint rather than a limitation. Push services were tried and removed, because one auditable notification path that everything shares beats several that each work slightly differently and fail in their own way.