Connect to a cluster
Before you can create or manage a store, you must point your PowerShell session at the cluster's managers. You do this by activating a workspace — a named set of managers that every admin cmdlet then targets. Establishing the workspace is always the first step in a session.
A manager is the control-plane service that runs on each server and creates, starts, and stops the nodes on that server. It listens on the management port, 7801 by default. In a multi-server cluster a workspace holds every manager's address at once, so each administrative change is applied consistently across every server.
Create and activate a workspace
Use New-ZrWorkspace to create a workspace from one or more manager endpoints and make it active. The first argument is the workspace name; the second is the manager list.
For a single-server cluster, point at the one local manager:
New-ZrWorkspace dev @('localhost:7801') -Activate
For a multi-server cluster, list every manager. Use the servers' real IP addresses or resolvable hostnames — not localhost, which only reaches the local machine:
New-ZrWorkspace prod @('10.0.0.11:7801','10.0.0.12:7801','10.0.0.13:7801') -Activate
-Activate makes the new workspace the session's target immediately. Without it, the workspace is saved but not activated; run Use-ZrWorkspace <name> to activate it later. Add -Force to replace a workspace of the same name.
New-ZrWorkspace returns the workspace it created. List saved workspaces at any time, with the active one marked, using Get-ZrWorkspace:
Name Active Mode Managers Token
---- ------ ---- -------- -----
prod True supervisor 3 False
A workspace with all its managers reachable shows the correct manager count and its mode (supervisor or attach). If the count is lower than the number of managers you listed, or the mode reads as unknown, resolve the unreachable manager before continuing — administrative changes may not apply cluster-wide while a manager is unreachable.
Reactivate or join a workspace
New-ZrWorkspace creates a workspace by claiming currently-unclaimed managers. To return to a workspace that already exists, use Use-ZrWorkspace instead.
To reactivate a workspace already saved on this machine, name it:
Use-ZrWorkspace prod
To join a workspace from a machine that does not have it saved yet, pass one of its managers as a seed — the full manager roster is discovered from it:
Use-ZrWorkspace prod @('10.0.0.11:7801')
Command reference
Use New-ZrWorkspace to create and activate a workspace, and Use-ZrWorkspace to reactivate or join an existing one.
New-ZrWorkspace <Name> <Managers[]> [-Token <string>] [-Force] [-Activate] [-Supervisor | -Attach]
Use-ZrWorkspace <Name> [<Managers[]>] [-Token <string>]
The manager endpoints accept several formats: a host and port (server1:7801), an IP address and port (10.0.0.11:7801), or a full URL (http://10.0.0.11:7801).
| Parameter | Description |
|---|---|
-Name | Name of the workspace. Required, and positional (first argument). |
-Managers | Manager endpoints. Required for New-ZrWorkspace; optional seed list for Use-ZrWorkspace. Positional (second argument). |
-Token | Admin bearer token for a secured cluster. |
-Force | Replace an existing workspace of the same name (New-ZrWorkspace). |
-Activate | Activate the workspace immediately after creating it (New-ZrWorkspace). |
-Supervisor / -Attach | Mark the deployment model explicitly. When neither is given, the model is auto-detected by probing the first manager. |
The active workspace is persisted under ~/.clustron, so it survives between sessions — you do not re-create it each time. Reactivate it with Use-ZrWorkspace <name>, and inspect all saved workspaces with Get-ZrWorkspace.
To target a manager for a single command without activating a workspace, pass -Managers directly to that cmdlet, for example Get-ZrStore -Managers 10.0.0.11:7801.
What you can do after activating a workspace
Once a workspace is active, its managers become the default target for New-ZrStore, Start-ZrStore, Stop-ZrStore, Get-ZrStore, and Watch-ZrStoreMetrics. You do not repeat the endpoints on each command; the active workspace supplies them. In a multi-server cluster, those cmdlets execute against every manager in the workspace to keep the configuration consistent.
Troubleshoot connection failures
If a cmdlet reports no manager connection, or a workspace shows fewer reachable managers than you expect, work through these causes.
| Symptom | Cause | Fix |
|---|---|---|
| "No active Zaris manager connection" | No workspace is active | Run New-ZrWorkspace <name> @('<host>:7801') -Activate, or pass -Managers to the command |
| Timeout or connection refused | The Management Service is not running | Confirm Clustron is installed and the Management Service is started on the target server |
Connection refused on 7801 | A firewall blocks the management port | Allow inbound TCP 7801 on the server and any network firewall between you and it |
| Some managers unreachable in the roster | An endpoint is unreachable or wrong | Verify each address and port; check network connectivity between machines |
| Works locally, fails from another host | You used localhost or 127.0.0.1 | Use the server's real IP or hostname for multi-server clusters |
Next steps
- Create a store — define and configure your first store.
- Ports and networking — confirm the management port is reachable.
- AdminShell cmdlet reference — full parameter and output details.