Ops Manager can rotate TLS certificates across a managed deployment without restarting MongoDB processes. When you increment the certificatesVersion field in the Automation Configuration, the MongoDB Agent runs db.adminCommand({ rotateCertificates: 1 }) on each eligible process in place, so client connections remain uninterrupted throughout the operation.
Eligibility
The MongoDB Agent applies zero-downtime rotation only to processes that meet all of the following requirements:
MongoDB version is 5.0 or later.
TLS is configured on the process.
All members of the deployment meet the requirements above.
The MongoDB Agent cannot apply zero-downtime rotation to a process in any of the following categories. In the Ops Manager UI, the checkbox for an ineligible deployment is disabled. Through the Automation API, Ops Manager rejects a configuration update for an ineligible deployment with an HTTP 400 error explaining why:
Condition | Behavior |
|---|---|
MongoDB version earlier than 5.0 | Not selectable in the Ops Manager UI. Automation API rejects the configuration update with an HTTP 400 error. |
TLS not configured | Not selectable in the Ops Manager UI. Automation API rejects the configuration update with an HTTP 400 error. |
BI Connector or | Not selectable in the Ops Manager UI. Automation API rejects the configuration update with an HTTP 400 error. |
TLS path change coincides with rotation | Rolling restart handles the path change. Ops Manager records the rotation as complete. |
Important
Zero-downtime rotation requires all processes in the deployment to meet the eligibility requirements. If any process does not qualify, use the existing method instead: navigate to Deployment, Security, Settings, TLS Settings, update the certificate path, and trigger a rolling restart through Review and Deploy.
Prerequisites
Before you rotate certificates, verify the following:
Your deployment is managed by Ops Manager Automation.
TLS is enabled on the deployment.
Your new TLS certificate is valid and correctly overwritten at the original configured path.
Rotate TLS Certificates
Use the Automation API or the Ops Manager UI to trigger certificate rotation.
Important
You cannot revert certificatesVersion to a previous value through the UI or the API. Ops Manager only allows this value to increase.
Use the Automation API
To rotate certificates using the Automation API, retrieve the current Automation Configuration, increment certificatesVersion, and upload the updated configuration.
Retrieve the current Automation Configuration.
Send a GET request to the Automation Configuration endpoint:
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" \ --digest \ --header "Accept: application/json" \ --request GET \ "https://<OpsManagerHost>/api/public/v1.0/groups/{GROUP-ID}/automationConfig"
Save the response body to a local file, such as automation-config.json.
Increment the certificatesVersion field.
In the processes array, locate the object for each process you want to rotate. Increment the certificatesVersion integer by 1. If the field is absent, add it and set it to 1.
To trigger in-place rotation, set a value greater than the currently published value. Equal values do not trigger rotation. Ops Manager rejects decrements with HTTP 400 INVALID_AUTOMATION_CONFIG. For field validation rules, see MongoDB Processes.
Upload the updated Automation Configuration.
Send a PUT request with the modified configuration:
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" \ --digest \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --request PUT \ --data @automation-config.json \ "https://<OpsManagerHost>/api/public/v1.0/groups/{GROUP-ID}/automationConfig"
Use the Ops Manager UI
To rotate certificates using the Ops Manager UI, navigate to the TLS settings for your project and select the deployments to rotate.
Rotation State and Durability
The MongoDB Agent persists the result of each rotation so that it survives agent restarts and resumes from where it left off.
Ops Manager records a TLS_CERTIFICATES_ROTATED event in the project's activity feed each time an Automation Configuration update rotates certificates on one or more processes. Use this event to audit certificate rotation history.
Retry Behavior
If the rotateCertificates command fails, the MongoDB Agent returns error code 128 (TlsCertificatesRotationErr). Ops Manager displays "TLS Certificate Rotation Error" in the Automation status panel and reschedules the step on the next convergence tick. Correct the certificate file on disk to resolve the error.
If the command succeeds but the MongoDB Agent can't persist the result, it retries automatically.
How the Agent Applies Rotation
When the MongoDB Agent detects an incremented certificatesVersion in the Automation Configuration, it checks each eligible process against the eligibility requirements and runs db.adminCommand({ rotateCertificates: 1 }).