k3sup

k3sup is a lightweight utility designed to bootstrap Kubernetes using k3s on local or remote VMs. It automates the process of:

1. SSHing into a remote server.
2. Installing k3s (server or agent) using the Rancher utility script.
3. Fetching the kubeconfig file automatically to your local machine so you can use kubectl immediately.

Key Capabilities:

• Bootstrap Kubernetes: Use k3sup install to set up a k3s server on any VM (AWS, GCP, DigitalOcean, etc.) or Raspberry Pi.
• Join Nodes: Use k3sup join to add existing Linux hosts as agents to an existing k3s cluster.
• Local Installation: Use k3sup install --local to bypass SSH if you are running k3s on your local machine.
• Automation: Supports use in CI/CD or via cloud-init.

Terminology

• Kubernetes: Uses master/slave terminology.
• k3s: Uses server/agent terminology.

Related Tools

• k3s: The lightweight Kubernetes distribution that k3sup installs.
• k3d: Runs k3s inside a Docker container on your local machine.
• kind: Runs Kubernetes clusters within Docker containers (not recommended for remote clusters).
• kubeadm: A heavier-weight tool for production-ready clusters, primarily aimed at cloud VMs or bare-metal (less ideal for low-powered ARM devices).
• k3v: A PoC for slicing a single cluster for multiple tenants.
• k3sup-multipass: A helper to launch a single-node k3s cluster using multipass VMs.

You can create a multi-master setup using an external SQL database (like MySQL).

1. Prepare the Datastore: Ensure your connection string is in the format required by k3s (e.g., wrapping host/port in tcp()).
2. Generate a Token: Create a 64-character token to secure the cluster.
3. Install Servers: Run k3sup install on multiple VMs using the --datastore and --token flags.
4. Join Agents: Join worker nodes to any of the servers.

For a multi-master setup using embedded etcd, you need an odd number of nodes (at least three).

1. Initialize the first server: Use the --cluster flag during the initial k3sup install.
2. Join additional servers: Use the k3sup join command with the --server flag to add more master nodes to the quorum.

Use the k3sup install command to provision a new Kubernetes server on a remote VM (e.g., Ubuntu, Debian, Raspbian). You must ensure SSH keys are configured on the target host. You can target a machine via its IP address or a hostname.

Common usage patterns:

• Via IP: Use --ip and --user.
• Via Hostname (e.g., EC2): Use --host, --user, and --ssh-key to specify the path to your private key.
• Local Install: Use --local to install k3s directly on your current machine without using SSH.
• Skip Installation: Use --skip-install if k3s is already present; this command will only retrieve the kubeconfig.

To manage remote clusters using your local kubectl or kubectx, use the --merge and --local-path flags during installation. This prevents overwriting your existing configuration and instead appends the new cluster context.

Example: Merging a cluster with the context name my-k3s into the default $HOME/.kube/config file.

k3sup install \
  --ip $IP \
  --user $USER \
  --merge \
  --local-path $HOME/.kube/config \
  --context my-k3s

If your SSH keys are protected by a password or stored on a hardware device (like a YubiKey), you can use ssh-agent to avoid re-typing passwords for every k3sup command.

1. Start the agent: eval $(ssh-agent)
2. Add your key: ssh-add ~/.ssh/id_rsa
3. Run k3sup commands normally; they will now use the keys from the agent.

k3sup is distributed as a static Go binary. You can install it on MacOS and Linux using the following shell script, or download the executable for Windows from the GitHub Releases page.

After installation, verify it works by running k3sup --help.

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

k3sup --help

To use K3sup Pro, you must activate your license.

• Individuals: Run k3sup-pro activate to verify your identity via GitHub.com. This is typically done on your local workstation.
• Commercial Users: Place your license key directly at ~/.k3sup/LICENSE to bypass the activation command.

The k3sup ready command verifies if a cluster is operational by running kubectl get nodes using the provided kubeconfig. It looks for the "Ready" status on all nodes.

You can check a local installation, a remote server, or a specific context merged into your existing configuration.

The k3sup pro plan command generates a YAML plan file for a High Availability K3s installation based on provided JSON host files. This YAML file can be edited and committed to Git for infrastructure management.

Workflow:

1. Create JSON files containing hostnames and IPs.
2. Run k3sup pro plan with the JSON files and desired cluster configuration.
3. Edit the resulting YAML file if necessary.
4. Run k3sup pro apply to execute the installation.

k3sup pro plan ./n100.json ./n200.json \
  --user ubuntu \
  --servers 3 \
  --svclb=false \
  --server-extra-args "--disable traefik" \
  --agent-extra-args "--node-label worker=true"

k3sup is designed to rewrite or merge your cluster's configuration into your local KUBECONFIG file on your client machine. You should run kubectl from your local workstation, not directly on the K3s hosts.

If you have lost your configuration, use the k3sup get-config command to retrieve it. This command supports various flags for merging configurations and setting context names.