Aller au contenu principal

Le plan de contrôle dans votre shell : piloter un cluster Zaris depuis PowerShell

· 12 minutes de lecture
Clustron Team
Clustron Team
Ingénierie des systèmes distribués

Provisionnement et pilotage d'un cluster Zaris depuis PowerShell

L'essentiel de ce que vous lisez sur un store de données concerne le chemin de données — lectures, écritures, protocole de communication, sa rapidité. Mais avant que tout cela ne compte, quelqu'un doit monter la chose : décider combien de partitions elle a, combien de copies de chacune, où vivent les ports, la démarrer, confirmer qu'elle est montée en bonne santé et la surveiller pendant qu'elle tourne. C'est le plan de contrôle, et dans Zaris il vit dans PowerShell.

Ceci est une visite guidée de l'opérateur au jour zéro. Nous allons créer un espace de travail, provisionner un store, le démarrer, puis relire son état en direct — le tout depuis le module AdminShell. Aucune console web requise, rien édité à la main. Et parce que tout l'intérêt d'une histoire d'opérateur est la confiance, nous serons explicites sur les choix que New-ZrStore met devant vous et sur ce que chacun coûte réellement.

Deux shells, deux plans​

Zaris livre sa surface en ligne de commande sous la forme de deux modules PowerShell distincts, et la séparation n'est pas cosmétique — elle reflète les deux plans du système :

  • AdminShell est le plan de contrôle. Ses cmdlets provisionnent, démarrent, arrêtent, inspectent et mettent à l'échelle les stores. Elles parlent au Management Service de Zaris (le « manager »), pas directement aux nœuds de données. Ce sont les verbes New-ZrStore, Get-ZrNode, Watch-ZrStoreMetrics.
  • ClientShell est le plan de données. Ses cmdlets — Connect-ZrStore, Get-ZrItem, Set-ZrItem — ouvrent une connexion directe vers les nœuds du store et déplacent des données clé-valeur. C'est la surface qu'utilise une application, et le sujet de l'article sur les chaînes de connexion.

Un opérateur qui monte un cluster vit presque entièrement dans AdminShell. Le manager auquel il parle est le composant qui connaît la forme désirée de chaque store et pilote les processus réels vers elle. La première chose à faire est donc d'indiquer à votre shell à quels managers parler.

Étape 0 — un espace de travail à cibler​

Un espace de travail est un ensemble nommé de managers que les cmdlets admin ciblent, persisté sous ~/.clustron pour qu'il survive aux sessions. Vous en créez un une fois et vous y basculez chaque fois que vous ouvrez un shell :

# Create a workspace pointing at the cluster's managers (does not activate it)
New-ZrWorkspace -Name "prod" -Managers "10.0.0.10:7801","10.0.0.11:7801"

# Make it the active target for this and future sessions
Use-ZrWorkspace prod

Chaque point de terminaison manager est un observateur d'un cluster — listez-les tous et les cmdlets admin agrègent l'état sur l'ensemble du cluster plutôt que sur ce qu'une machine se trouve connaître. Si votre cluster a la sécurité activée, enregistrez un jeton admin sur l'espace de travail (-Token) ou authentifiez la session avec Connect-ZrManager -Credential (Get-Credential) -Force, qui échange un nom d'utilisateur et un mot de passe contre un jeton de session. (Connect-ZrManager est l'ancienne connexion ad hoc et fonctionne toujours, mais les cmdlets d'espace de travail sont le chemin actuel — ce sont ce à quoi correspondent les espaces de travail enregistrés de la console web.)

Une bifurcation honnête du chemin ici : la visite guidée ci-dessous est le modèle superviseur, où chaque manager fork et possède ses processus Zaris locaux — le déploiement natif/Windows. Si vos nœuds tournent plutôt sous un orchestrateur comme Kubernetes (le modèle d'attachement), le manager ne crée pas de processus ; vous définissez le store avec votre orchestrateur et vous l'adoptez avec Register-ZrStore au lieu de New-ZrStore. New-ZrStore détecte un manager en mode attachement et vous le signale plutôt que d'échouer au fond de la pile.

Étape 1 — provisionner le store​

C'est la cmdlet qui porte les vraies décisions. La forme de production minimale est courte :

New-ZrStore -Name "orders" `
            -ReplicationFactor 2 `
            -BaseClusterPort 7811 `
            -BaseClientPort 7861

Cela crée un store nommé orders sur chaque machine de l'espace de travail, avec deux copies de chaque partition. Quatre paramètres portent le poids, soyons donc précis sur chacun.

-ReplicationFactor est le nombre total de copies de chaque partition — primaire plus réplicas. Pour la production, il doit être au plus égal au nombre de machines, de sorte que chaque copie atterrisse sur une machine différente ; c'est ce qui en fait de la tolérance aux pannes plutôt qu'une décoration. Sur une machine de dev unique, la contrainte est assouplie avec un avertissement — les réplicas partageront une machine, ce qui convient pour les tests et ne vous apporte rien lors d'une vraie panne. La cmdlet le dit à voix haute plutôt que de vous laisser croire autre chose.

-PartitionsPerNode vaut 1 par défaut, ce qui est la topologie de production. Le nombre total de partitions est dérivé de l'appartenance en direct du cluster — PartitionsPerNode × nœuds en direct — et recalculé à chaque changement d'appartenance, ce n'est donc pas un nombre que vous figez à la création. Vous le montez au-dessus de 1 surtout pour les tests locaux, où vous voulez observer le comportement conscient des partitions (routage de segment, rééquilibrage à la montée en charge) sur une machine unique sans monter un rack.

-BaseClusterPort / -BaseClientPort sont les premiers ports de deux plages : le port interne de gossip/cluster et le port exposé aux clients, incrémentés une fois par processus sur chaque machine. La cmdlet vérifie que les deux plages ne se chevauchent pas et refuse de créer un store qui entrerait en collision avec lui-même — une petite garde qui évite un échec déroutant au premier démarrage.

Il y en a trois autres qui valent la peine d'être connues parce qu'elles encodent un véritable compromis de durabilité :

New-ZrStore -Name "orders" -ReplicationFactor 3 `
            -BaseClusterPort 7811 -BaseClientPort 7861 `
            -ReplicationMode Sync `
            -WriteQuorumPolicy Majority `
            -AllowReplicaReads
  • -ReplicationMode vaut Async par défaut : le primaire écrit localement et retourne immédiatement, répliquant en arrière-plan. C'est l'option la plus rapide et le bon défaut pour un cache — mais soyez lucide : une écriture acquittée sous Async n'est pas encore garantie d'être sur un réplica. Choisissez Sync et le primaire attend l'acquittement du réplica avant de renvoyer Ok, échangeant de la latence contre de la durabilité.
  • -WriteQuorumPolicy ne mord que sous Sync : All (chaque réplica doit acquitter), Majority (floor(RF/2)+1 doivent acquitter), ou BestEffort (les échecs sont journalisés mais ne font pas échouer l'écriture).
  • -AllowReplicaReads laisse les clients lire depuis les nœuds réplicas pour répartir la charge de lecture — avec l'avertissement honnête qu'une lecture de réplica peut renvoyer des données légèrement périmées, car un réplica peut traîner derrière le primaire. Laissez-le désactivé quand vous avez besoin de lire vos propres écritures ; activez-le quand vous préférez le débit et pouvez tolérer le retard.

Remarquez ce que les défauts disent de la posture de Zaris : Async + lecture-depuis-le-primaire est un cache rapide et correct par défaut. Les boutons de durabilité sont là quand vous en avez besoin, nommés clairement, chacun avec un coût que vous pouvez voir.

Étape 2 — le démarrer, et confirmer qu'il est monté​

Créer un store définit sa forme ; cela n'exécute pas les processus. Start-ZrStore énumère les instances du store sur chaque manager et les démarre, en rapportant le succès ou l'échec par instance :

Start-ZrStore -Name "orders"

Voici maintenant la partie qui distingue un opérateur de quelqu'un qui a lancé une commande et espéré. Get-ZrStore relit l'état en direct du store depuis les managers — statut global, temps de disponibilité, et l'état d'exécution de chaque nœud :

Get-ZrStore orders
Store   : orders
Status  : Running
Uptime  : 2h 14m  (since 2026-10-03 09:41:12)

Nodes (4)
───────────────────────────────────────────
  ● 10.0.0.10-n0   10.0.0.10:7861   Running   up 2h 14m
  ● 10.0.0.10-n1   10.0.0.10:7862   Running   up 2h 14m
  ● 10.0.0.11-n0   10.0.0.11:7861   Running   up 2h 14m
  ● 10.0.0.11-n1   10.0.0.11:7862   Running   up 2h 14m
───────────────────────────────────────────
  Running: 4   Stopped: 0

Le statut du store est une synthèse : Running quand chaque nœud est actif, Stopped quand tous sont en panne, et Partial quand certains sont actifs et d'autres non — ce qui est exactement l'état que vous voulez révélé bruyamment, car un store Partial est un store qui a démarré de façon inégale. Le temps de disponibilité est délibérément le moment de formation du cluster rapporté par le cœur — le démarrage de nœud le plus précoce qui a survécu au changement — et non le plus vieux processus actuellement en cours, de sorte qu'un store qui sert depuis des heures ne rapporte pas à tort « quelques minutes » simplement parce qu'un nœud a redémarré.

Pour la couche en dessous, Get-ZrNode montre les rôles et la carte de partitions :

Get-ZrNode orders
Nodes (4)
─────────────────────────────────────────────────────────────────────────
  ● 10.0.0.10-n0   10.0.0.10:7861   Running   Primary   v7
  ● 10.0.0.10-n1   10.0.0.10:7862   Running   Replica   v7
  ● 10.0.0.11-n0   10.0.0.11:7861   Running   Primary   v7
  ● 10.0.0.11-n1   10.0.0.11:7862   Running   Replica   v7

La colonne Primary/Replica indique qui possède actuellement chaque partition, et le v7 est la version de la carte de partitions — le numéro de génération de la carte de propriété. Lorsque chaque nœud s'accorde sur la même version de carte, la propriété a convergé ; un nœud coincé sur une version plus ancienne est un nœud qui n'a pas rattrapé le dernier rebrassage. Demander le détail d'un nœud unique (Get-ZrNode orders 10.0.0.10-n0) développe cela en les identifiants exacts des partitions primaires et réplicas qu'il détient et le moment où son rôle a changé pour la dernière fois — la vue que vous consultez quand un basculement vient d'avoir lieu et que vous voulez savoir où la propriété a atterri.

Étape 3 — le surveiller pendant qu'il tourne​

Un instantané vous dit que le store est actif. Une vue en direct vous dit ce qu'il fait. Watch-ZrStoreMetrics interroge les managers et redessine une table par nœud à intervalle régulier jusqu'à ce que vous l'annuliez :

Watch-ZrStoreMetrics -StoreName orders -RefreshSec 2

Elle dispose d'abord les compteurs du quotidien — taux de requêtes, gets, puts, deletes, nombre d'éléments, utilisation mémoire — et repousse les diagnostics avancés de réplication et de synchronisation vers le bas, de sorte que les nombres que vous vérifiez d'un coup d'œil sont en haut. Les compteurs d'erreurs passent au rouge dès que leur taux dépasse zéro ; le débit se teinte de vert lorsqu'il monte. Elle signale aussi les changements de rôle en ligne : si un basculement fait passer un primaire à réplica pendant que vous regardez, une ligne [ROLE CHANGE] s'affiche avec un horodatage — le signal en direct qu'une partition vient de changer de mains.

Un détail délibéré qui mérite d'être souligné, car c'est le genre de chose qui rend un outil utilisable à 2 h du matin : la vue récupère la trame suivante avant d'effacer l'écran, et une interrogation vide transitoire conserve la dernière bonne trame plutôt que de tout effacer. Vous obtenez une table stable, pas une table clignotante, quelle que soit la lenteur d'un manager à répondre.

Pour compléter l'ensemble en lecture seule, Get-ZrInfo rapporte la version installée, les répertoires d'installation et de données, les deux emplacements de module, le runtime hôte — et sonde chaque manager pour sa joignabilité. Un manager sécurisé qui répond 401 est rapporté comme joignable mais nécessitant une authentification, pas comme « en panne », de sorte que vous pouvez distinguer d'un coup d'œil un problème réseau d'un jeton manquant.

Étape 4 — arrêter, et la forme sous-jacente à tout​

Mettre un store à l'arrêt est le miroir du cycle de vie de son démarrage :

# Fast whole-store stop (default: a hard kill, since every node goes down together)
Stop-ZrStore -Name orders

# Per-node drain and clean cluster-leave
Stop-ZrStore -Name orders -Graceful

Le défaut est une mise à mort dure et rapide, qui est le bon comportement quand le store entier descend d'un coup — il n'y a pas de cluster survivant à qui un nœud partant puisse passer la main, donc drainer n'apporte rien. Utilisez -Graceful quand vous voulez que chaque nœud draine et quitte le cluster proprement, ce qui importe quand vous arrêtez un sous-ensemble plutôt que l'ensemble.

Sous chaque cmdlet de cet article se cache une seule idée : un store Zaris a une forme désirée — une définition canonique des serveurs et partitions qu'il est censé avoir — et le manager tourne sous un modèle superviseur qui pilote en continu les processus en direct vers elle. New-ZrStore écrit cette forme ; Start-ZrStore la réalise ; Get-ZrStore et Get-ZrNode rapportent à quel point la réalité en est proche. C'est ce même modèle qui fait du redimensionnement élastique une ligne unique plutôt qu'un runbook — changer la forme désirée avec Add-ZrServer / Remove-ZrServer et laisser le superviseur réconcilier, ce qui est sa propre histoire de mise à l'échelle élastique.

Le résumé honnête​

Le cycle de vie complet du jour zéro, ce sont cinq commandes et deux lectures :

New-ZrWorkspace -Name prod -Managers "10.0.0.10:7801","10.0.0.11:7801"
Use-ZrWorkspace prod
New-ZrStore -Name orders -ReplicationFactor 2 -BaseClusterPort 7811 -BaseClientPort 7861
Start-ZrStore -Name orders
Get-ZrStore  orders          # is it Running, and are all nodes up?
Get-ZrNode   orders          # who owns what, and did the map converge?
Watch-ZrStoreMetrics -StoreName orders -RefreshSec 2   # what's it doing now?

Ce qui fait de ceci un plan de contrôle et pas seulement un tas de scripts, c'est que les cmdlets rapportent une vérité en direct, agrégée — non pas ce que vous avez demandé, mais ce que le cluster est réellement — et que les choix aux conséquences réelles sont nommés en toutes lettres : facteur de réplication contre nombre de machines, Async contre Sync, lectures de réplica contre péremption. Montez un store, confirmez qu'il a convergé, et gardez-le à l'œil — le tout sans quitter le shell.