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¶
-
kubeadmis installed on the machine, at the same version as the target cluster. The version is in the cluster'sclusterMetadata.additionalInfo.kubeadmVersionfield (see step 1). -
python3andpip3. - (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:
For example:
In the response, find:
clusterMetadata.additionalInfo.joinCommand: thekubeadm joincommand for this clusterclusterMetadata.additionalInfo.kubeadmVersion: thekubeadmversion 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:
- collects the machine's CPU, memory, storage, network and GPU details
- sends them to the network's Parser (
/api/addNode) to request membership - only if the request is accepted, runs the
kubeadm joincommand 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¶
- Read the Node contributor guide.
- Learn how nodes are monitored: Metrics system.