k3sup — Bootstrap K3s Clusters Over SSH in Under a Minute

Introduction

k3sup simplifies Kubernetes cluster bootstrapping by wrapping K3s installation into a single command that works over SSH. It removes the need for Ansible playbooks or manual shell scripts when setting up lightweight Kubernetes clusters.

What k3sup Does

• Installs a K3s server on any Linux host over SSH with one command
• Joins additional worker nodes to an existing cluster with automatic token exchange
• Fetches the kubeconfig file and merges it locally for immediate kubectl access
• Supports multi-master HA setups with embedded etcd or external datastore
• Installs Helm charts and Kubernetes apps via the built-in app catalog

Architecture Overview

k3sup is a single Go binary that SSH-es into target machines, downloads the K3s installer, runs it with the correct flags, and retrieves the resulting kubeconfig. It does not install an agent or leave a daemon on the target; all orchestration happens client-side. The optional k3sup app install feature uses Helm under the hood.

Self-Hosting & Configuration

• No server-side installation needed; k3sup runs entirely from your local machine
• Requires SSH key-based access to target hosts (password auth also supported)
• K3s version can be pinned with --k3s-version for reproducible deployments
• Custom K3s flags are passed through with --k3s-extra-args for TLS SANs, disable components, etc.
• Works on x86_64, ARM64, and ARMv7 for Raspberry Pi clusters

Key Features

• Single binary with zero dependencies beyond SSH access to the target
• Full cluster from zero to kubectl-ready in under 60 seconds
• Built-in app installer for cert-manager, OpenFaaS, Prometheus, and other popular tools
• HA mode with --cluster flag for multi-server etcd-based setups
• Cross-architecture support makes it ideal for edge and IoT Kubernetes deployments

Comparison with Similar Tools

• k3s installer script — The raw script requires manual token passing and kubeconfig retrieval; k3sup automates the full flow
• Ansible + K3s — Ansible playbooks are flexible but heavyweight; k3sup is a single binary with no inventory files
• kubeadm — Official bootstrapper for full K8s; k3sup targets lightweight K3s clusters with less ceremony
• Rancher — Full management platform with a web UI; k3sup is CLI-only and focused purely on bootstrapping
• Talos Linux — Immutable K8s OS; k3sup works on any existing Linux distribution

FAQ

Q: Does k3sup work with Raspberry Pi? A: Yes. k3sup fully supports ARM architectures and is widely used for Pi-based home clusters.

Q: Can I install additional software after cluster creation? A: Yes. The k3sup app install command provides a curated catalog of Helm-based apps for common cluster add-ons.

Q: Does k3sup support HA clusters? A: Yes. Use --cluster on the first server and --server --server-ip for additional control plane nodes with embedded etcd.

Q: Is k3sup suitable for production? A: It is a bootstrapping tool. The resulting K3s cluster is production-ready (K3s is CNCF-certified); k3sup simply automates the setup.

Sources

• https://github.com/alexellis/k3sup
• https://k3sup.dev/