Connect to a cluster
Before you can create or manage a store, you connect to the cluster's managers. In PowerShell you activate a workspace — a named set of managers that every admin cmdlet targets. In the Web Console you open the console the manager serves and sign in. Either way, connecting is the first step.
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
- PowerShell
- Web Console
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.
- Open the Web Console that the manager serves — the console URL from your deployment (for example
https://10.0.0.11:7801, or the console address your Kubernetes/Docker deployment exposes). - Sign in. The console binds to the workspace of the manager you opened and lists that cluster's stores; in a multi-manager cluster it reads the full manager roster from the one you opened.
- From here you work across the Stores list and each store's tabs.
The workspace is a PowerShell/session concept. The Web Console is always bound to the manager you open, so there is no separate "create workspace" step — opening the console and signing in is the console equivalent.
Reactivate or join a workspace
Reactivating or joining a saved workspace is a PowerShell/session concept; the Web Console has no equivalent because it is always bound to the manager you opened.
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.