Skip to content
litek8sdocs

Multi-node and HA

A server runs the whole control plane and its own pods; any Linux machine (a Raspberry Pi, an old laptop, a cheap cloud VM) joins it as a node with the token the server prints:

Joining machines Your laptop runs kubectl against the server on port 6443. The server, a systemd unit called litek8s-server, runs the API server, the controllers and its own pods. Nodes running litek8s-agent, such as a Raspberry Pi, an old laptop or a cheap cloud VM, join it with the join token over HTTPS. Pods talk across nodes over a WireGuard mesh, 10.42.0.0/16 with one /24 per node. your laptop · kubectl :6443 server litek8s-server (systemd) API server, controllers, its own pods join token · HTTPS nodes · litek8s-agent Raspberry Pi old laptop cheap cloud VM WireGuard mesh · 10.42.0.0/16, one /24 per node

On Linux servers (systemd, root), one command per machine, like k3s’s installer:

Terminal window
# the server (pods run here too); prints the join command and the kubeconfig path
curl -fsSL https://raw.githubusercontent.com/jairoFernandez/litek8s/main/install.sh | sh -s -- server


# every other machine: the command the server printed
curl -fsSL https://raw.githubusercontent.com/jairoFernandez/litek8s/main/install.sh | sh -s -- \
  agent --join https://192.168.1.10:6443 --token K10<hash>::<secret>

This installs /usr/local/bin/litek8s (and crun/iptables from the package manager when missing), checks the machine (cgroup v2, kernel WireGuard, free ports) and runs litek8s install server|agent: a systemd unit (litek8s-server / litek8s-agent, Restart=always) with the token in /etc/litek8s/*.env, kubeconfig in /etc/litek8s/kubeconfig.yaml. Pods keep running across systemctl restart and upgrades, and come back after a reboot. Extra flags go to litek8s apiserver / litek8s agent (e.g. --node-ip); re-running replaces them. sudo litek8s uninstall [--purge] removes it all. Without systemd, run the same processes yourself:

Terminal window
litek8s apiserver --listen 0.0.0.0:6443 --data-dir /var/lib/litek8s/apiserver --node-ip 192.168.1.10
litek8s agent --join https://192.168.1.10:6443 --token K10<hash>::<secret> --node-ip 192.168.1.21

Every node gets a /24 of 10.42.0.0/16; Services and DNS work cluster-wide. A node that stops goes NotReady after 40 s and its pods are rescheduled after their tolerationSeconds; laptops that sleep can join with a longer --node-grace-period. Three servers make the control plane highly available: install.sh | sh -s -- server --cluster-init on the first, ... server --server https://<first>:6443 --token <token> on two more (docs/ha.md). Any one server can die without losing writes; litek8s lb gives kubectl one address in front of all three:

HA control plane kubectl on your laptop talks to litek8s lb on 127.0.0.1:6443, which forwards to a control plane of three servers that replicate the object store with Raft on port 6444. Nodes connect to any server and fail over to another. your laptop · kubectl litek8s lb 127.0.0.1:6443 control plane server 1 API + store server 2 Raft leader server 3 API + store Raft :6444 Raft :6444 any server, fail over nodes agent agent agent
Terminal window
litek8s logs -l app=web --since 1h --grep ERROR
litek8s query 'topk(5, sum by (pod) (rate(container_cpu_usage_seconds_total[5m])))'
litek8s alerts