K3s uninstall is surprisingly complicated because the installer tries to be helpful by keeping things around, which can lead to lingering files and services that prevent a clean slate.
Here’s how to make sure K3s is really gone from a node:
1. Stop and Disable the K3s Service
The most common oversight is forgetting to stop the K3s agent or server process. It might still be running in the background.
Diagnosis:
sudo systemctl status k3s
sudo systemctl status k3s-agent
Fix:
sudo systemctl stop k3s
sudo systemctl disable k3s
# OR if it's an agent node:
sudo systemctl stop k3s-agent
sudo systemctl disable k3s-agent
This ensures the K3s process is terminated and won’t restart on boot.
2. Remove K3s Binaries and Data
Even after stopping the service, the K3s executables and configuration data remain.
Diagnosis:
Check for the existence of /usr/local/bin/k3s, /usr/local/bin/kubectl, and the data directory.
Fix:
sudo rm -rf /usr/local/bin/k3s
sudo rm -rf /usr/local/bin/kubectl
sudo rm -rf /var/lib/rancher/k3s/
sudo rm -rf /etc/rancher/k3s/
These commands purge the main K3s binary, the symlinked kubectl, and the persistent data and configuration directories, removing all traces of K3s’s runtime state and configuration.
3. Clean Up Network Interfaces and IPVS Rules
K3s often sets up specific network configurations, particularly if you’re using Flannel or IPVS. These can persist.
Diagnosis: Check for K3s-related network interfaces or IPVS rules.
Fix: If you installed K3s with IPVS mode:
sudo sysctl -w net.bridge.bridge-nf-call-iptables=0
sudo sysctl -w net.bridge.bridge-nf-call-ip6tables=0
sudo rm -f /etc/sysctl.d/99-k3s.conf # Or similar file created by k3s
This resets iptables bridge forwarding and removes any persistent sysctl configurations K3s might have applied.
4. Remove K3s-Managed Certificates and Keys
K3s manages its own TLS certificates for secure communication. These should be removed.
Diagnosis:
Look for files in /var/lib/rancher/k3s/server/tls/ or /var/lib/rancher/k3s/agent/tls/.
Fix:
sudo rm -rf /var/lib/rancher/k3s/server/tls/
sudo rm -rf /var/lib/rancher/k3s/agent/tls/
This cleans up any generated certificates and private keys used by K3s components, preventing potential conflicts if you reinstall K3s or other TLS-dependent services.
5. Unmount K3s Storage (if applicable)
If you configured K3s to use specific storage volumes or devices that were mounted, these might remain mounted.
Diagnosis:
Use mount to see currently mounted filesystems and look for K3s-related entries.
Fix:
sudo umount /var/lib/rancher/k3s/agent/pod-resources # Example, adjust path if needed
This unmounts any directories that K3s might have used for specific resource management or storage, freeing them up for other uses.
6. Remove the k3s User and Group (if created)
The K3s installer might create a dedicated user or group for its processes.
Diagnosis:
id k3s
getent group k3s
Fix:
sudo userdel k3s
sudo groupdel k3s
This removes the system user and group that K3s might have created, tidying up user accounts on the system.
7. Clean Up Container Runtime Data (if using containerd bundled with K3s)
K3s often bundles and manages its own containerd. Removing K3s without explicitly cleaning this can leave containers and images behind.
Diagnosis:
Check if containerd is running and its configuration.
Fix:
sudo systemctl stop containerd
sudo systemctl disable containerd
sudo rm -rf /var/lib/containerd/
# If you used a different containerd config location:
# sudo rm -rf /etc/containerd/config.toml
This stops and removes the data associated with the containerd instance that K3s might have managed, ensuring no leftover container images or runtime state exists.
8. Re-run the Installer Script with --uninstall Flag
The official K3s uninstall script is the most direct way, but it’s often forgotten or assumed to be sufficient on its own. It’s best run after the manual steps above if they fail.
Diagnosis: If previous steps didn’t fully remove K3s.
Fix:
curl -sfL https://get.k3s.io | sh -s - --uninstall
This script attempts to reverse the installation process, stopping services, removing binaries, and cleaning up configuration files. It’s a good final sweep.
After successfully performing these steps, you should have a clean system, free from any K3s remnants. The next potential issue you might encounter is unrelated services complaining about missing network configurations or ports that K3s previously occupied.