Setting Up a Kubernetes Homelab with K3s

Nov 15, 2025
kubernetes k3s homelab devops linux

Introduction

Kubernetes can seem intimidating for homelab setups, but K3s makes it accessible and lightweight. In this guide, I’ll walk you through setting up a production-ready K3s cluster on your home servers.

What is K3s?

K3s is a lightweight Kubernetes distribution from Rancher Labs, designed to be simple, secure, and require minimal resources. It’s perfect for:

Homelabs with limited resources
Edge computing scenarios
Development and testing environments
Learning Kubernetes concepts

Prerequisites

At least 2 Linux machines (Ubuntu 20.04+ recommended)
2GB+ RAM per node
20GB+ disk space
Network connectivity between nodes
Root or sudo access

Installation

Step 1: Install K3s on Master Node

curl -sfL https://get.k3s.io | sh -

After installation, grab the token from the master:

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

Step 2: Install K3s on Worker Nodes

Replace MASTER_IP with your master node’s IP:

curl -sfL https://get.k3s.io | K3S_URL=https://MASTER_IP:6443 \
  K3S_TOKEN=<token-from-master> sh -

Step 3: Verify Cluster

sudo k3s kubectl get nodes

You should see all nodes in a Ready state.

Storage Configuration

For persistent storage, install Longhorn (a distributed block storage system):

kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/master/deploy/longhorn.yaml

Networking

Configure a MetalLB load balancer for your homelab:

kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/main/config/manifests/metallb-native.yaml

Create a ConfigMap with your network range:

apiVersion: v1
kind: ConfigMap
metadata:
  namespace: metallb-system
  name: config
data:
  config: |
    address-pools:
    - name: default
      protocol: layer2
      addresses:
      - 192.168.1.100-192.168.1.110  # Adjust to your network

Monitoring Your Cluster

Install kube-prometheus-stack for monitoring:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install prometheus prometheus-community/kube-prometheus-stack -n monitoring --create-namespace

Best Practices

Resource Requests: Always define CPU and memory requests
Labels and Namespaces: Organize workloads with proper labels
Network Policies: Implement network segmentation
Regular Backups: Back up your etcd database regularly
Updates: Keep K3s updated for security patches

Troubleshooting

Nodes Not Joining

Check the worker node logs:

sudo journalctl -u k3s-agent -f

Container Issues

Inspect pod logs:

kubectl logs <pod-name> -n <namespace>
kubectl describe pod <pod-name> -n <namespace>

Conclusion

You now have a functional Kubernetes cluster in your homelab! Start by deploying simple applications and gradually increase complexity. This setup is great for learning and experimenting with cloud-native technologies.