How to Set Up a Proxmox Cluster: Complete Guide

Why Cluster Your Proxmox Nodes?

Running a single Proxmox VE server works fine for small setups, but as your infrastructure grows, clustering multiple nodes unlocks powerful capabilities: live VM migration, centralized management, high availability, and distributed storage. A Proxmox cluster lets you manage all your nodes from a single web interface and move workloads between hosts without downtime.

This guide walks you through every step of creating a production-ready Proxmox cluster, from initial requirements to monitoring cluster health.

Cluster Requirements

Before you begin, make sure your environment meets these prerequisites:

• Minimum of 2 nodes (3 or more recommended for proper quorum)
• Same Proxmox VE version on all nodes
• Reliable network connectivity between all nodes (low latency, ideally under 2ms)
• Unique hostnames and static IP addresses for each node
• DNS resolution working correctly between nodes (or entries in /etc/hosts)
• NTP configured so clocks are synchronized across all nodes
• No existing cluster membership on any node you plan to join

A common mistake is attempting to cluster nodes with different Proxmox VE major versions. Always ensure all nodes are running the same version before proceeding.

Step 1: Prepare Your Nodes

On each node, verify the hostname and IP configuration. Every node must be able to reach every other node by hostname.

# Check hostname on each node
hostname

# Verify /etc/hosts has entries for all nodes
cat /etc/hosts

# Example /etc/hosts entries
192.168.1.10  pve1.local pve1
192.168.1.11  pve2.local pve2
192.168.1.12  pve3.local pve3

Make sure NTP is running and clocks are in sync:

# Check time synchronization
timedatectl status

# If chrony is installed
chronyc tracking

Step 2: Create the Cluster

Choose one node to be the initial cluster creator. Log into that node via SSH and run:

# Create a new cluster named "my-cluster"
pvecm create my-cluster

This initializes the corosync configuration and creates the cluster filesystem (pmxcfs). You can verify the cluster was created:

# Check cluster status
pvecm status

You should see output showing a single node in the cluster with quorum.

Step 3: Add Nodes to the Cluster

On each additional node, run the join command pointing to the IP address of the first node:

# On pve2, join the cluster via pve1's IP
pvecm add 192.168.1.10

# You'll be prompted for the root password of pve1

After joining, the node's previous configuration will be replaced with the cluster configuration. Any existing VMs or containers on the joining node will remain, but the node's web interface configuration is replaced by the cluster-wide config.

Repeat for each additional node. After all nodes have joined, verify the full cluster:

# List all cluster nodes
pvecm nodes

# Full cluster status
pvecm status

Understanding Corosync and Quorum

Proxmox uses Corosync as its cluster communication layer. Corosync handles node membership, messaging, and quorum voting. Each node gets one vote, and the cluster requires a majority (more than 50%) to maintain quorum.

Quorum Rules

• 2-node cluster: Losing one node means no quorum (the remaining node cannot operate HA). You need to set expected_votes manually or use a QDevice.
• 3-node cluster: Can tolerate one node failure and still maintain quorum.
• 4-node cluster: Can still only tolerate one failure (needs 3 of 4 for majority).
• 5-node cluster: Can tolerate two simultaneous failures.

Adding a QDevice for 2-Node Clusters

If you only have two Proxmox nodes, a QDevice (Quorum Device) provides a third vote from an external lightweight server:

# On an external Debian/Ubuntu server, install the QDevice packages
apt install corosync-qdevice corosync-qnetd

# On one of your Proxmox nodes, add the QDevice
pvecm qdevice setup 192.168.1.50

# Verify the QDevice is connected
pvecm status

Configuring the Cluster Network

For production clusters, you should use a dedicated cluster network separate from your VM traffic. This prevents cluster communication from competing with VM workloads.

# During cluster creation, specify a dedicated link
pvecm create my-cluster --link0 10.10.10.10

# When joining, specify the same network
pvecm add 10.10.10.10 --link0 10.10.10.11

Proxmox supports up to 8 redundant links (link0 through link7) for corosync. Using two links on separate networks provides fault tolerance for the cluster network itself:

# Create cluster with two redundant links
pvecm create my-cluster --link0 10.10.10.10 --link1 10.10.20.10

Network Best Practices

• Use a dedicated VLAN or physical NIC for cluster traffic
• Ensure the cluster network has low latency and no packet loss
• Consider bonded interfaces for redundancy on the cluster link
• Keep cluster traffic on a private, non-routable network

Shared Storage for the Cluster

While a Proxmox cluster works without shared storage, you need it for live migration and high availability. Common shared storage options include:

• Ceph (built-in): Distributed storage running directly on Proxmox nodes, no external hardware needed
• NFS: Simple to set up with an external NAS or file server
• iSCSI: Block-level shared storage from a SAN
• GlusterFS: Distributed file system for larger deployments

For small clusters, NFS is the easiest way to get started. For larger or more performance-sensitive setups, Ceph is the recommended approach since it's tightly integrated with Proxmox.

Monitoring Cluster Health

Once your cluster is running, regular monitoring is essential. From the command line:

# Quick cluster health check
pvecm status

# Check corosync ring status
corosync-cfgtool -s

# View cluster node list with status
pvecm nodes

# Check for cluster partition or quorum issues
journalctl -u corosync --since "1 hour ago"

The Proxmox web interface also provides cluster status under Datacenter > Summary, showing all nodes, their status, and resource usage at a glance.

For monitoring on the go, ProxmoxR lets you check your cluster node status, resource usage, and VM state directly from your phone. This is especially useful for receiving alerts and verifying cluster health when you're away from your desk.

Troubleshooting Common Cluster Issues

Node Cannot Join the Cluster

• Verify network connectivity: ping pve1 from the joining node
• Check that port 8006 (API) and ports 5405-5412 (corosync) are open
• Ensure SSH root login is enabled on the target node
• Confirm the joining node is not already part of another cluster

Cluster Loses Quorum

# In an emergency (single-node needs to operate), override quorum
pvecm expected 1

# Warning: only use this when you're certain other nodes won't come back up
# with conflicting data

Removing a Node from the Cluster

# First, migrate all VMs off the node
# Then, on a remaining node:
pvecm delnode pve3

# On the removed node, reset its configuration
systemctl stop pve-cluster corosync
pmxcfs -l
rm -f /etc/corosync/*
rm -f /etc/pve/corosync.conf
killall pmxcfs
systemctl start pve-cluster

Conclusion

A properly configured Proxmox cluster gives you the foundation for live migration, high availability, and centralized management of your entire virtualization infrastructure. Start with three nodes if possible to ensure clean quorum handling, use a dedicated cluster network, and set up shared storage early. Once your cluster is stable, you can build on it with HA groups and automated failover to keep your workloads running even when hardware fails.