Joining a Node

Worker nodes are Linux machines (bare-metal or VMs) that you join to a cluster using a join token.

Prerequisites

• Linux (x86_64 or arm64)
• Root access
• Outbound internet access (to download k0s and reach the API)

Option 1: gctl CLI

Download the latest binary from GitHub Releases:

curl -fsSL https://github.com/geeper-io/geeper-cluster/releases/latest/download/gctl-linux-amd64 \
  -o /usr/local/bin/gctl && chmod +x /usr/local/bin/gctl

Then join:

sudo gctl cluster join <join-token>

The CLI will:

1. Download the correct version of k0s
2. Write HAProxy certificates
3. Install and start the k0s worker service

Option 2: Shell script

No CLI needed:

curl -fsSL https://console.geeper.io/api/v1/node/install.sh | sh -s -- <join-token>

What happens after joining

The node registers itself with the cluster control plane via k0s. Within a few seconds it will appear as Ready in kubectl get nodes.

Troubleshooting

Check the k0s service logs:

journalctl -u k0sworker -f