Proxmox Cluster Setup

What Is a Proxmox Cluster?

A Proxmox VE cluster groups multiple physical servers into a single managed environment. Once nodes are clustered, you manage every VM and container from any node’s web interface, migrate guests between hosts, and layer High Availability on top — none of which a standalone node can offer on its own.

Think of a Proxmox cluster as a group of people who all agree to keep identical copies of the same notebook. Every time one person writes something new — a VM created, a storage pool added — the change gets copied to everyone else’s notebook immediately. If too many people go missing at once, the remaining group refuses to let anyone write anything new until enough of them are back, so no two people can end up disagreeing about what the notebook says.

Under the hood, that notebook is pmxcfs, the Proxmox Cluster Filesystem, which transparently distributes everything under /etc/pve to every node. The “agreeing to keep writing” part is handled by Corosync, which manages node membership and quorum voting, and pvecm is the tool you use to actually create, join, and inspect the cluster.

Why Cluster Instead of Standalone Nodes?

A single Proxmox node works fine for a lab box or a single-purpose server, but clustering earns its complexity once you have more than one host to manage.

Why Quorum and Corosync Matter

Clustering only helps if the cluster can be trusted to agree on its own state, and that is exactly what Corosync’s quorum mechanism exists to guarantee. Every node gets one vote by default, and the cluster needs a strict majority of votes online before it will accept configuration changes. Lose quorum, and the surviving nodes deliberately switch to a read-only state rather than risk two halves of a split cluster making conflicting changes at the same time.

This matters most right before it becomes an emergency: a HA-managed guest whose node just went dark, a live migration mid-flight when a network link drops, or a config change queued up during a switch reboot. A cluster that lost quorum silently refusing writes looks, from the outside, exactly like a cluster that’s broken — until you check pvecm status.

Requirements Before You Start

Corosync is latency-sensitive, so treat the cluster network as its own concern rather than an afterthought bolted onto whatever NIC was free.

Creating and Joining a Cluster

Run these from the node’s shell. Create the cluster on the first node, then join every additional node to it individually.

# On the first node — create the cluster (name cannot be changed later)
pvecm create homelab-cluster

# Optional: create it with an explicit corosync link address
pvecm create homelab-cluster --link0 10.10.10.1

# Check the local view of cluster status and quorum
pvecm status

# List cluster nodes from the local view
pvecm nodes

# On each additional node — join using the IP of an existing cluster member
pvecm add 10.10.10.1

# Join specifying this node's own local IP on a dedicated corosync link
pvecm add 10.10.10.1 --link0 10.10.10.2

# Remove a node from the cluster (run from a remaining node, after migrating its guests off)
pvecm delnode oldnode

Corosync Configuration

pvecm create and pvecm add generate /etc/pve/corosync.conf for you — you rarely need to hand-edit it, but knowing its shape makes cluster status output much easier to read.

logging {
  debug: off
  to_syslog: yes
}

nodelist {
  node {
    name: uno
    nodeid: 1
    quorum_votes: 1
    ring0_addr: 10.10.10.1
  }
  node {
    name: due
    nodeid: 2
    quorum_votes: 1
    ring0_addr: 10.10.10.2
  }
  node {
    name: tre
    nodeid: 3
    quorum_votes: 1
    ring0_addr: 10.10.10.3
  }
}

quorum {
  provider: corosync_votequorum
}

totem {
  cluster_name: homelab-cluster
  config_version: 3
  ip_version: ipv4-6
  secauth: on
  version: 2
}

Quorum and the Two-Node Problem

A 3-node cluster needs 2 votes for quorum and survives one node failure cleanly. A 2-node cluster needs both votes — meaning either node failing takes the whole cluster read-only, which defeats much of the point of clustering in the first place. Proxmox’s own guidance is to treat three nodes as the practical minimum for a cluster that needs to survive a single failure.

If you’re stuck at two nodes — a common homelab reality — a QDevice gives you a third, external vote without needing a third full Proxmox node.

Setting Up a QDevice

A QDevice runs on a separate, independent machine — a Raspberry Pi or a small VM outside the cluster works fine — and arbitrates quorum over the network rather than participating in the cluster itself.

# On the external QDevice host (not a cluster member)
apt install corosync-qnetd

# On every Proxmox cluster node
apt install corosync-qdevice

# From a cluster node — configure the QDevice (copies the cluster's SSH key automatically)
pvecm qdevice setup 10.10.10.50

# Confirm the QDevice is now counted in cluster status
pvecm status

If you ever need to add or remove a cluster node afterward, remove the QDevice first with pvecm qdevice remove, make the node change, then set the QDevice back up.

pvecm Cheat Sheet

Troubleshooting Cheat Sheet

Final Thoughts

Most of what makes Proxmox clustering trustworthy is the part that’s invisible day to day — Corosync quietly counting votes and pmxcfs quietly replicating configuration, both handled long before you ever notice them working. The failures that do surface almost always trace back to one of two things: a network that can’t give Corosync the low, stable latency it needs, or a vote count that was never designed to survive the failure you just had.

For a homelab sitting at two nodes, a QDevice is cheap insurance against exactly that second failure mode — it costs a spare Raspberry Pi and ten minutes, against a cluster that goes read-only every time you reboot either box for patching.