Skip to main content

Multi-node configuration

Clustron Zaris runs a store across multiple nodes, either on one server or spread across several. This page explains the two topologies, how -PartitionsPerNode and -ReplicationFactor map nodes to servers, and how to choose the right layout. Get the topology right at creation time — it determines capacity, fault tolerance, and how ports are assigned.

The two topologies​

Zaris supports two common layouts. The difference is whether the nodes run on one machine or on several.

Single server, multiple nodes​

One server runs a single manager and several node processes. You control how many with -PartitionsPerNode (multiplied by the replication factor). Use this for local development and for testing distributed behavior without extra machines.

Server
  ├── Manager (7801)
  ├── <host>-n0 (7811 / 7861)
  └── <host>-n1 (7812 / 7862)

Create it by setting -PartitionsPerNode to the number of partitions you want per machine:

New-ZrStore `
  -Name TestStore `
  -PartitionsPerNode 2 `
  -ReplicationFactor 1 `
  -BaseClusterPort 7811 `
  -BaseClientPort 7861

Each server runs PartitionsPerNode × ReplicationFactor node processes, so this example produces two processes on the one machine.

Multiple servers​

Each server runs its own manager and its share of the store's partitions and replicas. Use this for production, for capacity beyond one machine, and for fault tolerance — losing one server does not take the whole store down.

Server 10.0.0.11 → Manager + 10.0.0.11-n0
Server 10.0.0.12 → Manager + 10.0.0.12-n0
Server 10.0.0.13 → Manager + 10.0.0.13-n0

First activate a workspace over every manager, then create the store once. With the default -PartitionsPerNode 1, each server runs its share:

New-ZrWorkspace prod @('10.0.0.11:7801','10.0.0.12:7801','10.0.0.13:7801') -Activate

New-ZrStore `
  -Name TestStore `
  -ReplicationFactor 2 `
  -BaseClusterPort 7811 `
  -BaseClientPort 7861

The workspace must include every manager before you create the store. New-ZrStore computes the layout from the live membership and creates each server's nodes, so a manager you left out of the workspace never receives its nodes. Keep -ReplicationFactor no greater than the number of servers, so each replica lands on a distinct machine.

How nodes and ports are assigned​

Two rules govern the generated topology.

  • Node names follow the pattern <serverHost>-n<index>, numbered from 0 on each server — the server 10.0.0.11 yields 10.0.0.11-n0, 10.0.0.11-n1, and so on. There is no name-prefix parameter; the names are derived from each manager's host.
  • Ports start at -BaseClusterPort and -BaseClientPort and increment for each additional node process on the same server. A single process per server reuses the same base ports on each machine, because each server has its own address.

The total node count is the number of servers in the workspace multiplied by -PartitionsPerNode × -ReplicationFactor.

Choose the right topology​

ScenarioRecommended topology
Local development and testingSingle server, multiple partitions per node
Small production deploymentOne partition per node, a few servers, -ReplicationFactor 2
Higher capacityMultiple servers, scale out by adding servers
Fault tolerance requiredMultiple servers, -ReplicationFactor ≤ server count

Common mistakes​

Three configuration errors account for most multi-node problems.

MistakeConsequenceFix
Running more than one manager on a serverConflicting control plane on that machineRun exactly one manager per server
-PartitionsPerNode too high for one machineIncrementing ports collide; nodes fail to startLower -PartitionsPerNode, or widen the port ranges
-ReplicationFactor greater than the server countReplicas share machines, so a server loss can lose dataKeep -ReplicationFactor ≤ number of servers in production
Not including all managers in the workspace before New-ZrStoreSome servers never receive their nodesActivate a workspace with every manager, verify with Get-ZrWorkspace, then create

Next steps​