For AI agents: a documentation index is available at https://www.mongodb.com/ko-kr/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.

Manage the Lifecycle of a Process

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.

  • Each operation is asynchronous. A 200 OK response 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=true query 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 without dryRun=true to apply the change.

  • 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 Admin role.

  • 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.

This procedure gracefully stops a running process.

1

Find the hostname:port of the process in the Ops Manager UI or with the v2.0 Get All Hosts endpoint.

2
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Accept: application/json" \ --include \ --request POST "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{GROUP-ID}/process/{HOST-PORT}:shutdown?pretty=true&dryRun=true"
3

Remove dryRun=true from the request. Ops Manager returns 200 OK with the process document, now with "disabled": true.

4

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 400. You cannot shut down a manual-mode process through automation.

This procedure starts a process that was previously shut down.

1

Find the hostname:port of the process in the Ops Manager UI or with the v2.0 Get All Hosts endpoint.

2
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Accept: application/json" \ --include \ --request POST "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{GROUP-ID}/process/{HOST-PORT}:startup?pretty=true&dryRun=true"
3

Remove dryRun=true from the request. Ops Manager returns 200 OK with the process document, now with "disabled": false.

4

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 RECOVERING and doesn't resync automatically. Resync the process instead.

This procedure gracefully restarts a running process. If the target is the current primary, the agent steps it down before restarting it.

1

Find the hostname:port of the process in the Ops Manager UI or with the v2.0 Get All Hosts endpoint.

2
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Accept: application/json" \ --include \ --request POST "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{GROUP-ID}/process/{HOST-PORT}:restart?pretty=true&dryRun=true"
3

Remove dryRun=true from the request. Ops Manager returns 200 OK with the process document, now with lastRestart set.

4

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 400 PROCESS_DISABLED_CANNOT_RESTART. Start the process instead.

The target host's agent has never reported to Ops Manager

Ops Manager rejects the request with 409 PROCESS_AGENT_NOT_REPORTING.

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.

1

Find the hostname:port of the process in the Ops Manager UI or with the v2.0 Get All Hosts endpoint.

2
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Accept: application/json" \ --include \ --request POST "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{GROUP-ID}/process/{HOST-PORT}:resync?pretty=true&dryRun=true"
3

Remove dryRun=true from the request. Ops Manager returns 200 OK with the process document, now with lastResync set.

4

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 mongos, a standalone, or an arbiter

Ops Manager rejects the request with 400 PROCESS_RESYNC_NOT_SUPPORTED. You can resync only data-bearing replica set members.

Another member of the replica set already has a resync outstanding

Ops Manager rejects the request with 409 PROCESS_RESYNC_IN_PROGRESS, including dry runs. Wait for the deployment to reach goal state, then retry.

The target is the current primary

Ops Manager returns 200 OK, but the Automation Agent doesn't resync a primary. The plan stays pending with the message A resync was requested on a primary. This requires manual intervention. The member keeps running as primary.

The target host's agent has never reported to Ops Manager

Ops Manager rejects the request with 409 PROCESS_AGENT_NOT_REPORTING.

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

AUTOMATION_PROCESS_SHUTDOWN_REQUESTED

A shutdown request was made for this process. Check this event if a member went offline unexpectedly.

Start

AUTOMATION_PROCESS_STARTUP_REQUESTED

A request was made to start a stopped process.

Restart

AUTOMATION_PROCESS_RESTART_REQUESTED

A restart request was made for this process. Check this event if a member briefly dropped out or an election occurred.

Resync

AUTOMATION_PROCESS_RESYNC_REQUESTED

A resync request was made for this process. Check this event if a member went into STARTUP2 or RECOVERING and is re-copying data.

The following table describes common errors and symptoms when you use the Process Lifecycle endpoints.

Symptom
Likely Cause
Resolution

409 AUTOMATION_CONFIG_DRAFT_ALREADY_EXISTS

You have an unpublished automation configuration draft in the project.

Publish or discard the draft, then retry.

409 AUTOMATION_CONFIG_CONCURRENT_MODIFICATION

Someone published a change between Ops Manager reading and publishing the configuration.

Retry the request.

409 GROUP_IN_RESTORATION_MODE

The project is reconciling after a restore.

Wait for reconciliation to finish, then retry.

409 PROCESS_AGENT_NOT_REPORTING

The target host's agent has never reported to Ops Manager.

Confirm the agent is installed, running, and can reach Ops Manager, then retry.

403 PROCESS_EXTERNALLY_MANAGED

The project's processes are managed by an external system.

These endpoints don't apply to externally managed projects.

404 PROCESS_NOT_FOUND

hostname:port doesn't match a process in the project's automation configuration.

Confirm the value with v2.0 Get All Hosts, then retry.

400 PROCESS_DISABLED_CANNOT_RESTART

The process is shut down.

Call the startup endpoint instead.

409 PROCESS_RESYNC_IN_PROGRESS

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.

400 PROCESS_RESYNC_NOT_SUPPORTED

The target is a mongos, a standalone, or an arbiter, which have no data to sync.

Resync a data-bearing replica set member instead.

400 INVALID_QUERY_PARAMETER

dryRun isn't true or false, including an empty value. For example, dryRun=tru or dryRun=.

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 RECOVERING after startup

The oplog rolled over while the process was down, so the member couldn't catch up.

Resync the process, then check replicaStateName on the host until it is SECONDARY.