Adding Agent Nodes
Agents are workers that join an existing server to run more Pods.
Syntax
curl -sfL https://get.k3s.io | K3S_URL=... K3S_TOKEN=... sh -To grow past a single machine, add agent nodes. An agent needs two things to join: the URL of a server and the node token.
The two required values
K3S_URL—https://<server-ip>:6443K3S_TOKEN— the token from the server
When K3S_URL is set, the install script knows you want an agent, not a server, and runs k3s agent for you.
Example
# Run this ON THE AGENT machine
curl -sfL https://get.k3s.io | \
K3S_URL=https://192.168.1.10:6443 \
K3S_TOKEN=K10abc123...::server:def456... \
sh -
# Back on the server, the new node appears
kubectl get nodesWhen to use it
- A team horizontally scales its k3s cluster by adding two agent nodes so Deployment replicas spread across more hardware.
- An edge operator adds a GPU-equipped arm64 agent node to an existing k3s server to run ML inference workloads.
- A lab environment joins three Raspberry Pis as agent nodes to a single server node running on an x86 mini PC.
More examples
Join a worker node
Installs k3s in agent mode on the worker and connects it to the existing server using the URL and token.
# Run on the worker machine:
curl -sfL https://get.k3s.io | \
K3S_URL=https://192.168.1.10:6443 \
K3S_TOKEN=<node-token> sh -Verify nodes after joining
Lists all cluster nodes after the agent joins, confirming the worker appears as Ready in the node list.
# Run on the server node:
kubectl get nodes -o wide
kubectl describe node worker-01 | grep -A5 'Taints\|Labels'Label and taint a worker node
Adds a label and taint to a worker so only pods with matching tolerations are scheduled on it.
kubectl label node worker-01 role=compute env=production
kubectl taint node worker-01 dedicated=compute:NoSchedule
kubectl get node worker-01 --show-labels
Discussion