Cluster architecture

A Clustron Zaris cluster runs two kinds of process: a manager that forms the control plane, and one or more nodes that form the data plane. This page describes what each does, the ports they use, and how a client finds its data.

Keeping the control plane and data plane separate is the central idea in the architecture. A slow administrative operation, such as creating a store or adding a server, runs only on the manager, so it cannot stall a hot read on a node. And because the manager is not on the request path, you can lose it without losing access to your data.

The manager: control plane

The manager handles the operations that are occasional and administrative rather than per-request. It is the cluster's point of administration, not a request proxy.

The manager is responsible for the following:

• Creating, starting, stopping, and deleting stores (in supervisor mode).
• Tracking cluster membership — which nodes exist and whether they are healthy.
• Holding cluster-wide configuration and security policy.
• Aggregating metrics and diagnostics.
• Backing the web console and answering its API.

A manager listens on port 7801 for the management API by default. You can change this with the ZARIS_MGMT_PORT environment variable, the ManagementPort configuration key, or an explicit ASPNETCORE_URLS. The web console is a separate service that answers on port 7810. Because the manager is not on the data path, clients keep reading and writing while it is down. What you lose while the manager is unavailable is the ability to run administrative operations until it returns.

note

In supervisor mode you run one manager per machine, and the console and CLI aggregate their views into one picture of the cluster. In attach mode a single manager observes every node. See Deployment models.

The nodes: data plane

Nodes are where your data lives and where per-request work happens. Every node does the following:

• Holds a share of the data as one or more partitions.
• Serves key-value operations: Get, Put, Delete, prefix scans, and queries.
• Runs the coordination primitives: leases, locks, counters, and watches.
• Enforces TTL expiration.
• Replicates its partitions to peer nodes and participates in failure detection.

Each node listens on two ports, one for clients and one for other nodes.

Port	Purpose
7861 (client port)	Where your application connects to read and write. Incremented per node on a machine (7861, 7862, …).
7811 (cluster port)	Node-to-node traffic: membership gossip and replication. Incremented per node (7811, 7812, …).

You run one or more nodes per machine. The node count per machine is partitions per node × replication factor, so a single laptop can host a realistic multi-node cluster for development. See Partitioning and replication.

Inside a node

Each node is a small storage engine built from focused components. The request pipeline is the front door; every other component does one job behind it.

• Request pipeline accepts client connections and routes each request to the right engine. It uses async I/O and backpressure so a burst of requests does not overwhelm the node.
• Segment store is the in-memory keyspace, split into segments so many cores can work concurrently without a single global lock.
• Index manager maintains equality and range indexes so queries avoid full scans.
• Expiration manager uses a timing-wheel sweeper that expires TTL entries in batches rather than scanning every key.
• Watch handlers deliver change events to key and prefix subscribers.
• Lease, lock, and counter engines implement the coordination primitives.
• Cluster sync streams each committed change to the partition's replicas.

Control plane compared with data plane

The table below summarizes why the two planes are optimized for different things.

	Control plane (manager)	Data plane (nodes)
Handles	store lifecycle, membership, config, security policy, metrics	Get/Put/Delete, scans, watches, leases, locks, counters
Frequency	occasional, administrative	every request, hot path
On the request path?	No	Yes
If it goes down	admin pauses; data keeps serving	that node's partitions fail over to replicas
Optimized for	correctness and clarity	throughput and low latency

How a client finds its data

Your application connects with the .NET client and gives it one or more node addresses as seeds. Routing then happens in the client, not through a proxy, so each operation is a single network hop to the node that holds the data.

From the seeds, the client does the following:

1. Learns the partition map — which node owns which partition.
2. Hashes each key to a segment, and maps the segment to a partition.
3. Sends the operation directly to the owning node, with no proxy hop through the manager.
4. Fails over to a replica, and refreshes the map, if a node becomes unreachable.

Membership and leadership

Nodes form a peer-to-peer cluster over the cluster port. They gossip health, detect failures, and track a leader that coordinates cluster-wide decisions such as partition ownership changes. When a node joins or leaves, the surviving nodes reconcile ownership and the manager's membership view updates. That updated view is what the Nodes page of the console shows.

Next steps

• Partitioning and replication
• Deployment models
• Web console