Resetting a K3s cluster from scratch is surprisingly straightforward, but the one thing most people miss is that K3s doesn’t actually delete its state files on uninstall; it just stops the services.
Let’s say you’ve got a K3s cluster that’s gone rogue. Pods aren’t starting, networking is flaky, or maybe you just want a clean slate for testing. A full reset means nuking the existing installation and starting fresh.
Here’s how you’d do it on a typical Linux node acting as a K3s server or agent.
First, stop the K3s service. On most modern systems using systemd:
sudo systemctl stop k3s
sudo systemctl disable k3s
This stops the K3s process from running and prevents it from starting on boot. The disable command is crucial to ensure it doesn’t just restart on the next reboot.
Next, you need to remove the K3s installation itself. The standard uninstaller script is your friend here. You can download it again or, if you still have it from the initial install, run it directly.
curl -sfL https://get.k3s.io | sh -
Wait, that command installs K3s! No, that’s the trick. Running get.k3s.io without any arguments actually uninstalls K3s if it’s already present. It’s a bit counter-intuitive, but the script detects an existing installation and pivots to uninstall mode.
After the uninstall script runs, you’ll see output indicating it’s cleaning up. However, K3s leaves behind critical state data that prevents a true "from scratch" start if you just reinstall. This is where the real wipe happens.
The primary location for K3s state is /var/lib/rancher/k3s/. You need to remove this directory to ensure no residual configuration or data interferes with a fresh installation.
sudo rm -rf /var/lib/rancher/k3s/
This command recursively removes the entire K3s state directory. This includes etcd data (if you were using the embedded etcd), Kubernetes manifests, certificates, and network configuration. Without this step, a reinstallation might pick up old configurations, leading to unexpected behavior or the same problems you were trying to fix.
You should also consider removing the K3s binaries and configuration files. These are typically located in /usr/local/bin/k3s, /usr/local/etc/k3s.yaml, and potentially /etc/rancher/k3s/.
sudo rm -f /usr/local/bin/k3s
sudo rm -f /usr/local/bin/kubectl
sudo rm -f /usr/local/bin/k3s-killall.sh
sudo rm -f /usr/local/bin/k3s-uninstall.sh
sudo rm -rf /etc/rancher/k3s/
sudo rm -f /etc/rancher/k3s/config.yaml
Clean up any symlinks or other remnants if you find them, though the above covers the most common locations.
Now that the old installation and its state are gone, you can reinstall K3s as if it were a brand new machine.
For a server node:
curl -sfL https://get.k3s.io | sh -
For an agent node, you’ll need the server’s IP address and token.
curl -sfL https://get.k3s.io | K3S_URL="https://<server_ip>:6443" K3S_TOKEN="<node_token>" sh -
Replace <server_ip> with the actual IP of your K3s server and <node_token> with the token obtained from the server (usually found in /var/lib/rancher/k3s/server/node-token on the server node after its initial setup).
After installation, you can verify the status:
sudo systemctl status k3s
And check if nodes are ready:
kubectl get nodes
You should see your newly reset node(s) joining the cluster with a clean slate.
The next thing you’ll likely encounter after a successful reset is figuring out how to manage kubectl contexts for your new cluster, especially if you’re connecting from a separate management machine.