How to manage cluster services
When to use
A cluster service is a unit that Cluster Manager starts on a specific node.
Storage pools (with names such as zpool_ssd01, zpool_tank0) and
cluster system services are represented this way. You manage services when maintaining a node,
moving a pool to another node, and troubleshooting a service that will not start.
A service has two independent dimensions. The first is permission: whether the service is allowed to operate or is disabled. The second is state: whether it is started or stopped. Enabling a service does not start it, and an attempt to start a disabled service will fail validation. This separation is intentional: disabling keeps the service off even after the node restarts, while stopping is a one-time action.
| Command | What it changes | Node required | When to use |
|---|---|---|---|
| Enable | Permission — the service is allowed to operate | no | Returning a service to operation |
| Disable | Permission — the service is disabled | no | Extended maintenance, taking a pool out of service |
| Start | State — starting on a node | yes | Starting a service on the selected node |
| Stop | State — stopping | no | A one-time stop without disabling |
Note the asymmetry: starting requires a node; stopping does not. A service starts on a specified node and stops wherever it is currently running.
Prerequisites
- The Cluster master (role_id=1) role — all four commands are restricted to this role;
- An available Cluster Manager: commands go to it, and it delivers them to the nodes;
- A service name containing letters, digits, and underscores — the cluster does not accept hyphens, periods, or spaces;
- vStack Center version 3.0.3.
Step 1. View the current service state
Service state is retrieved together with cluster membership.
- Open Provider Data Center → Storage Resources. The ZFS pools table shows cluster pools with GUID, Name, Health, Consuming, Scrubbing, Resilvering, Current node, and Capacity (RAW) columns.
- Open a pool from the table — the pool card provides an Actions menu with pool operations.
Interpret state as follows: permission tells you whether the service is allowed to operate, state tells you whether it is running now, and Current node tells you on which node. An enabled, running pool appears as running on its node. There is no point in starting a disabled, stopped service: enable it first.
Step 2. Start a service on a node
Starting targets a specific node: you need both a service and a node. vStack Center forwards the command to Cluster Manager, which delivers it to the node.
- Make sure the service is enabled. If it is disabled, complete step 4 first.
- Select the service and the node on which it should run, and start it.
- Check the result: the service should be running, and the node hosting it should match the one you selected.
An accepted command confirms that Cluster Manager received it. Only the service's state on the node confirms that it actually started.
Step 3. Stop a service
Stopping does not require a node: Cluster Manager already knows where the service is running. Select the service and stop it.
Stopping changes only the state. Permission remains, so the service can start again — for example, when the node restarts. If the service must remain off, disable it.
Step 4. Enable or disable a service
Permission is a persistent decision. Disabling keeps the service off regardless of restarts.
Disabling a storage pool service makes the data it serves unavailable. Before disabling it, check Storage Resources to see which node hosts the service (the Current node column) and which workloads depend on it.
Select the service and disable it — no node needs to be specified. Enable it through the same path using the opposite command.
For maintenance, follow this order: stop the service, disable it, perform the work, enable it, and start it on the required node. The reverse order — disabling without stopping — leaves the service running until the first restart.
Stopping a pool service also shuts down VMs running on remote nodes
VMs using this pool can run on nodes other than the owner node: with disks in NVMe mode, a machine can start on any node and access its disks over the network from the owner. Before 3.2.0, stopping the service shut down only the machines on the owner node; remote machines continued running and kept the pool in use — export failed with "pool is busy", and the service remained on its original node.
Starting with 3.2.0, vStack Center shuts down the pool's machines on other nodes before stopping the service. The same applies when moving a pool. Account for this when planning maintenance: stopping a pool service now also shuts down the machines you see running on neighboring nodes.
The barrier follows the principle "do not start unless certain". A node passes the check only if it confirms shutdown or reports that it has no machines using this pool. Any other outcome — an error, timeout, or lost connection — blocks the stop operation: it does not start at all, the service remains running, and the rejection response contains a list of machines blocking the operation and their nodes. The entire check has a 2-minute time limit.
Verify the result
Return to service state and compare it with what you requested.
| Action | Expected result after the command |
|---|---|
| Start | The service is running on the node specified in the request |
| Stop | The service is stopped and remains enabled |
| Disable | The service is disabled and stopped |
| Enable | The service is enabled; it must be started to run |
If permission has changed but state has not, the command was accepted, but the node has not reported back yet. Retrieve service state again.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| A service command is rejected with code -403 "Access denied" | Service commands are available only to the Cluster master role | Sign in with a cluster-level role |
| Error code -32602 "Invalid params" | The service name failed format validation | Remove hyphens, periods, and spaces; check the name against the Name column |
| Starting is rejected with code -20522 | The node identifier failed validation | Enter the node identifier as a number |
| Error code -713 | The command could not be forwarded to Cluster Manager | Check Cluster Manager availability; the command did not reach the nodes |
| The command is accepted, but service state has not changed | Cluster Manager accepted the command, but the node has not applied it yet | Retrieve state again; if the discrepancy persists, check the node in the Current node column |
| The service started on its own after the node restarted | It was stopped without being disabled | Disable the service rather than only stopping it |
| Stopping a pool service returned a list of machines blocking the operation | The pool's machines on other nodes could not be shut down: a node did not respond, the connection was lost, or a node returned an error | Resolve the issues with the listed machines on the specified nodes and try stopping again; the service remains unchanged |
| Starting has no effect | The service is disabled | Enable the service first, then start it |
| No cluster membership data is visible | The user does not have the privilege to view the status map | Request the View Cluster Status Map (full) (6003) privilege |
See also
- Cluster, nodes, and services — what a cluster service is and how Cluster Manager differs from the Cluster master role.
- How to manage cluster nodes — taking the node hosting a service out of service.
- How to view cluster resources — the status map that shows services and their node assignments.
API methods
API operations covered on this page: get-statusmap, cluster-service-enable,
cluster-service-disable, cluster-service-start, cluster-service-stop — see the
API reference.