Manage Nodes

Nodes are the compute units in exalsius. They represent individual machines (e.g., IaaS VMs or physical nodes). You can import nodes, which adds them to your node pool. Nodes in your node pool are managed by exalsius and can be used to deploy clusters.

Node Provisioning Concepts

exalsius supports two approaches for provisioning and managing nodes:

Self-Managed Nodes (via SSH): This is the standard, fully supported method for adding nodes to your pool. A self-managed node can be any machine you have SSH access to, including:
- On-premise servers: Bare metal or virtualized machines in your own data center.
- Cloud instances: Virtual machines from any cloud provider (e.g., AWS EC2, Google Compute Engine).
Direct Cloud Integration (Coming Soon): We are developing a direct integration with cloud providers to automate provisioning. Soon, you will be able to provision nodes directly from the exls CLI using cloud offers, streamlining on-demand scaling of your compute capacity. This feature is currently under development. The sections below describe the current SSH-based workflow and preview the upcoming direct import functionality.

Importing Nodes via SSH

Nodes can be added to the node pool either through an interactive process or by providing the required parameters directly.

SSH Access

You need SSH access to the nodes you want to import. You will need to provide the SSH endpoint and the private key to allow exalsius to connect to the node. We recommend creating a dedicated Deploy SSH Key for each cluster, as all nodes within a cluster must share the same key. The SSH user should have passwordless sudo access to ensure correct setup and resource discovery.

Prerequisites

Before importing a node, ensure it meets the following requirements:

Supported Operating Systems

OS Version	Status
Ubuntu 24.04 LTS	Tested (with latest kernels)
Ubuntu 22.04 LTS	Tested (with latest kernels)

Software Dependencies

exalsius automatically installs required GPU drivers (NVIDIA and AMD) for nodes running standard kernels (e.g., Ubuntu's default generic kernel).

Cloud Provider Custom Kernels

Public cloud providers often use their own compiled kernels with custom suffixes (e.g., -aws, -azure, -gcp). For these kernels, automatic AMD ROCm driver installation is not supported. If your node uses a cloud provider kernel and has AMD GPUs, ROCm 7.0 needs to be pre-installed before importing the node. Refer to the AMD ROCm installation guide for instructions.

Docker Not Supported

Nodes cannot have pre-installed Docker. exalsius uses containerd for its Kubernetes deployment, and Docker interferes with containerd's operation. If Docker is already installed, we recommend removing it before importing the node.

Firewall Requirements

For the import process to succeed, ensure that SSH (TCP port 22) is open on your nodes. Additional ports may be required depending on the workload you want to run. See the Firewall Configuration for details.

Option 1 - Interactive Import

Run the following command to start an interactive import session:

exls nodes import

You will be prompted to enter required details such as:

Node hostname and IP address
SSH username
SSH key selection

This guided process is ideal for managing a few nodes.

Once a node is successfully imported, exalsius automatically runs a discovery process to detect and record available system resources, including:

Available GPU devices and their specifications
CPU architecture and core count
Main memory

Info

The endpoint can be either a DNS name or a direct IP address, optionally including the SSH port (e.g., 192.168.1.10:22).

After the import, the node’s status will appear in your node list.

You can check it with:

exls nodes list

Option 2 - SSH Import via CLI Options

For automated workflows, you can import a node directly using CLI flags. First, make sure your SSH key is imported.

Check the list of imported SSH keys with:

exls management ssh-keys list

Import a new key with:

exls management ssh-keys import --key-path <path-to-private-key-file>

To import your node, run:

exls nodes import-ssh \
  --endpoint <ip:port> \
  --username <ssh-username> \
  --ssh-key-id <id-of-imported-ssh-key>

Example:

exls nodes import-ssh \
  --endpoint "203.0.113.42:22" \
  --username "ubuntu" \
  --ssh-key-id "9591093c-17f9-48fa-95bb-11700f330b88"

CLI Reference

exls nodes import-ssh --help

Upcoming Feature: Direct Import from Cloud Offers

To simplify scaling and reduce manual effort, we are building a direct cloud import feature. Once released, you will be able to provision and import cloud instances in a single step using the exls CLI.

This feature will allow you to scan for the best GPU prices across providers and then instantly provision nodes based on those offers.

How It Will Work (Feature Preview)

You will be able to list available instances using:

exls offers list

Then, you could import a node directly from an offer:

exls nodes import-offer <OFFER-ID> --amount 2

This command would automatically provision two instances from the cloud provider and add them to your exalsius node pool.

Under Active Development

This functionality is not yet released and is under active development.

Verifying Imported Nodes

To view all imported nodes:

exls nodes list

To inspect a specific node:

exls nodes get <NODE-ID>

You can verify:

Node health and connectivity
Node ownership and type

Info

Imported nodes will appear in your node pool and can be used by clusters and workspaces once in status AVAILABLE.

Deleting Nodes

If a node is no longer needed or has become unreachable, you can remove it from the node pool.

Run the following command:

exls nodes delete <NODE-ID>

CLI Reference

exls nodes delete --help

Warning

Deleting a node permanently removes it from your node pool.
Any workloads or clusters using this node will lose access to it.
Always ensure the node is not currently hosting active workloads before deletion.

Next Steps

Once nodes are imported, you can use them to deploy Clusters