Kubernetes Homelab: How to Build a Small Cluster

A Kubernetes homelab is a small cluster of computers used to learn container orchestration and run services on infrastructure you control. It can be a single low-power server or several machines, but the goal is not to recreate a cloud data center: it is to understand how Kubernetes schedules workloads, handles networking and storage, and recovers from ordinary failures. This guide compares practical distributions, explains the design choices that matter at home, and walks through a small K3s deployment.

What Is a Kubernetes Homelab?

A Kubernetes homelab runs Kubernetes on personal hardware, such as a mini PC, several repurposed desktops, or virtual machines hosted by a hypervisor. Kubernetes is the control system: you describe the desired state of applications, and the cluster’s control plane and worker nodes coordinate to keep that state running. The Kubernetes project maintains the platform, while its cluster architecture documentation explains how the control plane, nodes, and workloads fit together.

The lab may run services such as a dashboard, a test database, a media helper, or a home automation component. It is also a safe place to practice deployments, updates, monitoring, and recovery before using the same ideas at work. Kubernetes itself does not supply every service an application needs: persistent storage, external access, certificates, backups, and monitoring each require configuration or additional components.

Why Run Kubernetes at Home?

Running a few containers directly with Docker Compose is often simpler. Kubernetes becomes useful when the learning goal or workload depends on its APIs: scheduling across machines, declarative rollouts, service discovery, health checks, resource limits, or GitOps workflows. A lab makes these features tangible without requiring a cloud account or exposing an experiment to production users.

The trade-off is operational overhead. A cluster needs an operating system, reliable network addresses, updates, backups, and troubleshooting. A failed router or disk can affect every service in a small lab. The best first cluster is therefore one whose failure is inconvenient rather than harmful: keep irreplaceable data backed up elsewhere, and do not move essential household services until you can restore them.

How a Home Cluster Works

The API server accepts requests from tools such as kubectl. Controllers compare the requested configuration with the cluster’s current state, and the scheduler assigns eligible Pods to nodes. A node agent and container runtime then run those Pods. Services provide stable names and virtual addresses inside the cluster; an ingress controller or another gateway can route selected requests from outside it.

For a home deployment, the path usually includes the household router, a host’s network interface, the cluster’s network plugin, and a service or ingress controller. These are separate layers: a working Pod-to-Pod route does not automatically make an application reachable from another LAN device. Plan fixed addresses for nodes, decide which machine is allowed to reach the Kubernetes API, and avoid overlapping the cluster’s Pod and Service address ranges with the LAN or a VPN. RFC 1918 defines the private IPv4 ranges commonly used for these internal networks.

These are not different application APIs: each provides Kubernetes. The choice is about installation, packaging, and how much cluster assembly to do yourself. The K3s quick-start guide documents its server-and-agent workflow, MicroK8s documentation covers its installation and cluster setup, and the upstream kubeadm guide describes bootstrapping a cluster with kubeadm.

Components and Cluster Shapes

A single-node cluster puts the control plane and application Pods on one computer. It is the easiest shape to back up and rebuild, and it is sufficient for learning Kubernetes objects. It cannot demonstrate scheduling to another machine or tolerate that computer’s failure.

A common next step is one control-plane server and one or more agent nodes. This tests multi-node scheduling but still has a single control-plane failure point. Adding worker nodes does not make the API server or cluster state highly available.

High availability requires more deliberate design. For example, a K3s cluster with embedded etcd uses an odd number of server nodes to maintain quorum, along with a stable endpoint for API access. More machines consume electricity and introduce another network, storage, and upgrade surface. Build this shape only when control-plane failover is part of the learning goal; a single server is a better first milestone.

Storage and external traffic deserve separate decisions. A local-path volume can store data on one node, but that does not make it available if the node or disk fails. Shared storage or a CSI driver can provide different behavior, with its own availability and backup requirements. Similarly, an ingress controller or load balancer can publish a service to the LAN, but it does not automatically provide authentication, a firewall, or a public TLS endpoint.

Real-World Uses

A home Kubernetes cluster can host throwaway test deployments, run a private container registry or monitoring stack, provide a repeatable environment for learning GitOps, or run non-critical self-hosted services. It can also teach operational boundaries: how a failed node affects a workload, why a persistent volume is not a backup, and what changes when traffic crosses a VLAN or reverse proxy.

Use the lab to test recovery procedures, not just installation. A deployment that runs once proves little about whether you can update it, restore its data, rotate credentials, and explain how clients reach it. For essential services, compare the cluster’s maintenance burden with a simpler host and keep an independent recovery path.

Getting Started: Build a Small K3s Cluster

Start with one Linux machine and add agents only after the single-node setup is understood. A small x86 mini PC is convenient, but the workload, memory, storage, and network reliability matter more than a particular device. The mini PC build guide covers hardware planning for development and home-lab workloads.

If the Linux nodes will be virtual machines on Proxmox rather than physical hosts, see the K3s on Proxmox deployment guide for VM sizing, bridge networking, and recovery trade-offs.

1. Prepare the network and host

Install a supported Linux distribution, update it, and give the machine a stable address with a DHCP reservation or static configuration. NixOS is an option when you want to declare and rebuild the host configuration; see NixOS for a homelab before choosing it for a cluster node. Record the address. Make sure host firewalls allow the control-plane and node traffic required by the selected CNI and deployment; do not expose the Kubernetes API to the public internet. If using VLANs, place the server in an appropriate zone and permit only the flows that are needed. See home lab network segmentation with VLANs for a practical trust-zone design.

2. Install the server

K3s provides an installer at get.k3s.io. Download and inspect the script before running it with administrator privileges:

curl -sfL https://get.k3s.io -o install-k3s.sh
less install-k3s.sh
sudo sh install-k3s.sh

On a single machine, the installer creates a K3s server and the node can also run workloads. Check that the service is active and that Kubernetes can see the node:

sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -A

The server’s node token is used to authenticate agents. Treat it like a credential: do not paste it into chat, commit it to a repository, or expose it in an unprotected script. Read it on the server only when you are ready to join another host:

sudo cat /var/lib/rancher/k3s/server/node-token

3. Join an agent

On a second Linux machine, use the server’s stable address and the token obtained above. Replace the example address and placeholder; keep the token private:

curl -sfL https://get.k3s.io | sudo env \
  K3S_URL=https://192.168.1.20:6443 \
  K3S_TOKEN='<server-node-token>' \
  sh -

When the agent is ready, run the node check again on the server. If it does not join, check name resolution and reachability to the server on port 6443, confirm the token, then check the K3s service logs on both machines. Network-plugin traffic may require additional firewall rules; use the requirements for the CNI actually configured rather than opening all ports between every VLAN.

4. Deploy and verify a test workload

Create a small deployment, confirm that it becomes ready, then remove it. These commands run through the server’s bundled kubectl:

sudo k3s kubectl create deployment web --image=nginx:stable
sudo k3s kubectl get deployments,pods
sudo k3s kubectl delete deployment web

This verifies scheduling and basic container startup, not persistent storage or access from the LAN. Add those capabilities separately, test them with non-critical data, and document the exact backup and restore steps before relying on them.

Common Misconceptions

A cluster with multiple workers is highly available. Worker nodes can keep eligible workloads running when one worker fails, but a single control-plane server remains a single point of failure. Workload replicas also need enough healthy capacity and compatible storage to be rescheduled.

Kubernetes automatically makes an application reachable. A running Pod is not necessarily reachable from a browser. Services, ingress or gateway configuration, DNS, firewall rules, and possibly a LAN load-balancer implementation determine the path. The cluster’s own network does not replace the home router’s policy.

A persistent volume is a backup. A volume describes how a workload obtains storage. It may still be a single disk, a node-local directory, or data that is deleted with the cluster. Backups need an independent destination and a tested restore procedure.

Related Articles

• Kubernetes architecture explained covers the control plane, nodes, and core objects.
• Container networking explained explains CNI, Pod networking, services, and traffic paths.
• Mini PC build guide for development environments helps plan hardware for a small cluster.
• Home lab network segmentation with VLANs covers isolating servers and management networks.

Changelog

• Initial publication.