A Proxmox cluster is not just multiple machines connected to a switch. It’s four nodes running a consensus protocol (Corosync) that keeps them in agreement about the state of the cluster — which containers are running where, what resources are allocated, what configuration changes have been made. This post covers forming the cluster, what quorum actually protects you from, and the verification steps that confirm everything is wired correctly.
This is part of the Building a Homelab series. Your nodes should already have Proxmox installed with static IPs — see the Proxmox install guide first.
What Corosync does
Corosync is the cluster communication layer. It runs as a daemon on every node and uses UDP multicast (or unicast) to broadcast heartbeat messages. Every 250ms, each node shouts “I’m alive” to the cluster. If a node misses enough heartbeats, the cluster declares it offline.
This heartbeat traffic is separate from your container network traffic. It’s low-bandwidth (~1 MB/s total for a 4-node cluster) but latency-sensitive — Corosync works best on a reliable, low-latency network (like your gigabit switch, not a WiFi link).
What quorum is and why it matters
Quorum is the minimum number of nodes that must be online and in agreement for the cluster to remain operational. In a 4-node cluster, quorum is 3 votes (a majority).
What happens when quorum is lost:
- Existing VMs and containers keep running — they don’t stop
- No new containers can be started or stopped
- No live migrations
- No configuration changes to the cluster
- The web UI shows “Cluster not ready - no quorum”
This is a safety mechanism, not a failure. Without quorum protection, if your network partitions into two groups of 2 nodes each, both halves might start making conflicting changes — that’s a “split-brain” scenario that can corrupt shared storage and cluster state.
Quorum by node count:
| Nodes | Quorum required | Max nodes that can fail |
|---|---|---|
| 1 | 1 | 0 (no HA) |
| 2 | 2 | 0 (no HA — both must be up) |
| 3 | 2 | 1 |
| 4 | 3 | 1 |
| 5 | 3 | 2 |
With 2 nodes, quorum requires both to be up. If either fails, the cluster locks. Most people add a third node (or a Proxmox Qdevice — a lightweight quorum arbiter) to avoid this. 3-node and 4-node clusters are much more practical.
Task 1: Prepare nodes for clustering
The cluster join process uses SSH to copy cluster certificates between nodes. Test this before starting:
ssh root@10.0.0.71 "hostname" # should print: pvelab02
ssh root@10.0.0.72 "hostname" # should print: pvelab03
ssh root@10.0.0.73 "hostname" # should print: pvelab04
If any of these fails, check:
- The target node’s IP is correct (
ip addr showon the target) - No firewall is blocking port 22
- The target node is powered on and reachable (
ping 10.0.0.71)
# Run this on each node
hostname
ip addr show eth0 | grep "inet "
Each node must have:
- A unique hostname (pvelab01, pvelab02, etc.)
- A unique static IP
- The correct gateway configured
If any nodes share a hostname or IP, you must fix this before clustering — Corosync uses hostnames to identify nodes.
Proxmox cluster communication uses hostnames. Each node needs to resolve all other nodes’ hostnames via /etc/hosts (not just DNS, which can be slow or unavailable):
cat >> /etc/hosts << 'EOF'
10.0.0.70 pvelab01 pvelab01.homelab.lan
10.0.0.71 pvelab02 pvelab02.homelab.lan
10.0.0.72 pvelab03 pvelab03.homelab.lan
10.0.0.73 pvelab04 pvelab04.homelab.lan
EOF
Run the same command on all four nodes (with all four IPs listed). The Proxmox installer usually adds the node’s own entry; add the others.
Task 2: Create the cluster on node 1
SSH to pvelab01 and create the cluster:
pvecm create myofficelab
This:
- Initialises Corosync on pvelab01
- Generates cluster certificates
- Creates the
/etc/pve/cluster configuration directory - Starts the pve-cluster service
Check the cluster status immediately:
pvecm status
Expected output:
Cluster information
-------------------
Name: myofficelab
Config Version: 1
Transport: knet
Secure auth: on
Quorum information
------------------
Date: Sun Jul 6 00:00:00 2026
Quorum provider: corosync_votequorum
Nodes: 1
Node ID: 0x00000001
Ring ID: 1.7
Quorate: Yes
Votequorum information
----------------------
Expected votes: 1
Highest expected: 1
Total votes: 1
Quorum: 1
Flags: Quorate“Quorate: Yes” with 1 node means the cluster is running. It will need 3 nodes to be fault-tolerant.
Task 3: Join the remaining nodes
From the web UI (the easiest method): log into pvelab01’s web UI → Datacenter → Cluster → Join Information → Copy Information.
Then log into pvelab02’s web UI → Datacenter → Cluster → Join Cluster → paste the join information → enter pvelab01’s root password → click Join.
Or via command line on pvelab02:
pvecm add 10.0.0.70
You’ll be prompted for pvelab01’s root password. The join process:
- Copies cluster certificates from pvelab01 to pvelab02
- Starts Corosync on pvelab02
- Syncs the cluster configuration
This takes 30–60 seconds. After completion, both nodes’ configuration is managed by the cluster.
Repeat the join command on each remaining node, pointing to pvelab01 each time:
pvecm add 10.0.0.70
pvecm add 10.0.0.70
Do not try to join multiple nodes simultaneously. Wait for each join to complete and verify before starting the next. Joining two nodes at once can cause a race condition in the certificate exchange.
Task 4: Verify the cluster is healthy
pvecm status
pvecm nodes
Expected output from pvecm nodes:
Membership information
----------------------
Nodeid Votes Name
1 1 pvelab01 (local)
2 1 pvelab02
3 1 pvelab03
4 1 pvelab04All four nodes listed, all showing 1 vote. Total votes = 4, quorum = 3.
Open https://10.0.0.73:8006 (any node works — they all show the same cluster view now). Here’s what the Proxmox web UI looks like with a healthy 4-node cluster:
All four nodes appear in the left sidebar with green status dots. Click any node to see its individual CPU, RAM, and storage summary.
Create a minimal test container (or use an existing one) and live-migrate it between nodes to confirm networking and clustering are working:
In the web UI: select any running container → Migrate → Target Node: pvelab02 → Migrate.
A live migration of a small container takes 3–15 seconds. You should see it appear under pvelab02 after the task completes. If migration fails, check the task log for the error.
Task 5: Configure cluster-wide settings
In the web UI: Datacenter → Options → DNS Domain: set to homelab.lan (or your domain).
This affects how container hostnames resolve within the cluster.
cat /etc/corosync/corosync.conf
This file shows the cluster name, the node list, and the network rings Corosync uses for heartbeats. You shouldn’t need to edit it manually — pvecm manages it — but it’s useful to understand what’s there.
Understanding what changes after clustering
Once clustered, the /etc/pve/ directory is synchronised across all nodes using a distributed filesystem called pmxcfs. This means:
- Any configuration change on pvelab01 immediately appears on all other nodes
- Container configs (
/etc/pve/lxc/*.conf) are cluster-wide — you can migrate containers without copying files - The cluster keeps a lock on configuration operations — only one node can make changes at a time
Things that are not shared:
- Local storage (your NVMe content — VM disks live on the node’s local LVM)
/etc/hosts, network config, package lists — these are per-node
Removing a node from the cluster
If you need to permanently remove a node (hardware failure, decommission):
# Only do this if the node is permanently offline and will not rejoin
pvecm delnode pvelab04
Only remove a node after moving all its containers to other nodes. Removing a node while it still holds container configs orphans those configs — the containers can’t be managed until you recover them manually.
Next steps
With a working 4-node cluster, the next step is security hardening — SSH key authentication, disabling password login, and configuring the Proxmox firewall.
→ Continue to: Proxmox Security Hardening: SSH Keys, Firewall, and Hardening Your New Cluster
Related posts:
- Proxmox Security Hardening — lock down the cluster you just built
- Proxmox LXC Networking: Bridges, VLANs, and Static IPs — the bridges carrying inter-node and guest traffic
- Proxmox Backup Server: Automated Container Backups — protect the workloads running on the cluster
- Creating Your First Proxmox VM — VMs gain live migration across cluster nodes
- Proxmox VM vs LXC: When to Use Each — live migration is one of the trade-offs that decides VM vs container
This post contains Amazon affiliate links (tag: buildahomelab-20). I earn a small commission on qualifying purchases at no extra cost to you.