LinuxinfrastructureTested on real hardware

Deploy k3s on a single node (Linux)

Stand up a real, compliant Kubernetes cluster in one command with k3s: install the server node, confirm it's Ready, deploy a self-healing test app, and see how to add workers later.

Distrosubuntu, debian
Shellbash
Updated
Script
bash
# Install k3s — a fully compliant, lightweight Kubernetes distribution — on one node.
# Server minimum: 2 CPU cores, 2 GB RAM. Run as a user with sudo.

# 1. Install k3s (server). Starts it as a systemd service and brings up a 1-node cluster.
curl -sfL https://get.k3s.io | sh -

# 2. Confirm the node is Ready (k3s bundles its own kubectl).
sudo k3s kubectl get nodes

# 3. Deploy a test app and scale it — delete a pod and watch it heal.
sudo k3s kubectl create deployment web --image=nginx
sudo k3s kubectl scale deployment web --replicas=3
sudo k3s kubectl get pods

# 4. (Optional) drive the cluster with a standalone kubectl using the kubeconfig k3s wrote.
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

# --- Add a worker (agent) node later ---
# On the SERVER, read the join token:
#   sudo cat /var/lib/rancher/k3s/server/node-token
# On the NEW machine, join it (replace the IP and token):
#   curl -sfL https://get.k3s.io | K3S_URL=https://10.0.0.30:6443 K3S_TOKEN=YOUR_NODE_TOKEN sh -

What this does

This installs k3s — a fully compliant Kubernetes distribution packaged as a single binary under 100 MB — on one Linux machine, giving you a working single-node cluster. It then deploys a small test Deployment and scales it to three replicas so you can watch Kubernetes self-heal: delete a pod and a replacement appears within seconds. The final commented block shows how to join additional worker nodes when you outgrow one machine.

For the concepts and a guided walkthrough, see How and When to Use Kubernetes in a Homelab and the Kubernetes overview.

Prerequisites

  • A Linux host with 2 CPU cores and 2 GB of RAM minimum for the server node, per the k3s requirements. A mini PC, a VM, or a Proxmox LXC/VM all work.
  • curl available and a user with sudo.
  • Outbound HTTPS to get.k3s.io for the installer.

Notes

  • Make these values your own: replace 10.0.0.30 with your server node’s real IP and YOUR_NODE_TOKEN with the token you read from /var/lib/rancher/k3s/server/node-token, in the agent-join line only. Steps 1–4 need no edits. If a value looks specific to one machine, it’s a placeholder to change, not a literal to copy.
  • Where kubectl and the kubeconfig live. k3s ships its own kubectl (sudo k3s kubectl ...) and writes the cluster config to /etc/rancher/k3s/k3s.yaml. That file is root-owned; to use a standalone kubectl, copy it to ~/.kube/config and keep it private — it grants full cluster access.
  • Unique hostnames per node. Every node must have a unique hostname. If two share one, add K3S_NODE_NAME=some-unique-name to that node’s install command.
  • Uninstalling is clean. k3s installs an uninstall script: run /usr/local/bin/k3s-uninstall.sh on a server node (or k3s-agent-uninstall.sh on an agent) to remove it completely.
All playbooks