Skip to content

Join a node to a cluster

A node is a single machine, such as a server, a workstation or a cloud VM. By joining it to an existing cluster, you add its CPUs, memory and GPUs to the cluster's shared pool. You can add nodes at any time.

At a glance

Who this is for: anyone contributing a machine.
You need: the target cluster ID and the network's Parser URL.
Result: the machine is part of the cluster and can run block instances.

Before you start

Software

  • kubeadm is installed on the machine, at the same version as the target cluster. The version is in the cluster's clusterMetadata.additionalInfo.kubeadmVersion field (see step 1).
  • python3 and pip3.
  • (GPU machines) NVIDIA drivers with nvidia-smi, so that GPU details can be reported.

Network

What you need depends on where the machine is.

If the machine is on the same internal network as the cluster's master node, behind a common firewall, open:

  • 30000–32767 (TCP/UDP), the NodePort range

The cluster accepts external machines only if its configuration sets config.allowExternalNodes=true.

Port Protocol Component Purpose
10250 TCP kubelet Communication with the control plane
30000–32767 TCP/UDP NodePort services Services exposed through NodePort

Note

  • A static IP address is required.
  • If the cluster uses a VPN, join the VPN first. VPN access is arranged with the cluster owner and is not managed by AIOS.

Step 1: Get the cluster's details

Look up the target cluster in the network's cluster registry:

curl -X GET http://<cluster-registry-url>/clusters/<cluster-id>

For example:

curl -X GET http://<cluster-registry-url>/clusters/cluster-west-vision-001

In the response, find:

  • clusterMetadata.additionalInfo.joinCommand: the kubeadm join command for this cluster
  • clusterMetadata.additionalInfo.kubeadmVersion: the kubeadm version to install

Step 2: Join the node

Run the join script from the repository, on the machine you are adding:

cd k8s/onboarding/node

./join-node.sh \
  --node-id <node-id> \
  --cluster-id <cluster-id> \
  --api-url <parser-url> \
  --kubeadm-join-cmd "<join command from step 1>"
Option Meaning
--node-id A unique ID for this machine, for example node-001.
--cluster-id The ID of the cluster to join, for example cluster-west-vision-001.
--api-url The network's Parser URL.
--kubeadm-join-cmd The joinCommand from step 1, in quotes.

The script:

  1. collects the machine's CPU, memory, storage, network and GPU details
  2. sends them to the network's Parser (/api/addNode) to request membership
  3. only if the request is accepted, runs the kubeadm join command to join the machine to the cluster

What decides whether you are accepted: the node joins only if it passes the add_node governance policies of both the network and the cluster.

After joining

The Cluster Controller automatically labels the node with its nodeID. No further action is needed.


Next steps