Setting Up a Kubernetes Homelab with K3s

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:

Prerequisites

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

  1. Resource Requests: Always define CPU and memory requests
  2. Labels and Namespaces: Organize workloads with proper labels
  3. Network Policies: Implement network segmentation
  4. Regular Backups: Back up your etcd database regularly
  5. 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.

Resources