How to Add a Node to an Existing Proxmox Cluster
Why Have a Proxmox Cluster?
Creating a Proxmox cluster offers significant advantages that enhance the management, performance, and reliability of your virtualized environment. These advantages include:
- High Availability: Ensures continuous service by automatically migrating VMs if a node fails.
- Load Balancing: Distributes workloads across multiple nodes for optimal resource utilization.
- Scalability: Easily add nodes to accommodate growing workloads without downtime.
- Simplified Management: Centralizes control of all nodes and VMs through a single interface.
- Improved Resource Allocation: Enables shared access to storage and network resources.
- Enhanced Performance: Achieves better responsiveness and throughput by distributing workloads.
- Fault Tolerance: Protects data and applications by maintaining operations even during hardware failures.
- Simplified Backup and Disaster Recovery: Facilitates consistent backups and quick restoration of services in case of failure.
For my use case, I want to use it for high availability for one of my VMs when I set it up.
This guide will walk you through adding a new node to an existing Proxmox cluster, with detailed steps and best practices for seamless integration. I'll be using the web interface to set this up.
Assumptions
- This guide assumes you have an existing cluster set up
Before you start...
You will need 3 nodes to create the cluster though it is entirely possible to set it up with 2 nodes.
You can set up a Proxmox cluster with just two nodes, but it relies on something called quorum to keep running smoothly. In a two-node cluster, each node has one vote, so if one node goes offline, there’s no longer a majority. This causes the cluster to switch to a read-only mode, making it difficult to perform maintenance or keep everything working normally when one node is down.
For example, if one of your nodes crashes, the cluster may lose quorum, triggering system errors and causing your VMs to stop functioning until quorum is restored. To address this, you can run a specific command in the terminal to regain functionality.
pvecm expected 1
While you can set up a cluster with only 2 nodes, it's not recommended because you won't fully benefit from the features that a 3-node setup provides.
Prerequisites
Before you begin, ensure the following:
- Matching Proxmox VE Versions: The new node should have the same Proxmox VE version as the existing nodes in the cluster. You can check the version by running:
pveversion

Or simply just looking at the top of the page in the GUI interface

- Network Configuration:
Ensure that the new node and the cluster nodes are on the same network.
- Firewall and Ports:
Make sure the required ports are open. Proxmox uses ports like 8006
for the web interface and 22
for SSH. - Usually on by default
- Unique Hostname and IP: The new node should have a unique hostname and static IP address within the same subnet as the cluster.
Let's begin!
Prepare the New Node
Start by setting up the new node with Proxmox VE, including network configuration and storage setup.
Install Proxmox VE: Follow the official Proxmox installation guide, ensuring all basic configurations (like time zone and locale) are correct.
Assign Hostname and IP: Assign a unique hostname and static IP address to the new node to avoid conflicts.

Join the New Node to the Cluster
On the master node of your existing Proxmox cluster, retrieve the join information.
- Log into the Master Node
Navigate to Datacenter --> Cluster--> Click on Join Information, then the "Copy Information" button
- Run the Join Command on the New Node
Go to Cluster and click "Join Cluster"

- Click Cluster Join and paste the key
You will need to enter the root password of the master node and select the cluster network

If successful, the new node will join the cluster and synchronize with the master node.

Verify the Node Has Joined the Cluster
Refresh your browser and re-login into any node. You should now see all the nodes


Verify Node Connectivity:
Use the Proxmox web interface to check if the new node is visible in the cluster. Go to Datacenter > Cluster to confirm the node is listed.

and that's it, you've successfully connected a node to a cluster.
Now after you set up your cluster, there are things you might want to set up to set up. These include below:
- Network: Match cluster network settings, including VLANs and firewall rules.
- Storage: Add shared storage (if used) and configure local storage as needed.
- Resource Pooling & Permissions: Add node to resource pools; sync user permissions.
- High Availability (HA): Add node to HA groups for failover.
- Backup: Include node in backup schedules if hosting VMs/containers.
- VM Networking: Align virtual network settings for seamless VM connectivity.
- Monitoring & Alerts: Ensure node is included in cluster monitoring and alerts.
Will not cover this here but you can test the below which I'll cover in another article.
Enable High Availability (Optional)
If your Proxmox cluster uses High Availability (HA), configure HA for the new node.
- Configure HA Groups:
- Go to Datacenter > HA > Groups in the web interface, and add the new node to the desired HA group.
- Set Up HA Resources:
- Define VMs or containers on the new node to participate in HA.
Testing and Troubleshooting
After adding the node, test the setup:
- Test Node Communication:
- Ping other nodes in the cluster from the new node to confirm network connectivity.
- Test VM Migration:
- Try migrating a test VM to the new node and back to verify VM migration functionality.


- Troubleshoot Common Issues:
- Network Issues: Ensure that cluster traffic can flow between nodes by verifying firewall and routing settings.
- Cluster Sync Issues: Run
pvecm status
on the new node to check sync status. If it’s not syncing, you may need to verify SSH keys and firewall rules.
Final Thoughts
Adding a new node to a Proxmox cluster is simple and significantly boosts scalability and redundancy. This guide will help you integrate the new node smoothly, expanding your cluster’s capacity and resilience. Be sure to monitor the new node regularly to maintain stability and performance across your enhanced cluster.
Found this article useful? Why not buy Phi a coffee to show your appreciation?