El plano de control en tu shell: gestionar un clúster de Zaris desde PowerShell
La mayor parte de lo que lees sobre un almacén de datos trata del camino de datos: lecturas, escrituras, el protocolo de cable, lo rápido que va. Pero antes de que nada de eso importe, alguien tiene que poner la cosa en pie: decidir cuántas particiones tiene, cuántas copias de cada una, dónde viven los puertos, arrancarla, confirmar que levantó sana y vigilarla mientras corre. Eso es el plano de control, y en Zaris vive en PowerShell.
Este es un recorrido de operador de día uno. Crearemos un workspace, aprovisionaremos un almacén, lo arrancaremos y luego volveremos a leer su estado en vivo, todo desde el módulo AdminShell. Sin consola web, nada editado a mano. Y como el sentido de una historia de operador es la confianza, seremos explícitos sobre las decisiones que New-ZrStore pone ante ti y lo que cada una cuesta de verdad.
Dos shells, dos planos
Zaris distribuye su superficie de línea de comandos como dos módulos de PowerShell distintos, y la división no es cosmética: refleja los dos planos del sistema:
- AdminShell es el plano de control. Sus cmdlets aprovisionan, arrancan, detienen, inspeccionan y escalan almacenes. Hablan con el Servicio de gestión de Zaris (el "manager"), no con los nodos de datos directamente. Son los verbos
New-ZrStore,Get-ZrNode,Watch-ZrStoreMetrics. - ClientShell es el plano de datos. Sus cmdlets —
Connect-ZrStore,Get-ZrItem,Set-ZrItem— abren una conexión directa a los nodos del almacén y mueven datos clave-valor. Esa es la superficie que usa una aplicación, y es el tema del artículo sobre cadenas de conexión.
Un operador que pone en pie un clúster vive casi por completo en AdminShell. El manager con el que habla es el componente que conoce la forma deseada de cada almacén y conduce los procesos reales hacia ella. Así que lo primero es decirle a tu shell con qué managers hablar.
Paso 0 — un workspace al que apuntar
Un workspace es un conjunto con nombre de managers a los que apuntan los cmdlets de administración, persistido bajo ~/.clustron para que sobreviva a las sesiones. Creas uno una vez y te cambias a él cada vez que abres 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
Cada endpoint de manager es un observador de un clúster: enuméralos todos y los cmdlets de administración agregan el estado de todo el clúster en vez de lo que sepa una máquina cualquiera. Si tu clúster tiene la seguridad activada, registra un token de administración en el workspace (-Token) o autentica la sesión con Connect-ZrManager -Credential (Get-Credential) -Force, que intercambia un nombre de usuario y una contraseña por un token de sesión. (Connect-ZrManager es la conexión ad-hoc más antigua y sigue funcionando, pero los cmdlets de workspace son el camino actual: son a lo que se corresponden los workspaces guardados de la consola web).
Una bifurcación honesta en el camino aquí: el recorrido de abajo es el modelo supervisor, donde cada manager bifurca y posee sus procesos locales de Zaris —el despliegue nativo/Windows—. Si tus nodos corren en cambio bajo un orquestador como Kubernetes (el modelo attach), el manager no crea procesos; defines el almacén con tu orquestador y lo adoptas con Register-ZrStore en vez de New-ZrStore. New-ZrStore detecta un manager en modo attach y te lo dice en vez de fallar en lo hondo de la pila.
Paso 1 — aprovisionar el almacén
Este es el cmdlet con las decisiones de verdad dentro. La forma mínima de producción es corta:
New-ZrStore -Name "orders" `
-ReplicationFactor 2 `
-BaseClusterPort 7811 `
-BaseClientPort 7861
Eso crea un almacén llamado orders en cada máquina del workspace, con dos copias de cada partición. Cuatro parámetros llevan el peso, así que seamos precisos con cada uno.
-ReplicationFactor es el número total de copias de cada partición: la primaria más las réplicas. Para producción debe ser como mucho el número de máquinas, de modo que cada copia caiga en una máquina distinta; eso es lo que lo convierte en tolerancia a fallos y no en decoración. En una única máquina de desarrollo la restricción se relaja con un aviso: las réplicas compartirán máquina, lo cual está bien para pruebas y no te compra nada en una caída real. El cmdlet lo dice en voz alta en vez de dejarte creer otra cosa.
-PartitionsPerNode vale 1 por defecto, que es la topología de producción. El recuento total de particiones se deriva de la pertenencia al clúster en vivo —PartitionsPerNode × nodos vivos— y se recalcula en cada cambio de pertenencia, así que no es un número que congeles en el momento de creación. Lo subes por encima de 1 principalmente para pruebas locales, donde quieres observar el comportamiento sensible a particiones (enrutamiento de segmentos, rebalanceo al escalar hacia fuera) en una única máquina sin montar un rack.
-BaseClusterPort / -BaseClientPort son los primeros puertos de dos rangos: el puerto interno de gossip/clúster y el puerto de cara al cliente, incrementados una vez por proceso en cada máquina. El cmdlet valida que los dos rangos no se solapen y se niega a crear un almacén que colisionaría consigo mismo: una pequeña protección que te ahorra un confuso fallo de primer arranque.
Hay tres más que vale la pena conocer porque codifican una verdadera compensación de durabilidad:
New-ZrStore -Name "orders" -ReplicationFactor 3 `
-BaseClusterPort 7811 -BaseClientPort 7861 `
-ReplicationMode Sync `
-WriteQuorumPolicy Majority `
-AllowReplicaReads
-ReplicationModeesAsyncpor defecto: la primaria escribe localmente y retorna de inmediato, replicando en segundo plano. Esa es la opción más rápida y el valor por defecto correcto para una caché, pero ten claro que una escritura confirmada bajoAsynctodavía no tiene garantía de estar en una réplica. EligeSyncy la primaria espera la confirmación de la réplica antes de devolverOk, cambiando latencia por durabilidad.-WriteQuorumPolicysolo muerde bajoSync:All(toda réplica debe confirmar),Majority(deben confirmarfloor(RF/2)+1) oBestEffort(los fallos se registran pero no hacen fallar la escritura).-AllowReplicaReadspermite a los clientes leer de nodos réplica para repartir la carga de lectura, con la advertencia honesta de que una lectura de réplica puede devolver datos ligeramente obsoletos, porque una réplica puede quedarse detrás de la primaria. Déjalo desactivado cuando necesites leer-tus-escrituras; actívalo cuando prefieras el rendimiento y puedas tolerar el retardo.
Fíjate en lo que dicen los valores por defecto sobre la postura de Zaris: Async + lectura desde la primaria es una caché rápida y correcta por defecto. Los mandos de durabilidad están ahí cuando los necesitas, nombrados sin rodeos, cada uno con un coste que puedes ver.
Paso 2 — arrancarlo, y confirmar que levantó
Crear un almacén define su forma; no ejecuta los procesos. Start-ZrStore enumera las instancias del almacén en cada manager y las arranca, informando del éxito o fallo por instancia:
Start-ZrStore -Name "orders"
Ahora la parte que separa a un operador de alguien que ejecutó un comando y confió. Get-ZrStore vuelve a leer el estado en vivo del almacén desde los managers: estado general, tiempo activo y el estado de ejecución de cada nodo:
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
El estado del almacén es un resumen: Running cuando cada nodo está arriba, Stopped cuando todos están abajo, y Partial cuando algunos están arriba y otros no, que es exactamente el estado que quieres que salga a la superficie a gritos, porque un almacén Partial es uno que arrancó de forma desigual. El tiempo activo es deliberadamente el tiempo de formación del clúster reportado por el núcleo —el arranque de nodo más temprano que sobrevivió al vaivén— no el proceso en ejecución más antiguo, de modo que un almacén que lleva horas sirviendo no reporte mal "unos minutos" solo porque un nodo se reinició.
Para la siguiente capa más abajo, Get-ZrNode muestra los roles y el mapa de particiones:
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 columna Primary/Replica es quién posee actualmente cada partición, y el v7 es la versión del mapa de particiones, el número de generación del mapa de propiedad. Cuando todos los nodos coinciden en la misma versión de mapa, la propiedad ha convergido; un nodo atascado en una versión más antigua es un nodo que no se ha puesto al día con el último reparto. Pedir detalle a un único nodo (Get-ZrNode orders 10.0.0.10-n0) expande esto hasta los IDs exactos de particiones primarias y réplicas que posee y cuándo cambió su rol por última vez: la vista a la que recurres cuando acaba de ocurrir un failover y quieres saber dónde aterrizó la propiedad.
Paso 3 — vigilarlo mientras corre
Una instantánea te dice que el almacén está arriba. Una vista en vivo te dice lo que está haciendo. Watch-ZrStoreMetrics sondea los managers y redibuja una tabla por nodo a intervalos hasta que lo cancelas:
Watch-ZrStoreMetrics -StoreName orders -RefreshSec 2
Coloca primero los contadores del día a día —tasa de peticiones, gets, puts, deletes, recuento de elementos, uso de memoria— y empuja al fondo los diagnósticos avanzados de replicación y sincronización, de modo que los números que miras de un vistazo estén arriba. Los contadores de errores se ponen rojos en cuanto su tasa sube por encima de cero; el rendimiento se tiñe de verde a medida que sube. También señala los cambios de rol en línea: si un failover voltea una primaria a réplica mientras miras, se imprime una línea [ROLE CHANGE] con una marca de tiempo —la señal en vivo de que una partición acaba de cambiar de manos.
Un detalle deliberado que vale la pena destacar, porque es de esas cosas que hacen que una herramienta sea usable a las 2 de la madrugada: la vista obtiene el siguiente fotograma antes de limpiar la pantalla, y un sondeo vacío transitorio mantiene el último buen fotograma en vez de quedarse en blanco. Obtienes una tabla estable, no una parpadeante, por muy lento que sea un manager en responder.
Para redondear el conjunto de solo lectura, Get-ZrInfo reporta la versión instalada, los directorios de instalación y de datos, la ubicación de ambos módulos, el runtime del host, y sondea cada manager en busca de alcanzabilidad. Un manager asegurado que responde 401 se reporta como alcanzable pero necesitando autenticación, no como "caído", de modo que puedas distinguir de un vistazo un problema de red de un token ausente.
Paso 4 — detenerlo, y la forma que subyace a todo
Bajar un almacén es el espejo del ciclo de vida de arrancarlo:
# 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
El valor por defecto es un hard kill rápido, que es el comportamiento correcto cuando el almacén entero se va a bajar de golpe: no hay clúster superviviente al que un nodo que se marcha pueda entregar el relevo, así que drenar no compra nada. Usa -Graceful cuando quieras que cada nodo drene y deje el clúster limpiamente, lo cual importa cuando estás deteniendo un subconjunto en vez de todo.
Debajo de cada cmdlet de este artículo hay una idea: un almacén de Zaris tiene una forma deseada —una definición canónica de los servidores y particiones que se supone que debe tener— y el manager corre bajo un modelo supervisor que conduce continuamente los procesos en vivo hacia ella. New-ZrStore escribe esa forma; Start-ZrStore la realiza; Get-ZrStore y Get-ZrNode informan de cuán cerca está la realidad de ella. El mismo modelo es lo que convierte el redimensionado elástico en una línea en vez de un runbook: cambiar la forma deseada con Add-ZrServer / Remove-ZrServer y dejar que el supervisor reconcilie, que es su propia historia de escalado elástico.
El resumen honesto
El ciclo de vida completo de día uno son cinco comandos y dos lecturas:
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?
Lo que hace de esto un plano de control y no solo un montón de scripts es que los cmdlets reportan verdad en vivo y agregada —no lo que pediste, sino lo que el clúster realmente es— y que las decisiones con consecuencias reales se nombran a plena vista: el factor de replicación frente al recuento de máquinas, Async frente a Sync, las lecturas de réplica frente a la obsolescencia. Pon un almacén en pie, confirma que convergió y mantenlo vigilado, todo sin salir del shell.