Run distributed
This article runs Clustron Zaris as a distributed cluster. A cluster spreads the store across multiple nodes, where a node is a single running instance of the store. The nodes share data and coordinate work over the network.
You can run a cluster on one machine or across several. In both cases the store forms a cluster; only where the nodes run and how you connect to the managers differ.
Prerequisites
Before you start, you need Zaris installed, PowerShell 7 or later, and the cluster ports open: 7801 for the manager, 7811 for node-to-node traffic, and 7861 for client connections. On Windows, the installer opens the 7801–7899 range for you.
Choose a setup
Each machine runs one manager, which coordinates the cluster. The difference between the two setups is how many nodes run per machine and which managers you connect to.
| Aspect | Single machine | Multiple machines |
|---|---|---|
| Nodes | Several nodes on one machine (PartitionsPerNode > 1) | One node per machine (PartitionsPerNode = 1) |
| Managers | One (localhost) | One per machine, all listed |
| Use case | Development and testing on a single box | Production across servers |
Connect to the manager
Connect the admin shell to the manager before you create the store. A workspace is a named connection to one or more managers that the admin cmdlets target; create one and activate it with -Activate. Use the connection that matches your setup.
For a single machine, connect to the one local manager:
New-ZrWorkspace local -Managers localhost:7801 -Activate
For multiple machines, connect to every machine's manager, separated by commas:
New-ZrWorkspace prod -Managers 10.0.0.11:7801,10.0.0.12:7801 -Activate
If a workspace with that name already exists, or a manager is already part of another workspace, activate or join it instead with Use-ZrWorkspace <name> -Managers <managers>.
How the pieces fit together
A distributed cluster has three roles. Understanding them makes the steps below clearer:
- Managers coordinate the cluster. One runs per machine.
- Nodes are the store instances that host the data.
- Clients connect to the cluster to read and write data.
1. Create the store
Define the store with New-ZrStore. PartitionsPerNode sets how many partition processes run on each machine, and ReplicationFactor sets how many copies of each partition to keep. On a single machine, set PartitionsPerNode greater than 1 to run several nodes; across machines, leave it at the default of 1 so each connected machine runs one node. A single New-ZrStore call creates the store on every connected manager.
New-ZrStore `
-Name TestStore `
-PartitionsPerNode 2 `
-ReplicationFactor 1 `
-BaseClusterPort 7811 `
-BaseClientPort 7861
When several nodes run on one machine, Zaris assigns their ports automatically by incrementing the starting values. BaseClusterPort 7811 becomes 7811, 7812, and so on, and BaseClientPort 7861 becomes 7861, 7862, and so on.
2. Start the cluster
Start the store to bring every configured node online and form the cluster.
Start-ZrStore TestStore
3. Connect a client
Connect a client with Connect-ZrStore, giving it one endpoint to start from.
Connect-ZrStore -ConnectionString "zaris://10.0.0.11:7861/TestStore"
You only need to provide one endpoint, called the seed. The client uses the seed to discover the rest of the nodes, so you don't have to list every server. You can still list multiple endpoints — comma-separated in the connection string, for example zaris://10.0.0.11:7861,10.0.0.12:7861/TestStore — for resilience if the seed is unavailable.
What is an endpoint?
An endpoint is a machine or IP address joined to a client port, in the form <Machine/IP>:<ClientPort>. The machine is the server running the node, and the client port is the one you set with -BaseClientPort when you created the store. For example, localhost:7861 connects to a node on the local machine, and 10.0.0.11:7861 connects to a node on a remote server.
4. Verify the cluster
Store a value and read it back to confirm the cluster is working.
Set-ZrItem -Key "hello" -Value "world"
Get-ZrItem -Key "hello"
What you just did
You formed a Zaris cluster whose nodes share data and coordination. Because state is shared across nodes, the cluster also supports distributed locks, counters, and watch subscriptions. From here you can move your setup into configuration files and start calling the store from your applications.