Mastering Proxmox Connectivity: A Definitive Guide To Building A Two-Node Cluster

Connecting two Proxmox Virtual Environment (PVE) nodes into a unified cluster requires a synchronized Corosync communication layer and a dedicated low-latency network interface to ensure real-time configuration database replication. Success is defined by achieving a quorum-ready state where the Proxmox Cluster File System (pmxcfs) maintains a consistent SQLite-backed configuration across all member nodes without exceeding a 2-millisecond network latency threshold.

Infrastructure Prerequisites and Pre-Cluster Planning

Before initiating the clustering process, it is imperative to verify that both physical servers are running identical versions of Proxmox VE. While minor version mismatches are sometimes tolerated during upgrades, initial cluster creation demands architectural parity to prevent Corosync versioning conflicts. Each node must possess a unique hostname that is resolvable via the local hosts file, and static IP addresses are non-negotiable; using DHCP for cluster nodes will eventually lead to a total loss of management access if an IP lease changes and breaks the Corosync ring.

The fundamental components required for a successful integration include:

• Network Hardware: A minimum of two physical network interfaces (NICs) per node is recommended. One interface should be dedicated to standard VM traffic and management, while the second should be a direct-connect or isolated VLAN link specifically for Corosync traffic to prevent congestion-induced "fencing."
• Latency Standards: The round-trip time (RTT) between the two nodes must stay consistently below 2ms. Higher latency will trigger node instability, causing the Proxmox Cluster File System to lock into a read-only state to prevent data corruption.
• Time Synchronization: Both nodes must be synchronized to the same NTP or Chrony source. Even a five-second drift can cause authentication tokens to expire prematurely, preventing the second node from successfully joining the cluster.
• Authentication Requirements: You must have the root password for both nodes and ensure that SSH is permitted over the network between the two servers.
• Storage Considerations: While clustering enables central management, it does not automatically provide shared storage. If you intend to use Live Migration between the two nodes, you must have a shared storage backend such as Ceph, ZFS over iSCSI, or an NFS mount configured on both nodes.

Executing the Node Integration and Clustering Workflow

The process of connecting two Proxmox servers involves designating one node as the initial cluster creator and the second as the joining peer. This workflow can be completed entirely through the Proxmox Web Interface, though the backend mechanisms rely on the Proxmox Cluster Manager (pvecm) utility.

Step 1: Initializing the Primary Cluster Node

Navigate to the web interface of the server you wish to designate as the primary node. In the Datacenter view on the left-hand navigation pane, select the Cluster option. Click the Create Cluster button at the top of the interface. You will be prompted to enter a Cluster Name; this should be a simple, alphanumeric string without spaces or special characters.

Within this dialog, you must select the Cluster Network (Link 0). This is the most critical decision in the setup. Select the IP address associated with your dedicated, low-latency network interface. If you only have one network, select the management IP, but be aware that high traffic on this network can disrupt cluster communication. Once you click Create, Proxmox will generate the necessary cryptographic keys and initialize the /etc/pve/corosync.conf file.

Pro-Tip: If you are working in a professional production environment, configure a second link (Link 1) immediately during creation. This provides a fallback path for Corosync if the primary network interface fails, preventing the node from rebooting itself due to a loss of quorum.

Step 2: Extracting Join Information

Once the cluster is created on the first node, click the Join Information button in the same Cluster menu. A window will appear containing a long, Base64-encoded string known as the Join Information. This string contains the primary node's fingerprint, its IP addresses, and the cluster name. Click the Copy Information button to save this to your clipboard.

Step 3: Integrating the Second Node into the Cluster

Log in to the web interface of the second Proxmox server—the one that is not yet part of a cluster. Ensure that this node does not have any active Virtual Machines or Containers with IDs that conflict with the first node. If Node 1 has a VM with ID 100 and Node 2 also has a VM with ID 100, the join process will fail or cause metadata corruption.

Go to Datacenter, then Cluster, and click the Join Cluster button. Paste the information you copied from the first node into the Information block. The system will automatically populate the Peer Address and Fingerprint fields. You will then be prompted to enter the root password of the first node to authorize the SSH key exchange. Just as before, select the local network interface that matches the cluster network you chose on the first node. Click Join 'ClusterName'.

Warning: During the join process, the web interface of the joining node will become unresponsive for several seconds. This is normal, as the local /etc/pve directory is being overwritten by the cluster-wide versioned file system. Do not refresh the page or restart the server during this transition.

Step 4: Configuring the Quorum Device for Two-Node Stability

By default, a Proxmox cluster requires a majority of nodes to be online to maintain a "Quorum." In a two-node setup, a majority is 2 out of 2. If one node goes offline, the remaining node has only 50% of the votes, which is not a majority. Consequently, the remaining node will lose quorum, stop all IO operations for VMs, and prevent any configuration changes.

To fix this, you must introduce a third "vote" without necessarily adding a third full Proxmox server. This is achieved through the Proxmox External Vote Provider, or QDevice. You can install the corosync-qnetd package on a small Linux VM or a Raspberry Pi outside the cluster. Then, on both Proxmox nodes, install the corosync-qdevice package. Use the pvecm qdevice setup command followed by the IP of your external device to link them. This ensures that if one Proxmox node fails, the other node and the QDevice together provide 2 out of 3 votes, allowing the remaining server to continue functioning.

Comparative Performance and Network Benchmarks

The following table outlines the technical thresholds required to maintain a healthy connection between two Proxmox servers based on different network configurations.

Mitigating Critical Cluster Failures and Network Partitions

Even a perfectly configured two-node cluster can encounter issues due to hardware failure or network "split-brain" scenarios. Understanding the root causes of these failures is essential for maintaining uptime.

Scenario 1: Node shows "Unknown" status in the GUI after a network interruption.

• Root Cause: The Corosync service has lost connectivity on the designated cluster link, causing the nodes to stop communicating. Even if the management network is up, the cluster network may be down.
• Actionable Fix: Access the console of the disconnected node and verify the status of the Corosync service. Check the local network interface using the ip link command. If the network is physically fine, restart the pve-cluster and corosync services. If the node cannot regain quorum, you may need to temporarily force it to accept a single vote by using the command pvecm expected 1.

Scenario 2: "Authentication Failed" or "Permission Denied" during the join process.

• Root Cause: This is typically caused by stale SSH fingerprints in the /etc/ssh/ssh_known_hosts file or a time desynchronization between the two servers.
• Actionable Fix: Manually verify that you can SSH from Node 2 to Node 1 using the root account. If an "Offending key" error appears, remove the old host key. Additionally, run the date command on both nodes to ensure they are within the same minute of each other.

Scenario 3: The cluster becomes read-only and VMs cannot start.

• Root Cause: The cluster has lost quorum. In a two-node setup without a QDevice, if one node is powered off, the other enters a protective read-only mode because it no longer sees a majority of votes.
• Actionable Fix: The long-term fix is to add a QDevice. The immediate emergency fix is to tell the remaining node that it only needs one vote to be healthy. Execute the command pvecm expected 1 in the terminal. This will immediately restore the cluster to a "Quorate" state, allowing you to manage and start VMs.

Frequently Asked Questions

Can I connect two Proxmox servers with different hardware specifications?

Yes, Proxmox allows you to cluster nodes with different CPU architectures (e.g., Intel and AMD), but you must set the VM CPU type to "kvm64" or "common" to ensure compatibility during live migrations. If you use "host" passthrough for CPUs, migrating a VM from an Intel host to an AMD host will cause a kernel panic in the guest operating system.

How do I remove a node from the cluster if it becomes permanently unavailable?

If a node is physically destroyed and cannot be brought back online, you must remove it from the cluster configuration manually. From the healthy node, use the command pvecm delnode followed by the name of the failed node. Afterward, you must manually delete the node's directory from /etc/pve/nodes/ to clean up the web interface view.

Is a dedicated crossover cable between two nodes sufficient for clustering?

While a crossover cable provides the lowest possible latency and isolates Corosync traffic, it creates a single point of failure. If the cable or one of the NICs fails, the cluster will lose quorum. It is better to use a dedicated VLAN on a redundant switch or two separate physical links to provide high availability for the cluster communication layer.

What happens if the cluster name I choose already exists on the network?

Proxmox uses the cluster name to generate specific multicast or unicast traffic tags. If two different clusters on the same network share a name, it can lead to packet collisions and instability. Always use a unique name for each cluster and, if possible, isolate clusters using different VLANs for their Corosync traffic.

Optimize Your Virtual Infrastructure

Building a robust Proxmox cluster is the first step toward achieving professional-grade high availability and seamless resource management. By implementing a dedicated Corosync network and a quorum device, you ensure that your virtualized workloads remain resilient against hardware failures and network volatility.