A Proxmox cluster ties several hosts together under one web interface. You manage every node and VM from a single login, you migrate VMs between hosts, and with the right storage you get live migration and high availability. The tool that does the work is pvecm, and the join is two commands.
This guide builds a cluster from standalone nodes: create it on the first host, join the others, and confirm quorum is healthy. Then it covers the parts people get wrong — what corosync and quorum actually do, why two-node clusters are fragile, how shared storage enables live migration, and how to remove a node without leaving the cluster in a bad state. Steps target Proxmox VE 8.x.
Before you start, each node should be a working, fully updated Proxmox install with its own static IP and a unique hostname. If you haven’t built the hosts yet, install Proxmox VE on bare metal first, then come back.
What you need first
Clustering is unforgiving about a couple of prerequisites. Sort these before running any command.
Before you cluster
- Every node on the same Proxmox VE major version (e.g. all 8.x)
- A unique hostname and a static IP on each node
- All nodes able to resolve and ping each other
- No VMs yet on the nodes you're joining (joining wipes their VM list)
- A low-latency network between nodes for corosync — ideally a dedicated link
- Time synced (NTP) across all nodes
Step 1: Create the cluster on the first node
Pick one node to start the cluster. On it, give the cluster a name and run:
# on the first node — names the cluster "pve-cluster"
pvecm create pve-clusterThat’s it for node one. Check the status:
pvecm statusYou’ll see one node, a quorum section, and the corosync ring information. A single node always has quorum with itself, so it reports Quorate: Yes.
Step 2: Join the other nodes
On each additional node, join using the IP of the first node. Run this on the joining node, not on the first one:
# on node 2, node 3, etc. — point at the cluster's existing node
pvecm add 192.168.1.50It asks for the root password of the target node and checks SSH connectivity, then pulls the cluster config down. After it finishes, refresh the web GUI on any node — all of them now appear in the left-hand tree under the datacenter.
Confirm the whole cluster sees itself:
pvecm status
pvecm nodespvecm nodes lists every member with its node ID and vote. You want all nodes Online and the status Quorate: Yes.
Step 3: Understand corosync and quorum
This is the concept that explains every weird cluster behavior, so it’s worth a moment even though there’s nothing to type.
Corosync is how nodes talk to each other and agree on cluster state. Quorum is the rule that the cluster will only change its configuration when more than half the votes are present. The shared config filesystem at /etc/pve (backed by pmxcfs) depends on quorum.
Votes, majority, and what survives a failure
| 2 nodes (2 votes) | Majority is 2. Lose one node and you're at 1 vote — below majority, so the cluster loses quorum. Fragile. |
|---|---|
| 3 nodes (3 votes) | Majority is 2. Lose one node and 2 votes remain — still quorate. The practical minimum. |
| 4 nodes (4 votes) | Majority is 3. Tolerates one failure, but an even count risks a tie on a clean 2-2 split. |
| 5 nodes (5 votes) | Majority is 3. Tolerates two failures. Odd counts avoid ties. |
When a cluster loses quorum, the running VMs keep running — they don’t drop — but /etc/pve goes read-only. You can’t create or change VMs, edit storage, or migrate until a majority comes back. This is deliberate: it stops two halves of a split network from both editing shared config and corrupting it (split-brain).
Step 4: Add shared storage for live migration
A cluster works with each node on its own local storage, but the disk lives on one host. To move a running VM between nodes without copying its disk every time, every node needs to reach the same storage.
Shared storage options for a cluster
| Ceph | Distributed storage built into Proxmox, runs on the nodes themselves. No external SAN needed. Wants at least 3 nodes and a fast, separate network. The go-to for hyper-converged clusters. |
|---|---|
| NFS | A NAS or file server every node mounts. Simple to set up and widely used. The NAS becomes a single point of failure unless it's itself redundant. |
| iSCSI / Fibre Channel | Block storage from a SAN, shared to all nodes. Common where a SAN already exists. More setup, often paired with LVM on top. |
Add shared storage under Datacenter → Storage → Add, and because it’s defined at the datacenter level every node picks it up automatically. Once a VM’s disk sits on shared storage, migration just moves the running memory state.
Step 5: Live-migrate a VM
With a healthy cluster and shared storage, migration is a click. Select the VM, hit Migrate, choose the target node, and start it. Proxmox copies the memory state across and switches execution to the new node with no downtime.
From the CLI:
# live-migrate VM 101 to node "pve02"
qm migrate 101 pve02 --onlineThe --online flag is what makes it a live migration of a running VM. Drop it and the VM has to be stopped first (offline migration).
Removing a node from the cluster
Pulling a node out has a specific order, and doing it wrong leaves corosync referencing a ghost member.
- Migrate or back up everything off the node you’re removing.
- Power that node off permanently — it must not come back online with its old identity.
- From a remaining node, delete it by name:
# run on a node that's staying — remove "pve03"
pvecm delnode pve03- Confirm with
pvecm statusthat the node count dropped and the cluster is still quorate.
The two-node problem and QDevices
Two-node clusters are common in small setups and inherently fragile: two votes means a single failure drops you to one vote, below majority, and the survivor loses quorum even though it’s perfectly healthy. Your VMs keep running but you can’t manage anything.
A QDevice fixes this. It’s an external tie-breaker — a small always-on machine (a Raspberry Pi, a NAS, any Linux box) running corosync-qnetd. It contributes a third vote without being a full Proxmox node, so either real node can fail and the survivor plus the QDevice still hold a majority.
Set it up by installing the qnetd package on the external box and the client on the nodes, then registering it:
# on the external tie-breaker machine (Debian/Ubuntu)
apt install corosync-qnetd
# on each Proxmox node
apt install corosync-qdevice
# on one Proxmox node, register the QDevice (use the external box's IP)
pvecm qdevice setup 192.168.1.60After setup, pvecm status shows the QDevice as an extra vote and the expected total rises by one.
Where to go from here
A working cluster gives you one pane of glass, painless migration, and the foundation for high availability. The pieces that make it solid are an odd vote count, a low-latency network for corosync, and shared storage if you want live migration to be quick.
Two natural follow-ups: decide your storage layout, since it dictates how migration and HA behave — Proxmox LVM vs LVM-Thin vs ZFS covers the local options, while Ceph or NFS handle the shared side. And make sure your backup routine spans the cluster, not just one node, with Proxmox backups. If you’re still choosing a platform, Proxmox VE vs VMware ESXi puts the clustering and HA story side by side. For more walkthroughs, browse the Proxmox guides.
