Building a 2-node cluster + qdevice for the home lab

Is a 2-node home cluster worth it?

The short answer: yes, for learning. The longer answer: it has real caveats.

A 2-node cluster plus a qdevice gives you:

• Hands-on experience with Proxmox clustering
• HA demonstration (a VM can restart on the other node)
• Live migration between the two nodes (with shared storage or replication)
• A stepping stone to a 3+ node cluster later

The caveat: 2-node clusters without a qdevice split-brain on the slightest network blip. The qdevice provides the tiebreaker vote.

What you need

• 2× mini-PCs running Proxmox VE 9.x (let’s call them pve1 and pve2)
• 1× Raspberry Pi 3/4/5 (or any lightweight Linux box) for the qdevice
• A wired network connecting all three (the cluster link MUST be wired; Wi-Fi will cause headaches)
• All three on the same subnet, or routed properly

Network design

Use a dedicated subnet for the cluster link. Simplest:

flowchart TD
  Internet([internet]) --> Router[ISP router<br/>192.168.1.1]
  Router --> Switch{Home switch}
  Switch --> PVE1[pve1<br/>192.168.1.10]
  Switch --> PVE2[pve2<br/>192.168.1.11]
  Switch --> QDev[qdevice<br/>Raspberry Pi<br/>192.168.1.20]
  PVE1 <-->|corosync| PVE2

For a more advanced setup, dedicate a NIC on each PVE for cluster traffic (separate subnet), but for a home lab the single subnet is fine.

Step 1: Set up the qdevice host

The Raspberry Pi runs the corosync-qnetd daemon, which acts as a third-party vote provider.

# On the Raspberry Pi (Raspberry Pi OS / Debian)
sudo apt update
sudo apt install -y corosync-qnetd

# Enable and start
sudo systemctl enable --now corosync-qnetd

# Verify the qnetd is listening
ss -tlnp | grep 5403
# Should show: LISTEN 0  1  0.0.0.0:5403  ... corosync-qnetd

Step 2: Prepare each Proxmox node

Both nodes need:

• Same NTP source (chrony is installed by default)
• Same /etc/hosts entries for both nodes
• Cluster-friendly hostname + FQDN
• SSH keys between root accounts

# On BOTH pve1 and pve2 — edit /etc/hosts
# (heredoc replaced)
echo "192.168.1.10  pve1.lab.local  pve1" >> /etc/hosts
echo "192.168.1.11  pve2.lab.local  pve2" >> /etc/hosts
echo "192.168.1.20  qdevice.lab.local  qdevice" >> /etc/hosts
# Verify resolution
ping -c 2 pve2.lab.local
ping -c 2 qdevice.lab.local

Step 3: Create the cluster on pve1

# On pve1, create the cluster
pvecm create homecluster

# This takes a few seconds. Verify:
pvecm status

# Expected output:
# Cluster information
# -------------------
# Name:             homecluster
# Config Version:   1
# Transport:        knet
# Secure auth:      on

Step 4: Join pve2 to the cluster

# On pve2, get the cluster join info from pve1
# Easiest: copy the join info from pve1
# On pve1:
pvecm status
# Look for the "Cluster IP" or generate join info
pvecm addnode pve2 -link0 192.168.1.11

# Actually, the correct way:
# On pve2, run:
pvecm add 192.168.1.10

# It will prompt for the root password of pve1, then join.

Step 5: Add the qdevice

# On pve1 (or any cluster node), add the qdevice
pvecm qdevice setup 192.168.1.20

# This installs the corosync-qdevice client package, generates TLS certs,
# and tells corosync about the qdevice.

# Verify
pvecm status

# Expected output should now show:
# Votes:   3
# Expected votes: 3

Step 6: Verify HA works

# Create a test VM (or use an existing one)
# Enable HA on it
ha-manager add vm:100 --group default --max-restart 3 --max-relocate 2

# Check HA status
ha-manager status

# Simulate a node failure (CAREFUL)
# On the OTHER node (not the one running the VM):
# Stop corosync
systemctl stop corosync

# Watch the VM migrate / restart on the other node
# Watch from the UI: the VM should show as running on pve2 within 30 seconds

# Restart corosync on pve1 when done
systemctl start corosync

Common 2-node home-cluster issues

Corosync link goes down

If the link between pve1 and pve2 drops, both nodes become unsure of their quorum. With the qdevice, one node keeps quorum (the one that can still talk to the qdevice). The other fences itself.

Symptoms:

• VMs go down on one node
• That node’s UI shows “waiting for quorum”
• The other node is fine

Fix: restore the link. Corosync will reconnect within a few seconds.

Split brain after a network blip

If neither node can talk to the qdevice (e.g., the qdevice Pi reboots), both nodes lose quorum and shut down. This is correct behaviour — better to have downtime than corrupted VMs.

Fix: wait for the qdevice to come back, and the cluster will re-establish quorum automatically.

pve2 fails to join

Most common cause: SSH keys or hostname resolution. Verify:

# From pve2, can you SSH to pve1 without password?
ssh root@pve1.lab.local

# Does DNS/hosts resolve?
getent hosts pve1.lab.local

# Are both nodes running the same Proxmox version?
pveversion -v

When 2-node isn’t enough

If your workloads include:

• Heavy write I/O (database, large Ceph) → 3+ nodes with proper storage
• Production-tier VMs → 3+ nodes with HA and replication
• Frequent network maintenance → 3+ nodes (more forgiving)

A 2-node home cluster is for learning and light workloads. If you find yourself wanting more, add a third mini-PC — the cost is similar to a Raspberry Pi and the cluster becomes much more capable.

Key takeaways

• 2-node clusters need a qdevice to avoid split-brain
• A Raspberry Pi running corosync-qnetd is the simplest qdevice
• The whole setup takes about 30 minutes including the qdevice
• HA works, but with caveats — a network blip means downtime
• A 2-node setup is a stepping stone; go to 3+ for real workloads

Knowledge check