Skip to content
longbridge docs
Open Console →

Join a node

Attach machines to your cluster — a homelab box, a Hetzner server, or an AWS instance — over an outbound-only tunnel that works behind NAT.

A node is any machine running Talos Linux that you attach to your control plane. The join is outbound-only: the node dials the control plane, so there’s no public IP, no inbound firewall hole, and no port-forwarding to set up. The same three steps work everywhere.

Get a short-lived token and a ready-made config for your cluster with lb node token <cluster> and lb node config <cluster> --token <token>. The token expires; mint a fresh one per machine.

Any machine, three steps

  1. Boot Talos on the machine from the official image.
  2. Apply the worker config that points at your cluster: 
    talosctl apply-config --insecure --nodes <machine-ip> --file worker.yaml
  3. Confirm it registered with kubectl get nodes.

The specifics below are just how you get a Talos machine in each environment.

Homelab

Write the Talos image to a USB stick or boot it on a VM (Proxmox, UTM, plain QEMU all work). A mini-PC, an old laptop, or a Raspberry Pi (arm64) are all fine. Because the join is outbound-only, a machine on your home LAN behind NAT joins with no router changes.

Hetzner

Boot a Cloud server into rescue and install the Talos image, or use a Talos snapshot. A small shared-vCPU instance (for example cx23) is plenty for a worker. Apply the config and it registers over the public network — still outbound-initiated.

AWS

Launch an instance from a Talos AMI (build one with the Talos image factory, or use a community AMI). Spot instances are a good fit: cheap, and the control plane simply sees nodes come and go. Security group needs no inbound rules for the join.

Removing a node

Drain it, then delete it from the cluster and tear the machine down:

kubectl drain <node> --ignore-daemonsets --delete-emptydir-data
kubectl delete node <node>

The hardware is yours — reclaim it whenever you like. That’s the no-lock-in part, made literal.

Troubleshooting

  • Node never appears. Check the machine has outbound internet and the token hasn’t expired. Mint a fresh one with lb node token <cluster>.
  • NotReady after joining. A CNI is installing; give it a minute. If it persists, check the node’s clock is in sync.