LinuxinfrastructureTested on real hardware

Add a worker node to a k3s cluster (Linux)

Grow a single-node k3s cluster into a real multi-node one: read the join token off the server and register a new agent node with one command.

Distrosubuntu, debian
Shellbash
Updated
Script
bash
# Add a worker (agent) node to an existing k3s cluster.
# Run each step on the machine noted. Agent minimum: 1 CPU core, 512 MB RAM.

# 1. On the SERVER node — read the cluster join token.
sudo cat /var/lib/rancher/k3s/server/node-token

# 2. On the NEW machine — join it to the cluster.
#    Replace 10.0.0.30 with the server's IP and YOUR_NODE_TOKEN with the token from step 1.
curl -sfL https://get.k3s.io | K3S_URL=https://10.0.0.30:6443 K3S_TOKEN=YOUR_NODE_TOKEN sh -

# 3. Back on the SERVER — confirm the new node joined and reached Ready.
sudo k3s kubectl get nodes

What this does

This registers a new agent (worker) node against an existing k3s server, expanding a single-node cluster into a multi-node one. You read a shared join token from the server, run the k3s installer on the new machine with that token and the server’s URL, and confirm the node reaches Ready. Once it joins, Kubernetes begins scheduling pods across both machines automatically.

This is the copy-paste version of Task 4 in How and When to Use Kubernetes in a Homelab; start from the Deploy k3s on a single node playbook if you don’t have a server yet.

Prerequisites

  • A running k3s server node (see the single-node playbook).
  • A second Linux machine with 1 CPU core and 512 MB of RAM minimum, per the k3s requirements, plus room for your workloads.
  • Network reachability from the new machine to the server on TCP 6443.

Notes

  • Make these values your own: replace 10.0.0.30 with your server node’s real IP or hostname, and YOUR_NODE_TOKEN with the exact string printed by step 1. If a value looks specific to one machine, it’s a placeholder to change, not a literal to copy.
  • Unique hostnames are required. Every node must have a distinct hostname. If the new machine shares one with an existing node, add K3S_NODE_NAME=some-unique-name to the install command in step 2.
  • The token is a cluster credential. Anyone with the server URL and this token can join the cluster — treat it like a password, and rotate it if it leaks.
  • Removing a node. To detach an agent, run /usr/local/bin/k3s-agent-uninstall.sh on it, then sudo k3s kubectl delete node <name> on the server.
All playbooks