K3s on a Homelab: From Zero to a Working Cluster

Why k3s

If you want a real Kubernetes cluster to break things on without melting your laptop, k3s is the right tool. It’s a single binary, it strips out the in-tree cloud providers, and it runs on a Raspberry Pi or a VPS with 512MB of RAM.

This is part 1 of a short series. By the end you’ll have a working single-node cluster and a deployed pod.

Prerequisites

• A Linux box (bare metal, VM, or Pi) with root
• Open ports: 6443/tcp, 8472/udp, 10250/tcp
• About 10 minutes

Install

Run the official install script. It downloads the binary, writes a systemd unit, and starts k3s.service.

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

Check it’s alive:

sudo k3s kubectl get nodes

You should see one node, Ready.

Grab the kubeconfig

k3s writes a config to /etc/rancher/k3s/k3s.yaml. Copy it so you can use kubectl from your workstation:

sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config
sed -i 's/127.0.0.1/YOUR_SERVER_IP/' ~/.kube/config

Deploy something

A quick sanity check with nginx:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1
  selector:
    matchLabels: { app: nginx }
  template:
    metadata:
      labels: { app: nginx }
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports: [{ containerPort: 80 }]

kubectl apply -f nginx-deploy.yaml
kubectl port-forward deploy/nginx 8080:80

Open http://localhost:8080 — welcome page.

What’s next

In part 2 we’ll add a second node and talk about the embedded etcd-vs-sqlite tradeoff and how to back it up. For now: you have a cluster. Go break it.

Tip: if you reinstall, k3s keeps state in /var/lib/rancher/k3s. Nuke that directory to start clean.