Add a new PVE node to an existing cluster
1 · Prerequisites
Confirm every item is in place before any state change.
- DNS forward and reverse for the new node resolves correctly
- NTP is working on the new node
- The new node runs the same Proxmox VE version as the cluster
- Network connectivity on TCP 22, 8006, UDP 5404-5405 between nodes
2 · Pre-checks
Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.
- · On the master: pvecm status shows quorum OK
- · On the new node: pvecm status shows the node is alone (or not in a cluster)
3 · Procedure
Execute each step in order. Verify the expected output of a step before moving to the next.
- 1On the master: pvecm status to confirm cluster fingerprint
- 2On the master: note the cluster master IP and fingerprint
- 3On the new node: pvecm addnode --fingerprint <fp> <master-ip> -password 0
- 4Wait 30 seconds; verify pvecm status shows the new node
- 5On any node: pvesh get /cluster/resources --output-format yaml | grep -E node
4 · Verification
Confirm the procedure actually fixed the problem.
- ✓pvecm status shows quorum OK and all nodes present
- ✓pvesh get /cluster/resources lists the new node as online
- ✓pmxcfs synced (new node sees all VMs and storage)
5 · Rollback
If verification fails, undo the procedure in reverse order.
- ↶On the new node: pvecm delnode (only if newly joined and unreachable)
- ↶Or rebuild the new node if its pmxcfs is corrupted
6 · Escalation
When the runbook isn't enough, contact:
- · Cluster lead (engineering)
- · Network team if Corosync cannot reach the new node
- · Vendor support if pvecm addnode fails with cryptic errors
Add a new PVE node to an existing cluster
This runbook covers adding a node to an existing cluster.
When to use
- Capacity expansion (adding a 4th or 5th node)
- Hardware refresh (replacing an old node)
- Geographic expansion
Prerequisites
- DNS forward AND reverse resolves for the new node’s hostname and IP
- NTP is synchronised on the new node (
chronyc trackingorntpdate -q) - The new node runs the same Proxmox VE version as the cluster
- Network connectivity to the master on UDP 5404-5405, TCP 22, 8006
- OOB management (iDRAC/iLO/IPMI) is configured and reachable
Pre-checks
On the master:
pvecm status
# Expect: Quorum information: Quorate: Yes
# Expect: Master node: <some node>
# Note the cluster fingerprint and master IPOn the new node:
pvecm status
# Expect: this node is alone or not in a clusterProcedure
Step 1: Get cluster info from the master
pvecm statusNote the Master Node IP and the cluster fingerprint. The fingerprint is shown on the cluster join page in the GUI.
Step 2: Join from the new node
pvecm addnode --fingerprint <cluster-fingerprint> <master-ip> -password 0Or via the GUI: Datacenter → Cluster → Join Cluster.
Step 3: Wait for sync
sleep 30
pvecm status
# Verify: Quorate: Yes, all nodes presentStep 4: Verify
pvesh get /cluster/resources --output-format yaml | grep node
# Should list all nodes, including the new oneOn the new node:
ls /etc/pve/qemu-server/ | head
# Should list VMs from the clusterVerification checklist
-
pvecm statusreports quorum OK - All nodes appear in
pvesh get /cluster/resources - The new node sees the cluster’s VMs in the GUI
- Storage shared between nodes works (test by reading a VM disk)
Rollback
If the join fails or the new node has issues:
# Substitute the name of the node you are removing:
NODE_NAME=pve-04
# On the new node (if it can still reach the cluster):
pvecm delnode "$NODE_NAME"
# If the new node is unreachable from the cluster:
# From the master:
pvecm delnode "$NODE_NAME" --skip-fencing-checkIf pmxcfs is corrupted on the new node, rebuild it from scratch and re-join.
Escalation
- Cluster lead: notify before and after the operation
- Network team: if Corosync cannot reach the new node
- Vendor support: if
pvecm addnodefails with cryptographic errors