Skip to content

Node contributor guide

A node contributor adds a single machine to an existing cluster, so that its spare CPUs, memory and GPUs can run AI workloads for the network.

At a glance

You will: join one machine to a cluster.
You need: kubeadm at the cluster's version, the cluster ID, and the network's Parser URL.

How it works

sequenceDiagram
    participant You as Your machine
    participant Reg as Cluster registry
    participant P as Network Parser
    participant K as Cluster (Kubernetes)
    You->>Reg: 1. Look up the cluster (join command, kubeadm version)
    You->>P: 2. Request to join, with this machine's resources
    P-->>You: Accepted (network and cluster add_node policies pass)
    You->>K: 3. kubeadm join
    K-->>You: Node labelled with its nodeID

Join a node

  1. Check the requirements. Your machine needs network access to the cluster, a static IP if joining over the internet, and VPN access if the cluster uses one. See Join a node: before you start.

  2. Get the cluster's details, including its join command:

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

    You need clusterMetadata.additionalInfo.joinCommand and clusterMetadata.additionalInfo.kubeadmVersion.

  3. Run the join script on your machine:

    cd k8s/onboarding/node
    
    ./join-node.sh \
      --node-id node-001 \
      --cluster-id cluster-abc \
      --api-url <parser-url> \
      --kubeadm-join-cmd "<join command from step 2>"
    

If both the network's and the cluster's add_node policies accept your machine, it joins the cluster. The Cluster Controller then labels it with its nodeID.

After you join

  • Your machine runs a metrics collector that reports CPU, memory, disk and GPU use to the cluster. See Node metrics.
  • Blocks may place instances on your machine, and several instances may share one GPU.
  • If your machine becomes unhealthy, the cluster moves its workloads to other nodes.