Cluster Nodes

QuickStack allows you to scale your applications and improve availability by setting up a cluster across multiple Virtual Private Servers (VPS). This guide walks you through the process of connecting additional servers to your primary QuickStack installation. The initial server is the master node; additional servers you join are worker nodes.

Understanding the Concept of a Cluster

• What is a Cluster? A cluster is a group of computers (in this case, VPSs) that work together as a single system. By distributing your applications across multiple servers, you can handle more users, and you provide a more stable environment if one server has a problem.
  • Single Node Cluster: A single node cluster is a QuickStack installation on a single server. This is the default setup when you install QuickStack for the first time.
  • Multi Node Cluster: A multi-node cluster is a QuickStack installation that spans multiple servers. Each server in the cluster is responsible for running a part of the applications you deploy. It is recommended to use a private network for the communication between the servers.

Single node

A single server runs the k3s control plane, QuickStack, and all workloads. This is the default installation.

Multi node

The master node keeps the public IP, while the worker nodes join it over a private network. Each server runs part of the workloads.

Viewing cluster nodes

1. Go to Settings → Platform → Cluster.
2. All nodes and their status are listed.

Each node shows:

• Name — hostname or identifier
• CPU / RAM / Disk status — 🟢 normal / 🔴 pressure
• Schedulable — whether new workloads can be placed here

Add a worker node

Prerequisites

• Supported Linux distribution (Ubuntu, Debian, etc.)
• Network connectivity to the master node
• Port 6443 (Kubernetes API) accessible from the new server
• SSH access to the new server

Step 1: Get the join command

1. Go to Settings → Platform → Cluster.
2. Click Add Cluster Node.
3. Copy the displayed command.

The command looks like:

curl -sfL https://get.quickstack.dev/setup-worker.sh | K3S_URL=https://MASTER_IP:6443 JOIN_TOKEN=K10... sh -

sudo cat /var/lib/rancher/k3s/server/node-token

Step 2: Configure the command

Replace MASTER_IP with:

• The internal/private IP for nodes in the same network (recommended)
• The public IP for nodes across the internet

Step 3: Run on the new server

ssh root@new-worker-server
curl -sfL https://get.quickstack.dev/setup-worker.sh | K3S_URL=https://192.168.1.100:6443 JOIN_TOKEN=K10... sh -

Step 4: Verify

Return to Settings → Platform → Cluster. The new node appears within a few minutes. Verify all status indicators are green.

Manage node scheduling

Deactivate a node (drain)

Prevents new pods from being scheduled on this node. Existing workloads continue running.

1. Find the node in the cluster overview.
2. Click the node and select Deactivate Node.

Reactivate a node (uncordon)

1. Find the deactivated node.
2. Click Activate Node.

Remove a worker node

• 1. Deactivate a node (drain)
• 2. Delete the node (on master)

kubectl delete node <node-name>

Troubleshooting

Planning considerations