Objectif
Ajouter proprement un nouveau nœud Proxmox VE à un cluster existant sans provoquer de conflit de configuration ou de quorum, en vérifiant versions, noms, réseau Corosync, stockage et absence de VM locales à conserver avant l’opération de join.
Prérequis
- Versions Proxmox VE compatibles et dépôts/paquets mis à jour selon la politique du cluster.
- Hostname unique, résolution DNS ou /etc/hosts correcte et synchronisation horaire fiable.
- Réseau Corosync dédié ou suffisamment isolé, avec latence faible et adresses statiques.
- Nouveau nœud sans VM/CT locales à conserver et sans configuration cluster précédente résiduelle.
- Accès root, mot de passe/empreinte du cluster, sauvegarde des configurations utiles et fenêtre de changement.
Procédure pas à pas
Contrôler la santé du cluster existant
Avant d’ajouter un membre, vérifiez que le cluster actuel est quorate, que tous les nœuds attendus sont visibles et qu’aucune erreur Corosync ou pmxcfs n’est en cours. Ajouter un nœud pendant un incident complique le diagnostic. Relevez le nom du cluster, le nombre de votes, les adresses de lien et l’état des services HA si utilisés.
pvecm statuspvecm nodessystemctl --no-pager --full status corosync pve-cluster- Le cluster est quorate et tous les membres existants sont stables.
- Aucun incident Corosync/pmxcfs n’est ignoré avant le join.
Préparer le nouveau nœud
Sur le serveur à ajouter, vérifiez le hostname, /etc/hosts, les interfaces, la date et les versions. Le nom doit être unique et résolu de manière identique depuis tous les membres. Évitez de modifier le nom après l’intégration. Vérifiez aussi que le nœud ne possède aucun guest local important, car les configurations /etc/pve seront ensuite gérées par le cluster.
hostnamectlcat /etc/hostsip -br addrpveversion -vtimedatectl- Le hostname et les IP sont définitifs.
- Le nœud est propre, à jour et sans workload local à préserver.
Vérifier la connectivité Corosync
Testez la communication entre le nouveau nœud et les membres existants sur le réseau choisi pour Corosync. Une perte de paquets ou une latence fluctuante peut provoquer des pertes de quorum et du fencing. Si plusieurs liens Corosync sont prévus, documentez leur priorité et leur chemin physique. Évitez un réseau dépendant d’un seul switch sans redondance si la disponibilité l’exige.
ping -c 20 <CLUSTER-NODE-IP>ip route get <CLUSTER-NODE-IP>- Le trafic emprunte le réseau prévu avec une latence stable et sans perte.
Sauvegarder la configuration utile du nouveau nœud
Conservez hors /etc/pve les éléments locaux qui devront être reproduits après intégration : configuration réseau, dépôts, paramètres matériel, fichiers spécifiques de stockage ou scripts. Le join synchronise la configuration de cluster et peut rendre inutiles ou écraser certaines définitions locales. Cette sauvegarde sert de référence, pas à recopier aveuglément d’anciens fichiers dans pmxcfs.
cp -a /etc/network/interfaces /root/interfaces.before-clusterpvesm status- La configuration locale nécessaire est sauvegardée et les stockages attendus sont inventoriés.
Ajouter le nœud au cluster
Depuis le nouveau nœud, utilisez l’adresse d’un membre existant pour rejoindre le cluster avec pvecm add. Vérifiez attentivement l’empreinte présentée et fournissez les informations demandées. Si un réseau Corosync spécifique doit être utilisé, appliquez les options conformes à votre version Proxmox plutôt que de laisser le trafic partir par une interface non prévue.
pvecm add <IP-NODE-EXISTANT>- La commande termine sans erreur et le nœud apparaît dans le cluster.
- Le certificat et la configuration de cluster sont synchronisés.
Valider pmxcfs et le quorum après join
Contrôlez immédiatement pvecm status, la liste des nœuds et le montage /etc/pve. pmxcfs doit être en lecture/écriture lorsque le cluster possède le quorum. Vérifiez que les fichiers de configuration distribués sont présents et que le nouveau membre reçoit les changements. Une perte de quorum ou un /etc/pve en lecture seule doit être traitée avant toute création de VM.
pvecm statuspvecm nodesmount | grep /etc/pvels -la /etc/pve/nodes- Le nouveau membre est Online et le cluster reste quorate.
- /etc/pve reflète les nœuds du cluster.
Vérifier les stockages et réseaux cluster
Comparez les définitions de stockage et de bridge. Un stockage marqué pour tous les nœuds n’est pas forcément réellement accessible depuis le nouveau serveur. Vérifiez chaque storage shared, NFS, Ceph
pvesm statusip -br link- Seuls les stockages réellement accessibles sont actifs sur le nouveau nœud.
- Les bridges utilisés par les VM existent avec les bons VLAN.
Tester une migration non critique
Après validation du réseau et du stockage, migrez une VM ou un CT pilote adapté à votre architecture. Si les disques sont locaux, Proxmox devra copier les données ; si le stockage est partagé, la migration peut être plus rapide. Vérifiez aussi la compatibilité CPU pour les migrations live et le mapping des bridges.
qm migrate <VMID> <TARGET-NODE> --onlinepct migrate <CTID> <TARGET-NODE> --restart- Le workload pilote démarre et communique correctement sur le nouveau nœud.
Intégrer le nœud à la supervision et à la HA
Ajoutez le serveur aux sauvegardes, à la supervision, aux alertes matérielles et, si utilisé, aux règles HA. Ne placez pas immédiatement des services critiques en HA avant d’avoir testé stockage, réseau et comportement du watchdog. Documentez aussi les liens Corosync et les ports switch afin de pouvoir diagnostiquer une future perte de quorum.
pvecm status- Le nouveau nœud est exploitable et supervisé avec les mêmes standards que les autres membres.
Validation
La procédure est validée lorsque :
- Le cluster reste quorate et tous les nœuds attendus apparaissent Online.
- pmxcfs est fonctionnel et /etc/pve contient la configuration distribuée.
- Les stockages et bridges requis sont réellement accessibles depuis le nouveau nœud.
- Une migration pilote fonctionne et la supervision/backup du nœud est active.
Retour arrière
- Si le join échoue avant intégration complète, conserver les logs et corriger réseau, nommage ou versions avant une nouvelle tentative.
- Si le nœud doit être retiré après intégration, suivre la procédure officielle de suppression de nœud ; Proxmox recommande la réinstallation pour remettre proprement un nœud en mode standalone.
- Ne copiez pas manuellement une ancienne base pmxcfs ou des clés cluster pour annuler un join sans procédure de récupération documentée.
- Migrer ou arrêter les workloads du nœud avant toute suppression du cluster.
Dépannage / erreurs fréquentes
- Cluster non quorate après ajout : vérifier Corosync, latence, votes et adresses de lien avant toute action sur les VM.
- Nœud absent ou Offline : contrôler hostname, résolution, heure, firewall et services corosync/pve-cluster.
- Stockage visible mais inaccessible : vérifier la restriction de nœuds et la connectivité réelle vers NFS/iSCSI/Ceph.
- Migration refusée : contrôler bridge cible, stockage, CPU et configuration du guest.
- Configuration locale disparue après join : restaurer uniquement les éléments non cluster depuis la sauvegarde de référence, jamais /etc/pve en bloc.