k3sup — Bootstrap K3s Clusters Over SSH in Under a Minute

What it is

k3sup (pronounced 'ketchup') is a lightweight CLI that installs K3s on any remote server over SSH with a single command. It targets developers and homelab operators who want fast Kubernetes cluster creation on bare metal, VMs, or Raspberry Pis without writing complex setup scripts or Ansible playbooks.

K3s is a lightweight Kubernetes distribution by Rancher. k3sup removes the remaining friction by handling the SSH connection, binary download, and kubeconfig retrieval in one step.

How it saves time or tokens

Manually setting up K3s involves SSHing into a server, downloading the binary, configuring systemd, and fetching the kubeconfig. k3sup collapses this into a single command. For multi-node clusters, it also handles joining worker nodes to an existing server without manual token passing.

How to use

1. Install k3sup on your local machine (a single binary download).
2. Run k3sup install with the target server's IP and SSH key.
3. For worker nodes, run k3sup join pointing at the server IP.

Example

# Install k3sup locally
curl -sLS https://get.k3sup.dev | sh
sudo install k3sup /usr/local/bin/

# Bootstrap a K3s server
k3sup install --ip 192.168.1.100 --user pi

# Join a worker node
k3sup join --ip 192.168.1.101 --server-ip 192.168.1.100 --user pi

# Verify the cluster
export KUBECONFIG=$(pwd)/kubeconfig
kubectl get nodes

Related on TokRepo

• AI tools for DevOps — Explore other DevOps and infrastructure automation tools.
• AI tools for self-hosted — Tools for running self-hosted infrastructure and services.

Common pitfalls

• Forgetting to open port 6443 on the server firewall. K3s API server listens on this port and worker nodes need it to join.
• Using password-based SSH instead of key-based. k3sup works best with SSH keys; password auth requires additional configuration.
• Not checking the kubeconfig file location after install. k3sup writes it to the current directory by default, not to ~/.kube/config.