Cluster Incus : haute disponibilité multi-nœuds

Un cluster Incus regroupe plusieurs serveurs sous une seule API : les instances se répartissent sur les nœuds, la configuration est répliquée dans une base distribuée, et un nœud peut tomber sans arrêter le service. Ce guide monte un cluster pas à pas : exposer l'API, activer le clustering, ajouter des nœuds par token, et surtout comprendre le quorum à 3 nœuds et la récupération après panne. Monté et testé sur un cluster 3 nœuds Incus 7.0 (placement --target, migration d'instance, evacuate/restore). Pour qui vise la haute disponibilité.

Ce que vous allez apprendre

• Exposer l'API et activer le clustering.
• Ajouter un nœud via un token de join.
• Comprendre le quorum (pourquoi 3 nœuds).
• Maintenir et récupérer un cluster.

Prérequis

• Des serveurs Incus fraîchement installés, aux versions identiques (un écart de version fait échouer le join).
• Le port 8443 ouvert entre les nœuds.
• Les horloges synchronisées (NTP) : un décalage casse la réplication.

Exposer l'API et activer le clustering

Par défaut, Incus n'écoute que sur son socket local. Le clustering exige d'exposer l'API sur le réseau avec core.https_address, sinon l'activation échoue sur This server is not available on the network :

incus config set core.https_address=:8443

La voie recommandée pour un cluster neuf est incus admin init, en répondant yes à « use Incus clustering ». Sur un serveur déjà initialisé, on transforme le démon en cluster à un seul nœud :

incus cluster enable node1
incus cluster list

+-------+-----------------------------+-----------------+--------+-------------------+
| NAME  |             URL             |      ROLES      | STATUS |      MESSAGE      |
+-------+-----------------------------+-----------------+--------+-------------------+
| node1 | https://192.168.10.184:8443 | database-leader | ONLINE | Fully operational |
|       |                             | database        |        |                   |
+-------+-----------------------------+-----------------+--------+-------------------+

Le premier membre porte les rôles database-leader et database : c'est lui qui héberge la base distribuée pour l'instant.

Ajouter un nœud

L'ajout se fait en deux temps, avec un token à usage unique.

1. Sur un membre du cluster, générez le token pour le futur nœud :

   incus cluster add node2
   # Member node2 join token: eyJzZXJ2ZXJf...

   Le token embarque l'adresse des membres, un secret et l'empreinte du certificat du cluster. Son mécanisme est détaillé dans le guide Accès distant et UI.

2. Sur le nouveau nœud, lancez incus admin init en répondant yes à « joining an existing cluster », puis collez le token. En automatisé, avec Ansible ou cloud-init, un preseed fait le join sans interaction. Il faut d'abord exposer l'API du nœud joignant, sinon le join échoue :

   # sur le nœud joignant, AVANT le preseed
   incus config set core.https_address=192.168.10.50:8443

   # preseed.yaml sur node2 (192.168.10.50)
   cluster:
     enabled: true
     server_address: 192.168.10.50:8443
     cluster_token: eyJzZXJ2ZXJf...
     member_config:
       - entity: storage-pool
         name: default
         key: source
         value: ""

   cat preseed.yaml | incus admin init --preseed

Vécu : le preseed qui réussit sans rien faire (exit 0, aucun join)

Trois pièges m'ont bloqué en montant un cluster 3 nœuds réel, tous silencieux :

• core.https_address doit être posé sur le nœud joignant avant le preseed. Sans lui, le join s'arrête sur Cannot use wildcard core.https_address "" for cluster.https_address. Le server_address du preseed ne le pose pas tout seul.
• Un nœud déjà initialisé en autonome ne peut pas rejoindre. Si le serveur a déjà tourné incus admin init --auto, le preseed renvoie exit 0 sans rien faire, et le membre n'apparaît jamais dans incus cluster list. Il faut le remettre à neuf : systemctl stop incus.service incus.socket, rm -rf /var/lib/incus, redémarrer, puis rejouer le join.
• Le token s'affiche sur la ligne suivante du label. incus cluster add node2 imprime Member node2 join token: puis le token sur la ligne d'après. Un script qui parse la ligne du label récupère une chaîne vide, et le join échoue sur ServerName is required. Récupérez la ligne qui commence par eyJ.

Autre piège fréquent : un token expiré. Un délai trop long entre incus cluster add et le join, ou un redémarrage du serveur entre les deux, l'invalide avec No matching cluster join operation found. Consommez-le immédiatement, régénérez-le au besoin, et réglez sa durée de vie par cluster.join_token_expiry.

Le member_config fournit les valeurs spécifiques au nœud, comme la source du pool de stockage : chaque serveur garde ses disques locaux tout en partageant la configuration.

Le quorum : pourquoi 3 nœuds

C'est le point à comprendre avant de viser la haute disponibilité. La base distribuée d'Incus (Cowsql, un fork de dqlite) est répliquée par l'algorithme Raft, qui a besoin d'une majorité de votants pour fonctionner.

• Par défaut, 3 membres sont votants (cluster.max_voters=3).
• La base reste disponible tant qu'une majorité est en ligne. Avec 3 votants, le cluster survit à la perte d'un nœud.
• Avec seulement 2 nœuds, il n'y a aucune tolérance de panne réelle (perdre un votant fait perdre la majorité).

La conclusion est nette : un vrai cluster HA commence à 3 nœuds. En dessous, c'est du confort de gestion, pas de la haute disponibilité.

Une fois node2 et node3 joints, incus cluster list montre les trois membres ONLINE. Le rôle database-leader reste sur node1, les deux autres portent database : les trois forment le quorum Raft à 3 voix.

+-------+-----------------------------+-----------------+--------+-------------------+
| NAME  |             URL             |      ROLES      | STATUS |      MESSAGE      |
+-------+-----------------------------+-----------------+--------+-------------------+
| node1 | https://192.168.10.184:8443 | database-leader | ONLINE | Fully operational |
|       |                             | database        |        |                   |
+-------+-----------------------------+-----------------+--------+-------------------+
| node2 | https://192.168.10.50:8443  | database        | ONLINE | Fully operational |
+-------+-----------------------------+-----------------+--------+-------------------+
| node3 | https://192.168.10.199:8443 | database        | ONLINE | Fully operational |
+-------+-----------------------------+-----------------+--------+-------------------+

Placer les instances

Sans précision, Incus place une nouvelle instance sur le membre qui en a le moins. On cible un nœud précis avec --target :

incus launch images:debian/13 web1 --target node2
incus launch images:debian/13 web2 --target node3
incus launch images:debian/13 web3            # placement automatique
incus list -c ns4L   # la colonne LOCATION indique le nœud d'exécution

Sur le cluster de test, les deux premières instances atterrissent où on les envoie ; la troisième est placée automatiquement sur le nœud le moins chargé, ici node1 :

+------+---------+----------------------+----------+
| NAME |  STATE  |         IPV4         | LOCATION |
+------+---------+----------------------+----------+
| web1 | RUNNING | 10.107.24.164 (eth0) | node2    |
| web2 | RUNNING | 10.107.24.252 (eth0) | node3    |
| web3 | RUNNING | 10.107.24.100 (eth0) | node1    |
+------+---------+----------------------+----------+

Maintenance et récupération

Pour intervenir sur un nœud, on l'évacue (ses instances migrent ou s'arrêtent), puis on le restaure :

incus cluster evacuate node2
# ... maintenance ...
incus cluster restore node2

Sur le cluster de test, évacuer node2 migre web1 vers node1 : Incus stoppe l'instance, la déplace, puis marque le nœud EVACUATED. Le membre reste dans le cluster mais n'accepte plus d'instances :

Evacuating cluster member: Stopping "web1" ... Migrating "web1" to "node1"

+-------+-----------------------------+-----------------+-----------+--------------------------------+
| NAME  |             URL             |      ROLES      |  STATUS   |            MESSAGE             |
+-------+-----------------------------+-----------------+-----------+--------------------------------+
| node2 | https://192.168.10.50:8443  | database        | EVACUATED | Unavailable due to maintenance |
+-------+-----------------------------+-----------------+-----------+--------------------------------+

Le restore fait le chemin inverse : web1 remigre vers node2, qui repasse ONLINE. Le comportement d'évacuation se règle par instance via cluster.evacuate : migrate à chaud si le stockage le permet, sinon stop ou force-stop.

Pour retirer définitivement un membre (ajoutez --force s'il est injoignable) :

incus cluster remove node2

Récupérer après une perte de quorum

Si vous perdez la majorité, par exemple 2 nœuds sur 3, le cluster devient indisponible. La récupération reste possible tant qu'un membre database survit :

L'ordre de ces quatre étapes n'est pas indifférent : le leader redémarre en premier, sinon les autres ne le trouvent pas.

1. incus admin cluster list-database, pour repérer les survivants ;
2. systemctl stop incus.service incus.socket sur tous les survivants ;
3. sur le nouveau leader : incus admin cluster recover-from-quorum-loss ;
4. redémarrer incus.socket puis incus.service, leader d'abord.

Aucune donnée n'est supprimée de la base.

À retenir

• Le clustering exige d'abord d'exposer l'API : incus config set core.https_address=:8443.
• On active avec incus admin init (recommandé) ou incus cluster enable (single-node).
• Un nœud s'ajoute via incus cluster add (token) puis un join sur le nouveau serveur ; le token est à consommer vite.
• La HA réelle demande 3 nœuds (quorum Raft/Cowsql) ; 2 nœuds ne tolèrent aucune panne.
• Versions identiques + NTP obligatoires ; récupération via recover-from-quorum-loss.

FAQ : questions fréquentes sur le cluster Incus

Combien de nœuds faut-il pour un cluster Incus en haute disponibilité ?

Trois nœuds minimum. La base distribuée d'Incus (Cowsql, un fork de dqlite) est répliquée par l'algorithme Raft, qui a besoin d'une majorité de votants. Par défaut, trois membres sont votants : le cluster survit alors à la perte d'un nœud.

Comment ajouter un nœud à un cluster Incus ?

En deux temps. Sur un membre existant, on génère un token à usage unique avec incus cluster add nom-du-noeud. Sur le nouveau serveur, on lance incus admin init en répondant oui à joining an existing cluster et en collant le token, ou on passe un preseed YAML avec la section cluster.

Pourquoi mon join de cluster Incus échoue avec No matching cluster join operation ?

Parce que le token de join a expiré. C'est le piège classique : un délai trop long entre incus cluster add et le join, ou un redémarrage du serveur entre les deux, invalide le token. Il faut le consommer immédiatement et le régénérer au besoin. Sa durée de vie se règle via cluster.join_token_expiry.

Comment récupérer un cluster Incus après une perte de quorum ?

Tant qu'un membre database survit, la récupération est possible. On identifie les survivants avec incus admin cluster list-database, on arrête incus.service et incus.

Pour aller plus loin

• Workers et nœuds distants : étendre ce cluster au-delà du réseau local.
• Stockage partagé CephFS : donner aux instances un volume que tous les nœuds voient.
• Réseau OVN : VPC et load balancers : bâtir des réseaux virtuels par-dessus ce cluster.

×

📖 Voir la documentation →