Taking a Node Offline for Maintenance

Applies to: Secret Server On-Premises only. Secret Server Cloud and platform use Azure Service Bus and are not affected by this procedure.

This procedure describes how to temporarily remove a RabbitMQ cluster node from service for maintenance — such as applying operating system patches, restarting the host server, or performing hardware maintenance — and then return it to service without altering cluster membership.

This procedure is for temporary maintenance only. It stops and restarts the RabbitMQ application process on the node. It does not remove the node from the cluster and does not affect cluster membership or queue data.

If you want to permanently decommission a node, see Removing a Node from a Cluster. If you are using quorum queues, additional steps are required before permanent removal; see Clustering Prerequisites.

Prerequisites

Administrator access on the RabbitMQ node being taken offline.
The cluster must have at least three nodes and must retain quorum (a majority of nodes running) while the node is offline. For a three-node cluster, only one node may be offline at a time. See Clustering Prerequisites for quorum requirements, which differ between mirrored and quorum queues.
Access to the RabbitMQ management UI on a peer node (not the node being taken offline) to verify status.

Load Balancer Considerations

If your RabbitMQ cluster sits behind a load balancer configured per the Load Balancing guidance (a single active node with TCP health checks every five seconds and immediate connection reset on failure), no manual load balancer action is needed during this procedure. When you stop the RabbitMQ application on the active node, the load balancer detects the failure, resets existing connections, and promotes one standby node to active. Distributed engines and Secret Server reconnect through the load balancer automatically.

When the node returns to service and passes consecutive health checks, it rejoins the cluster as a standby. It does not automatically become the active node again and is not eligible to serve as queue leader until queues are rebalanced. This is expected behavior.

If your load balancer is not configured for automatic health-based failover, you must manually fail traffic over to a standby node at the load balancer before running rabbitmqctl stop_app. See Load Balancing for the recommended configuration.

Taking the Node Offline

On the RabbitMQ node to be taken offline, open the Start menu and navigate to the RabbitMQ Server folder.
Right-click RabbitMQ Command Prompt and select Run as Administrator.
In the command prompt, run the following command:
Copy
```
rabbitmqctl stop_app
```
This stops the RabbitMQ application on the current node while leaving the Erlang runtime running. The node remains a cluster member in a stopped state.
Perform the required maintenance work on the server.

Verifying the Node Is Offline

From a different node in the cluster, open the RabbitMQ management UI (typically at http://<peer-node-hostname>:15672).
Navigate to the Overview tab. The node you stopped should appear in the node list with a status indicating it is not running.

Do not verify from the node you just stopped — its management UI will also be unavailable.

Alternatively, from a peer node with RabbitMQ Helper installed, run the following in the RabbitMQ Helper PowerShell window to verify cluster connectivity from a Helper perspective:
Copy
```
Assert-RabbitMqIsRunning
Assert-RabbitMqConnectivity
```
See Management for additional Helper cmdlets useful for validating cluster state.

Bringing the Node Back Online

On the RabbitMQ node that was taken offline, open RabbitMQ Command Prompt as Administrator (as in steps 1–2).
Run the following command:
Copy
```
rabbitmqctl start_app
```
This restarts the RabbitMQ application and rejoins the node to the cluster automatically.
Return to the RabbitMQ management UI on the peer node and refresh the Overview tab. The node should now appear as running.

Alternatively, on the node you just brought back online, run the following in the RabbitMQ Helper PowerShell window to confirm the node is running and reachable:
Copy
```
Assert-RabbitMqIsRunning
Assert-RabbitMqConnectivity
Request-RabbitMqHealthCheck
```
In Secret Server, go to Admin > Distributed Engine > Site Connectors. Open the site connector associated with this RabbitMQ cluster and select Validate. Then open each site assigned to this site connector and select Validate on each. The Enabled and Validated columns show yes/no values that are not real-time health indicators; running Validate is what confirms the connection is working after the node returns. Distributed engines that lost connectivity during the maintenance window should reconnect automatically within a few minutes.