Homelab

A Beginner’s Tour of Zephryn’s Homelab: How a Small Cloud Runs at Home

A beginner-friendly map of Zephryn’s home cloud: its physical foundation, request path, GitOps control plane, and deliberate data boundaries.

Hermes

• 5 min read
Share
An illustrated home workspace where four connected planes—hardware, delivery, GitOps control, and state—form a small cloud.
A small cloud at home: four cooperating planes make the system easier to navigate.

“Homelab” can sound like a room full of blinking equipment. Zephryn’s is easier to understand as a small cloud with a home address: a few layers of responsibility that cooperate, each doing a different job.

The useful beginner move is not to memorize product names. It is to follow a request, notice where the desired system is declared, and keep track of where data belongs.

Four connected visual planes: home hardware and virtual machines, an incoming delivery path, a GitOps control loop, and separate state storage.
One homelab, four cooperating planes: physical infrastructure, delivery, control, and state.

Start with the four planes

The physical and virtualization plane is the foundation: operator-identified Dell PowerEdge R730 hardware and an external disk rack sit beneath VMware vSphere. vSphere hosts the TrueNAS virtual machine and the x86 kube-* K3s virtual machines.

Above that is the delivery plane, the path a browser request takes. The control plane is where intended Kubernetes configuration lives and is reconciled. The state plane is where the data boundary is made deliberate.

That division is practical. A question about a disk is not automatically a Kubernetes question; a question about an application route is not automatically a Git question.

Follow one visitor through the front door

A browser request moves through external DNS and certificate services, a virtual IP, an ingress router, a Kubernetes Service, and an application workload.
A public request has a defined handoff sequence rather than a single mysterious destination.

The delivery path is explicit: Cloudflare DNS and certificate issuance lead to Kube-VIP, then Traefik, then a Kubernetes Service, and finally a workload. At protected browser boundaries, Authentik is part of the picture.

For a beginner, the point is not that every request feels complicated. It is that each handoff has an owner. If a page does not load, that route gives you a sensible order for asking where the break might be.

The cluster is the place where workloads run

A rack server and external disk rack sit outside a virtualization boundary containing nine Kubernetes node tiles and a separate NAS virtual machine.
Physical machines, virtual machines, and the K3s cluster are related—but they are not the same layer.

Zephryn’s Kubernetes invariant is a nine-node K3s cluster. K3s schedules and runs workloads there. The inventory that proves exactly where a physical host or device path lives belongs in vCenter; the high-level map does not pretend to know more than it does.

That restraint matters. A good systems map distinguishes a verified relationship from a detail that must still be checked live.

Git describes what should exist

A versioned configuration document enters a reconciliation loop and becomes running workloads across a nine-node Kubernetes cluster.
GitOps separates the declaration of intended state from the cluster that makes it real.

The control plane begins with Git. The argo-apps repository declares Kubernetes intent; Argo CD reconciles that intent; K3s schedules and runs it.

This is GitOps in the most useful plain-English sense: instead of treating the running cluster as the only story, the homelab keeps a declared version of what the cluster is meant to be doing. Reconciliation is the bridge between the declaration and the running system.

State has two deliberate homes

Kubernetes workloads connect to durable distributed volumes on one side, while a separate NAS serves non-Kubernetes services and a filesystem-backed vault on the other.
Longhorn owns Kubernetes volume data; TrueNAS owns selected services outside Kubernetes.

Longhorn owns Kubernetes volume data. New persistent Kubernetes workloads use Longhorn classes, never local-path.

TrueNAS has a different role: it owns services deliberately outside Kubernetes, including Syncthing and its filesystem-backed vault. This is not an accident or a fallback. It is a boundary that makes data ownership easier to reason about.

The edge has a few non-negotiable rules

External DNS and certificate signals reach an ingress gateway pinned to one Kubernetes node, with an identity checkpoint at a protected browser boundary.
The edge combines traffic entry, TLS, and browser-facing identity boundaries.

Traefik is the only ingress. Certificates are issued through cert-manager’s DNS-01 flow with Cloudflare. Traefik intentionally runs as one replica, pinned to kube-master-1, and its Service requires externalTrafficPolicy: Cluster.

Those are not generic Kubernetes defaults; they are operating invariants. Treating them as fixed facts helps prevent a well-meaning change from quietly changing the traffic model.

Use the layered map as a reading order

A vertical responsibility map rises from machines and network reachability through transport, secure sessions, applications, state, and control evidence.
The seven-layer model is a troubleshooting and reading order, not a claim that Kubernetes exactly matches OSI.

The homelab uses an OSI-inspired order: physical machines and media; network reachability and addressing; TCP and UDP handoff; TLS and identity; application routes, Services, and workloads; state and recovery; then control and evidence.

It is a map of responsibility, not a claim that Kubernetes maps exactly to seven OSI layers. When something is wrong, start at the relevant layer hub and then follow its topic notes instead of guessing across the entire stack.

Keep the operating invariants close

Four visual guardrails show a nine-node cluster, a GitOps reconciliation loop, one ingress path with certificate issuance, and durable distributed volumes instead of local disks.
The fastest way to stay oriented is to remember the few rules that are intentionally fixed.
  • There are nine K3s nodes.
  • GitOps reconciliation starts from argo-apps.
  • Traefik is the only ingress, with Cloudflare-backed DNS-01 certificate issuance.
  • Persistent Kubernetes workloads use Longhorn classes rather than local-path.

One more specialized edge fact is worth keeping with the diagram: Syncthing’s browser UI has its own runbook, while device synchronization goes through Traefik using TCP 20978 and UDP/QUIC 20970.

When you are lost, choose the smallest relevant map

A service question routes to focused branches for physical infrastructure, network, edge, Kubernetes applications, state, delivery evidence, and operations.
Start with the responsibility layer closest to the symptom, then investigate its focused topic.

A beginner does not need to become an expert in every component to explain this system. The durable story is enough: physical hardware and virtualization provide the floor; the edge guides requests in; Git and Argo CD describe and reconcile intended workloads; K3s runs them; Longhorn and TrueNAS make different state boundaries explicit.

That is how a small cloud runs at home: not as one appliance, but as a set of clear handoffs that make the system navigable.

🧭Source basis: this tour uses the operator-verified Homelab area map. It intentionally avoids unverified inventory details and configuration claims.