K3s on a Single VPS: Building and Operating a Lightweight Kubernetes Cluster

K3s is the pragmatic way to run Kubernetes on one VPS: a single 60–70 MB static binary that bundles the API server, controller manager, kubelet, containerd and the metrics stack, with SQLite as the default datastore instead of etcd. That matters on a 2–4 GB instance, where a kubeadm control plane with etcd typically idles at 900 MB–1.3 GB before you schedule anything. The trade-off is that every knob you would normally set on a three-node cluster — kubelet flags, datastore sizing, kube-proxy mode, Traefik and ServiceLB defaults — now lives in one config file that you need to get right the first time, because a failed upgrade on a single control plane is a full outage.

This walkthrough assumes Ubuntu 22.04 or 24.04 on a KVM instance with at least 2 vCPU and 4 GB RAM, and it ends with a pod that survives a reboot and a documented upgrade path. If you are still sizing the instance or deciding whether to split the control plane from workloads, the cloud VPS plans and sizing guidance are worth reading before you commit, since resizing later means re-planning the datastore.

Prerequisites: kernel modules, cgroups and swap

K3s will not start cleanly if bridged traffic hits iptables, if cgroup v2 is mounted read-only, or if swap is still enabled — the kubelet fails on swap by default. On a stock Ubuntu VPS image all three are common. Verify before installing anything.

# must print "cgroup2" (v1 also works but v2 is what you want on 22.04+)
stat -fc %T /sys/fs/cgroup

# swap must be off; kubelet refuses otherwise
swapon --show
sudo swapoff -a
sudo sed -ri '/^\s*[^#].*\sswap\s/ s/^/#/' /etc/fstab

# bridge traffic must reach iptables / nftables
sudo modprobe br_netfilter
printf 'br_netfilter\noverlay\n' | sudo tee /etc/modules-load.d/k3s.conf

cat <<'EOF' | sudo tee /etc/sysctl.d/90-k3s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF
sudo sysctl --system

One more check on virtualised hosts: lsmod | grep vxlan should show the module loaded after K3s starts. If your provider’s kernel does not ship overlay or vxlan, use the ServersideBackend or pick a different image now rather than debugging pod sandbox errors later.

Install with a config file, not with flags

The install script accepts environment variables, but flags typed on the command line are lost the moment you run the upgrade script. Put everything in /etc/rancher/k3s/config.yaml first; the installer and every future restart read it. On a single VPS, disable the components you do not need and pin the advertise address to the private IP so the API server does not bind to a public interface.

sudo mkdir -p /etc/rancher/k3s
cat <<'EOF' | sudo tee /etc/rancher/k3s/config.yaml
node-name: vps-1
write-kubeconfig-mode: "0600"
tls-san:
  - vps-1.example.com
  - 203.0.113.10
# skip Traefik if you already run nginx on port 80/443
disable:
  - traefik
# ServiceLB grabs hostPort 80/443 too in some versions
# disable:
#   - servicelb
kubelet-arg:
  - "eviction-hard=memory.available<256Mi"
  - "system-reserved=cpu=200m,memory=256Mi"
  - "kube-reserved=cpu=200m,memory=256Mi"
kube-apiserver-arg:
  - "audit-log-maxsize=50"
  - "audit-log-maxbackup=2"
EOF

curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=stable sh -s -

Verify the control plane and wire up kubectl

sudo systemctl is-active k3s
sudo k3s kubectl get nodes -o wide
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown "$USER":"$USER" ~/.kube/config
kubectl get pods -A

# what the control plane actually costs in RSS
ps -o rss= -C k3s-server | awk '{s+=$1} END {print s/1024 " MB"}'

Back up and compact the SQLite datastore

All cluster state — Deployments, Secrets, ServiceAccounts, the CA — lives in /var/lib/rancher/k3s/server/db/state.db. WAL mode means the file grows until checkpointed, and a single-node cluster has no replica to recover from. Two habits: snapshot before every upgrade, and compact after heavy churn.

# online snapshot to a timestamped file
sudo k3s etcd-snapshot save --name pre-upgrade-$(date +%F)

# SQLite-level backup that is safe while the server runs
sudo sqlite3 /var/lib/rancher/k3s/server/db/state.db \
  ".backup '/var/backups/k3s-state-$(date +%F).db'"

# compact after mass deletes (WAL is not shrunk by the app)
sudo systemctl stop k3s
sudo sqlite3 /var/lib/rancher/k3s/server/db/state.db "PRAGMA wal_checkpoint(TRUNCATE); VACUUM;"
sudo systemctl start k3s

Copy those files off the VPS — a datastore backup stored on the same disk does not survive the failure it is meant to protect against. On nodes with frequent deploys, the state database commonly grows 20–60 MB per week of rollout churn; if you see it above ~500 MB, snapshot and compact before it becomes the slowest part of every API call.

Deploy a workload, then tighten its limits

A minimal Deployment proves scheduling, networking and storage at once. Use explicit requests and limits from the start — requests drive scheduling, limits drive cgroup enforcement, and leaving them empty is how a small VPS ends up with a pod that starves everything else.

kubectl create deployment web --image=nginx:1.27-alpine --replicas=2
kubectl set resources deployment/web \
  --requests=cpu=100m,memory=64Mi --limits=cpu=500m,memory=256Mi
kubectl get pods -o wide
kubectl top pods        # requires metrics-server, bundled with k3s

kubectl port-forward deploy/web 8080:80 &
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080

Survive reboots and plan the upgrade path

K3s is a plain systemd service, so a reboot test is the only proof that your config file is complete. Reboot, wait for k3s to report active, then confirm pods return without manual intervention.

sudo reboot
# after reconnect
sudo systemctl is-enabled k3s         # must be enabled
kubectl get nodes && kubectl get pods -A
sudo journalctl -u k3s -b | grep -iE "error|fail" | head -20

For upgrades, k3s channel files (/var/lib/rancher/k3s/data/ and /etc/rancher/k3s/k3s.yaml) are pinned per version, but the install script re-run with INSTALL_K3S_VERSION=v1.31.4+k3s1 performs an in-place binary swap and restarts the unit — roughly 15–40 seconds of API downtime on a single node. Snapshot, upgrade, watch pods, and only then move the channel forward. Never point a single-node cluster at the latest channel on a schedule.

When a single node is not enough

This setup is genuinely useful for internal tooling, CI runners, staging and small production APIs where one instance is acceptable. It stops being appropriate once you need real HA: a single control plane, single datastore and single disk are three single points of failure, and no amount of pod anti-affinity fixes that. When you reach the point of adding a second node, rebuild rather than convert — an embedded-etcd cluster is cleaner to bootstrap from scratch than a promoted SQLite node. Review VPS versus dedicated server trade-offs first if your reason for clustering is resource pressure rather than availability.

Leave a Reply