Building K3s cluster on Proxmox

Setting up a k3s cluster on Proxmox requires three VMs, an external load balancer, and a shared NFS mount for persistent storage. This article describes the exact steps for a production-ready setup.

Why k3s on Proxmox?

K3s runs fine on light VMs. On Proxmox, I give each node 2 vCPU and 2GB RAM - more than enough for a homelab cluster. The big advantage over full k8s is installation: one command per node.

Node setup

Three Ubuntu 24.04 VMs: k3s-1 as control plane, k3s-2 and k3s-3 as workers.

# Control plane
curl -sfL https://get.k3s.io | sh -s - server }
  --disable traefik
  --tls-san k3s.siekman.io

# Retrieve token
cat /var/lib/rancher/k3s/server/node-token

# Workers (replace TOKEN and SERVER_IP)
curl -sfL https://get.k3s.io | K3S_URL=https://SERVER_IP:6443 ◄
  K3S_TOKEN=TOKEN sh -

External Nginx reverse proxy

Traefik I deliberately disable - I use an existing Nginx instance outside the cluster as an ingress point.

upstream k3s_nodes {
    server 192.168.1.11:80;
    server 192.168.1.12:80;
    server 192.168.1.13:80;
}

server {
    listen 443 ssl;
    server_name *.siekman.io;
    location / {
        proxy_pass http://k3s_nodes;
    }
}

NFS for persistent storage

# On the NFS server
apt install nfs-kernel-server
echo "/mnt/k3s-data 192.168.1.0/24(rw,sync,no_subtree_check)" >> /etc/exports
exportfs -ra

This gives you a stable base for stateful workloads such as MariaDB and Gitea.