You can use the Ops Manager API to shut down, start, restart, and resync a MongoDB process. These operations are useful during resiliency testing to simulate downtime or for planned maintenance restarts. You can also resync a member that fell too far behind after a long shutdown.
When you send a request, Ops Manager immediately instructs the Automation Agent running on that host to shut down, start, restart, or resync the MongoDB process. The agent applies the change on its next check-in with Ops Manager. If the process is the current primary, the agent first steps it down so that another member can take over, then stops or restarts it.
About this Task
Each operation is asynchronous. A
200 OKresponse means Ops Manager published the change, not that the process has stopped, started, restarted, or resynced. The response includes no job ID. To follow the change to completion, poll the automation status resource. If the agent can't apply the change, the plan shows as failed there and the agent keeps retrying.Every endpoint accepts an optional
dryRun=truequery parameter. Use it to preview a change before you apply it. Ops Manager runs all the same checks and returns the process document as it would look after the change, but sends nothing to the agent and changes nothing in your deployment. For example, after a shutdown the returned document contains"disabled": true. Review it, then send the same request withoutdryRun=trueto apply the change.
Before You Begin
Your deployment must run Ops Manager 8.0.28 or 9.0.2 or later.
Automation must be enabled for the project, and the target host's Automation Agent must be running.
If you have an unpublished automation configuration draft in the project, Ops Manager rejects every request, including a dry run. Publish or discard the draft before you continue.
You must have the
Project Automation Adminrole.These endpoints don't support externally managed projects or Kubernetes Operator (MCK) deployments.
Warning
These endpoints provide no quorum protection. Shutting down too many members of a replica set leaves it without a primary. Shut members down one at a time and wait for each to stop before you continue.
Shut Down a Process
This procedure gracefully stops a running process.
Find the hostname and port of the process.
Find the hostname:port of the process in the Ops Manager UI or with the v2.0 Get All Hosts endpoint.
Poll the automation status endpoint.
Poll the automation status resource until the process's lastGoalVersionAchieved equals the plan's goalVersion.
The following table describes how Ops Manager handles shutdown requests in specific scenarios.
Scenario | Behavior |
|---|---|
Target is the current primary | The agent steps it down before stopping it. |
Target is already shut down | No change to the process. The agent takes no action, but Ops Manager still publishes the configuration and records the event. |
Target is in manual mode | Ops Manager rejects the request with |
Start a Process
This procedure starts a process that was previously shut down.
Find the hostname and port of the process.
Find the hostname:port of the process in the Ops Manager UI or with the v2.0 Get All Hosts endpoint.
Confirm the member returns to a healthy state.
Poll the automation status resource until the plan completes. Then confirm that the member's replicaStateName on the v2.0 Get One Host by ID endpoint returns to SECONDARY or PRIMARY.
The following table describes how Ops Manager handles startup requests in specific scenarios.
Scenario | Behavior |
|---|---|
Target is already running | No change to the process. The agent takes no action, but Ops Manager still publishes the configuration and records the event. |
The oplog rolled over while the process was down | The member starts and stays in |
Restart a Process
This procedure gracefully restarts a running process. If the target is the current primary, the agent steps it down before restarting it.
Find the hostname and port of the process.
Find the hostname:port of the process in the Ops Manager UI or with the v2.0 Get All Hosts endpoint.
Poll the automation status endpoint.
Poll the automation status resource until the plan completes.
The following table describes how Ops Manager handles restart requests in specific scenarios.
Scenario | Behavior |
|---|---|
Target is shut down | Ops Manager rejects the request with |
The target host's agent has never reported to Ops Manager | Ops Manager rejects the request with |
Resync a Process
This procedure triggers an initial sync on a replica set member. Use it to recover a member stuck in RECOVERING because it fell behind the oplog window.
Find the hostname and port of the process.
Find the hostname:port of the process in the Ops Manager UI or with the v2.0 Get All Hosts endpoint.
Confirm the member completes the initial sync.
Poll the automation status resource until the plan completes. Then poll v2.0 Get One Host by ID until replicaStateName is SECONDARY. The initial sync can take a long time on large data sets.
The following table describes how Ops Manager handles resync requests in specific scenarios.
Scenario | Behavior |
|---|---|
The target is a | Ops Manager rejects the request with |
Another member of the replica set already has a resync outstanding | Ops Manager rejects the request with |
The target is the current primary | Ops Manager returns |
The target host's agent has never reported to Ops Manager | Ops Manager rejects the request with |
Audit Trail
Each successful, non-dry-run request adds one event to the project's activity feed, alongside the usual automation configuration published event. The activity feed attributes requests made with the API to the Public API.
Operation | Event type | What it tells you |
|---|---|---|
Shut down |
| A shutdown request was made for this process. Check this event if a member went offline unexpectedly. |
Start |
| A request was made to start a stopped process. |
Restart |
| A restart request was made for this process. Check this event if a member briefly dropped out or an election occurred. |
Resync |
| A resync request was made for this process. Check this event if a member went into |
Troubleshooting
The following table describes common errors and symptoms when you use the Process Lifecycle endpoints.
Symptom | Likely Cause | Resolution |
|---|---|---|
| You have an unpublished automation configuration draft in the project. | Publish or discard the draft, then retry. |
| Someone published a change between Ops Manager reading and publishing the configuration. | Retry the request. |
| The project is reconciling after a restore. | Wait for reconciliation to finish, then retry. |
| The target host's agent has never reported to Ops Manager. | Confirm the agent is installed, running, and can reach Ops Manager, then retry. |
| The project's processes are managed by an external system. | These endpoints don't apply to externally managed projects. |
|
| Confirm the value with v2.0 Get All Hosts, then retry. |
| The process is shut down. | Call the startup endpoint instead. |
| A resync for this replica set was already requested and the deployment hasn't reached goal state yet. A resync that is stuck, for example one requested on a primary, keeps blocking new requests. | Poll the automation status resource until the plan completes, then retry. |
| The target is a | Resync a data-bearing replica set member instead. |
|
| Fix the value or omit the parameter. |
After resync, automation status shows manual intervention required | The resync was requested on a primary. | Step down the primary to unblock resyncing. |
Plan keeps failing in automation status | The agent can't apply the change, for example because the host is unreachable. | Review the process's error in the automation status response and fix the cause. The agent then retries. |
Member stays in | The oplog rolled over while the process was down, so the member couldn't catch up. | Resync the process, then check |