Set up a multi-node Olares cluster

For workloads that require more computing resources and distributed storage, you can add a worker device to an existing single-node Olares system to form a multi-node cluster.

Learning objectives

By the end of this guide, you will learn how to:

• Enable JuiceFS on an existing Olares master node.
• Generate and securely handle the command for joining a worker node.
• Add a worker node and check that the cluster is ready.

Before you begin

Choose the role of each device before you start:

• The existing single-node Olares system is the master node.
• The device you are adding is the worker node.

Use a separate terminal window for each device, and keep each window connected to the same device throughout the setup.

Run commands on the correct node

This guide switches between the master and worker terminals. Check the hostname in your terminal prompt before running each command. Running a migration or uninstall command on the wrong node can disrupt your Olares system.

Prerequisites

Make sure the following requirements are met:

• Olares 1.12.7 or later is installed, activated, and running on the master.
• You can access both devices over SSH and run commands with sudo. Password-based SSH sign-in is enabled on the master.
• The worker can reach the master's SSH address and the join script URL generated by the master.

Back up the master node

Enabling JuiceFS stops Olares and migrates its local file system. Back up important data before you continue, and do not power off the master node during the migration.

Step 1: Enable JuiceFS On master node

JuiceFS provides the shared file system required by a multi-node cluster.

1. Connect to the master node over SSH.

   For a device running Olares, you can find its local IP address in LarePass under Settings > System > your device > Network > Intranet IP. If you use Olares One and need help finding its SSH password, see Access Olares One via SSH.

   ssh <username>@<master-node-ip-address>

2. Stop Olares.

   sudo olares-cli stop

3. Enable JuiceFS and migrate the existing Olares file system.

   sudo olares-cli node enable-juicefs

   Olares restarts automatically after the migration. Wait until the command reports that JuiceFS is enabled and the master is ready to accept worker nodes.

   Example output:

   [Job] Enable JuiceFS on the master node and migrate rootfs execute successfully!!! (...)
   JuiceFS is enabled on this master node (version <version>); it is now ready to accept worker nodes.
   Run 'olares-cli node join-command' on this master to print the command for a worker node.

Step 2: Generate the worker join command On master node

1. On the master node, run:

   sudo olares-cli node join-command

2. Check the detected SSH address and username. Enter y to confirm them, or enter the correct username when prompted.

3. Enter the SSH password for the selected user.

   Olares checks that the worker can use this account to connect to the master and run commands with sudo. If the check fails, confirm the IP address, username, password, SSH service, and firewall settings, then try again.

4. Copy the generated command. You will run it on the worker node in the next step.

   Example output:

   SSH login and sudo access verified for <username>@<master-ip-address>:22.
   
   Run the following command on the worker node:
   
   export MASTER_AUTH_INFO='<encoded-auth-info>' OLARES_SYSTEM_CDN_SERVICE='<olares-cdn-url>' && curl -fsSL '<join-script-url>' | bash
   
   MASTER_AUTH_INFO is Base64-encoded, not encrypted. Anyone holding this command can recover the master's SSH credentials, so share it only with the intended worker administrator.

Protect the join command

The generated MASTER_AUTH_INFO value is Base64-encoded, not encrypted. Anyone who has the command can recover the master's SSH credentials. Share it only with the administrator of the intended worker, and never post it in a public channel or repository.

Step 3: Add the worker node On worker node

Check the worker state

The worker must not have a complete Olares installation. If Olares is installed, back up any important data and run sudo olares-cli uninstall before joining the worker. The join command stops and displays this instruction if it detects an existing installation.

1. Connect to the worker node over SSH.

2. On the worker, paste and run the complete command you generated in Step 2. The command follows this pattern:

   export MASTER_AUTH_INFO='<encoded-master-connection-information>' \
     OLARES_SYSTEM_CDN_SERVICE='<olares-cdn-url>' \
     && curl -fsSL '<join-script-url>' | bash

   Use the generated command exactly as shown. Do not copy the placeholder command above.

3. If the command reports that Olares is already installed, uninstall it:

   Joining this machine to an Olares cluster as a worker node, using the Olares <version> installer.
   error: Olares <version> is already installed on this node; run 'sudo olares-cli uninstall' before joining it to another cluster

   sudo olares-cli uninstall

   When the uninstall finishes, run the generated join command again.

4. The join process uses the worker's current hostname as its node name. If the hostname is valid and unique in the cluster, no action is required.

   If the hostname cannot be used, enter a new one when prompted. The join process updates the worker's hostname automatically.

   The hostname must:

   • Contain only lowercase letters, numbers, hyphens (-), or periods (.).
   • Start and end with a letter or number.
   • Be unique in the cluster.

   For example, you can use olares-worker.

The join process checks the connection to the master, prepares the matching Olares version, and adds the worker to the cluster.

When the worker joins successfully, the output ends with a confirmation similar to this:

[Job] Add Worker Node To The Cluster execute successfully!!! (...)

This node joined the Olares cluster at <master-ip-address> as "<worker-node-name>".
Verify it on the master with: sudo /usr/local/bin/kubectl get nodes

Step 4: Verify the cluster On master node

Olares uses Kubernetes to manage the cluster. On the master node, run the following kubectl command to check the status of all nodes:

sudo /usr/local/bin/kubectl get nodes

Confirm that the master and worker nodes both appear and their status is Ready.

Example output:

NAME          STATUS   ROLES                         AGE   VERSION
master-node   Ready    control-plane,master,worker   1h    v1.33.3+k3s1
worker-node   Ready    worker                        1m    v1.33.3+k3s1

Resources

• Olares environment variables: Learn about the environment variables used for advanced Olares configurations.
• Set up a cluster with two Olares One devices on Olares 1.12.6: Follow the current manual procedure before Olares 1.12.7 is released.