/ /

Configure Maintenance Window

You can set the hour of the day when Atlas should start weekly maintenance on your cluster. This setting is optional and is not required for most clusters. Configure maintenance windows from your project settings.

Typically, you don't need to manually configure a maintenance window. Atlas performs maintenance automatically in a rolling manner to preserve continuous availability for resilient applications. You can use the Test Failover capability to ensure that your application is resilient to replica set elections.

Configuring maintenance windows provides more control over the timing of maintenance by allowing maintenance that requires replica set elections to occur at your preferred time of day, and other standard updates to occur outside of business-critical hours.

Important

You configure maintenance windows at the project level and they apply only to Dedicated clusters (M10 and above). For Free clusters and Flex clusters, Atlas manages their maintenance windows automatically and you can't configure them manually.

Maintenance Window Considerations

Urgent maintenance activities: Atlas may perform urgent maintenance activities (such as security patches for zero-day vulnerabilities) as soon as necessary without regard to configured maintenance windows or protected hours.
Ongoing maintenance operations: Once you schedule a maintenance window for your cluster, you cannot change it until any ongoing maintenance operations have completed.
MongoDB database upgrades: If maintenance includes a MongoDB patch version upgrade, Atlas displays the current and target versions in the console. If Atlas upgrades the MongoDB maintenance version on one of your clusters during the next maintenance window, the cluster's card displays the target MongoDB maintenance version.
Maintenance requires replica set elections: Atlas performs maintenance the same way as the maintenance procedure described in the MongoDB Manual. This procedure requires at least one replica set election during the maintenance window per replica set. Use the Test Failover capability to ensure that your application is resilient to replica set elections.
Maintenance starts as close to the start of the window as possible: Maintenance always begins as close to the scheduled time as possible, but in-progress cluster updates or unexpected system issues could delay the start time.
Potential for brief performance degradation during maintenance: If you have low Disk IOPS, your cluster could experience a brief performance degradation during maintenance while MongoDB repopulates the WiredTiger storage engine. To learn more, see Journaling and the WiredTiger Storage Engine.
Protected hours: In addition to configuring a maintenance window, you can set daily protected hours, which is a window of time during which Atlas avoids performing standard updates. Atlas automatically performs maintenance during the maintenance window.
However, Atlas may perform standard updates that don't involve a cluster restart or impact workload performance, outside of the maintenance window. When you enable protected hours, Atlas performs standard updates outside of the protected hours window. The length of your protected hours window can't exceed 18 hours.

Scheduled Maintenance Operation Types

The Scheduled Maintenance Operations modal may display one or more of the following maintenance types:

MongoDB Required Maintenance: Critical maintenance operations required for cluster health and stability.
MongoDB Version Update: Upgrades to MongoDB patch versions or maintenance releases.
OS Policy Version Update: Updates to the underlying operating system policies and security patches.
Other Maintenance Operation: Additional maintenance activities required for cluster management.

Track Maintenance Completion

You'll see a Maintenance window completed event in your Project Activity Feed when maintenance operations finish.

Enable Auto-Defer for Future Maintenance Windows

When you enable the Automatically defer maintenance for one week option, Atlas automatically defers future scheduled maintenance by one week each time. This means maintenance effectively runs every two weeks instead of weekly, since the first week is automatically deferred each time. If needed, you can still manually defer maintenance an additional time.

Important

If you enable the Automatically defer maintenance for one week option, Atlas configures automatic deferral for future maintenance windows. To defer currently scheduled maintenance, use the Defer 1 Week option as described in the Defer Maintenance section.

Auto-defer allows you to:

Reduce maintenance frequency: Set up auto-defer once to space out maintenance operations to occur every two weeks instead of weekly.
Batch updates: Consolidate maintenance operations into a single maintenance window and reduce the total number of maintenance events.
Test in lower environments first: Set up auto-defer in production environments and allow maintenance to run weekly in development or staging. This gives you time to validate updates before they reach production.

To enable auto-defer, see the section View and Configure Maintenance Window.

Required Access

To manage maintenance windows, you must have Organization Owner or Project Owner access to the project.

Procedure

Open Your Project Settings

In Atlas, go to the Project Settings page.

If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
In the sidebar, click Project Settings.

The Project Settings page displays.

View or modify project settings.

View and Configure Maintenance Window

To view and configure the maintenance window using the Atlas UI:

Click the Set Maintenance Window button to display the maintenance window settings.
Set the day and time that you want Atlas to start maintenance on your project.
If you want Atlas to automatically defer any scheduled maintenance for one week, click Automatically defer maintenance for one week.
Enabling this option configures automatic deferral for future maintenance windows. To defer currently scheduled maintenance, use the Defer 1 Week button.
To set a range of protected hours in which Atlas avoids performing standard updates, toggle the Turn on protected hours setting to On. You can set a maximum time range of 18 hours a day.
Click Save to keep your changes or click Cancel to discard them.

To return the details for the maintenance window using the Atlas CLI, run the following command:

atlas maintenanceWindows describe [options]

To update the maintenance window using the Atlas CLI, run the following command:

atlas maintenanceWindows update [options]

To learn more about the syntax and parameters for the previous commands, see the Atlas CLI documentation for atlas maintenanceWindows describe and atlas maintenanceWindows update.

Tip

See: Related Links

Clear Your Maintenance Window Configuration Settings

If you configured a preferred maintenance window start time, you can clear the settings using the Atlas CLI or the Atlas UI. Clearing your maintenance window configuration restores the default maintenance window settings.

To clear the configured maintenance window using the Atlas UI, toggle the Set Maintenance Window setting to Off.

To clear the configured maintenance window using the Atlas CLI, run the following command:

atlas maintenanceWindows clear [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas maintenanceWindows clear.

Respond to Required Maintenance

When maintenance is required:

Between 48 and 72 hours (2-3 days) before the scheduled maintenance, Atlas displays a banner in your project's cluster list showing the date and time when the maintenance is scheduled. Click Show Details to see the scheduled maintenance operations, such as MongoDB version updates, OS policy updates, or other maintenance types.
Atlas sends an email to users with the Project Owner role and updates the Atlas UI to display the option to begin maintenance immediately or to defer maintenance for one week.
Note
To configure how you receive scheduled maintenance window notifications, see Configure a Maintenance Window Alert.

Begin Maintenance Now

To begin maintenance immediately:

In the maintenance banner, click Show Details. A modal window titled Scheduled Maintenance Operations appears, showing the scheduled date and time along with the types of maintenance operations planned.

In the Scheduled Maintenance Operations modal, click the Begin Now button. In the Start Cluster Maintenance Now confirmation modal, confirm by clicking Yes, start my maintenance now.

To update the maintenance window using the Atlas CLI, run the following command:

atlas maintenanceWindows update [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas maintenanceWindows update.

IMPORTANT: To trigger maintenance immediately, pass the --startASAP option.

# Trigger immediate maintenance for the project with the ID
# 5e2211c17a3e5a48f5497de3:
atlas maintenanceWindows update --startASAP --projectId 5e2211c17a3e5a48f5497de3 --output json

Atlas provides the Update One Maintenance Window for One Project endpoint. You can trigger maintenance immediately by passing in the optional startASAP field with a value of true.

curl --user "${PUBLIC_KEY}:${PRIVATE_KEY}" \
  --digest --include \
  --header "Accept: application/vnd.atlas.2025-03-12+json" \
  --header "Content-Type: application/json" \
  -X PATCH "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/maintenanceWindow" \
  --data '
    {
      "startASAP": true
    }'

Defer Maintenance

Use the following procedure to defer currently scheduled maintenance by one week. To automatically defer all future maintenance, enable auto-defer.

Note

You can defer a single project maintenance event up to two times.

To defer scheduled maintenance:

In the Scheduled Maintenance Operations modal, click the Defer 1 Week button. In the Defer Maintenance to Next Week confirmation modal, confirm by clicking Yes, defer maintenance until next week.

Note

You can defer a single project maintenance event up to two times.

To defer the maintenance window using the Atlas CLI, run the following command:

atlas maintenanceWindows defer [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas maintenanceWindows defer.

Atlas provides the Defer One Maintenance Window for One Project endpoint.

Note

You can defer a single project maintenance event up to two times.

Back

Downgrade Major MongoDB Version

Stop, Start, or Delete