You can manage how Atlas rolls out maintenance for your projects by configuring:
Protected Hours: Business-critical hours during which standard updates can't occur.
Maintenance Windows: The time of day when Atlas should start weekly maintenance that requires replica set elections for clusters in a project.
Maintenance Sequence: The order in which projects in your organization receive maintenance. You configure maintenance sequence in waves labelled sequentially, from Wave 1 to Last Wave.
You can visualize how Atlas rolls out maintenance to your projects given your maintenance window, protected hours, and maintenance sequence configuration using the Projected Maintenance Calendar tool.
Important
Maintenance windows, protected hours, and maintenance sequence are configured per project 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.
We recommend that you set maintenance windows, protected hours, and maintenance sequence, though all are optional. Atlas performs maintenance automatically in a rolling manner to preserve continuous availability for resilient applications. To confirm that your application is resilient to replica set elections, test failover in Atlas.
Maintenance Management Considerations
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.
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 minor or 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. To confirm that your application is resilient to replica set elections, test failover in Atlas.
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.
Default Maintenance Sequence: Atlas automatically assigns maintenance waves to projects without explicit wave assignments using the following rules:
Atlas assigns projects without a configured maintenance window to Wave 1.
Atlas assigns projects with a configured maintenance window to Wave 2.
Maintenance sequence evaluation: Atlas evaluates the configured maintenance sequence at the time a maintenance event first goes out. If you make changes to the maintenance sequence between when a maintenance event starts and is completed across all waves, Atlas begins using the new maintenance sequence at the start of the next maintenance event.
Time between maintenance: When you have maintenance sequence configured, there is at least a 48-hour gap between when Atlas rolls out maintenance to one wave and the following wave. A maintenance must complete for all projects assigned to a given wave before Atlas proceeds to the next wave, starting with Wave 1.
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 minor versions, 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 have maintenance sequence configured for projects in an organization, you can't configure auto-deferring maintenance for projects in that organization.
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.
Configure Your Project's Maintenance Window and Sequence
View and Configure Maintenance Window and Sequence
You can configure a project's maintenance window, protected hours, and maintenance sequence from your organization's settings or from that project's settings.
In Atlas, go to the Organization Settings page.
If it's not already displayed, select your desired organization from the Organizations menu in the navigation bar.
In the sidebar, click Organization Settings.
The Organization Settings page displays.
The Maintenance Window and Sequence section displays the maintenance windows and sequence you have configured for the projects in your organization. To configure maintenance sequence waves from your organization's settings using the Atlas UI:
Click Edit sequence for all projects.
To manually assign maintenance waves to your projects, select Manual Assignment.
Use the dropdown next to each project to assign a maintenance wave.
If you have environment project tags set for your projects, you can use the Generate sequences based on existing project tags option.
Atlas generates the following assignments based on the environment project tags. You can only use these project tags for maintenance wave assignments.
development/test: Wave 1
staging: Wave 2
production: Last Wave
Atlas does not automatically update these assignments if you update a project's environment tag.
If you have Manual Assignment selected, you can also configure a project's maintenance sequence as you configure its maintenance window.
To link your projects' maintenance waves to their environment project tags, select Use Project Tags to auto-define sequence.
Atlas generates the following assignments based on the environment project tags. You can only use these project tags for maintenance wave assignments.
development/test: Wave 1
staging: Wave 2
production: Last Wave
Atlas automatically updates these assignments as you update a project's environment tag.
Click Save to keep your changes or click Cancel to discard them.
To configure a project's maintenance window using the Atlas UI:
Select one or more projects whose maintenance window you want to configure.
To edit the maintenance window of a single project, click the next to the project to open the Edit Maintenance Window page.
To edit the maintenance window of multiple projects, click the checkbox next to the projects you want to select. Then, click Edit Maintenance Window.
Set the day and time that you want Atlas to start maintenance on the projects you selected.
To set a range of protected hours in which Atlas avoids performing standard updates, toggle the Enable protected hours setting to On. You can set a maximum time range of 18 hours a day.
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.
Important
Deferring Maintenance when using Maintenance Sequence
Auto-deferring maintenance is not available for projects with maintenance sequence configured.
You can only defer maintenance for projects with a maintenance sequence wave configured if they are assigned to Last Wave. Atlas limits these projects to at most one deferral.
To set the maintenance sequence, use the dropdown under Sequence (per project) to assign your project or projects to a maintenance wave.
Note
Using Project Tags to Set Maintenance Sequence
If you have Use Project Tags to auto-define sequence selected in your organization-level maintenance sequence settings, you can't manually configure the maintenance sequence from a project's settings.
Click Save to keep your changes or click Cancel to discard them.
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 the icon next to Project Overview.
The Project Settings page displays.
The Maintenance Window and Sequence section displays the maintenance window and sequence you have configured for a project. To configure maintenance sequence waves from a projects's settings using the Atlas UI:
Click the Edit button to configure the maintenance window or sequence.
Set the day and time that you want Atlas to start maintenance on your project.
To set a range of protected hours in which Atlas avoids performing standard updates, toggle the Enable protected hours setting to On. You can set a maximum time range of 18 hours a day.
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.
Important
Deferring Maintenance when using Maintenance Sequence
Auto-deferring maintenance is not available for projects with maintenance sequence configured.
You can only defer maintenance for projects with a maintenance sequence wave configured if they are assigned to Last Wave. Atlas limits these projects to at most one deferral.
To set the maintenance sequence, use the dropdown under Sequence (per project) to assign your project or projects to a maintenance wave.
Note
Using Project Tags to Set Maintenance Sequence
If you have Use Project Tags to auto-define sequence selected in your organization-level maintenance sequence settings, you can't manually configure the maintenance sequence from a project's settings.
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.
Atlas provides the Update One Maintenance Window for One Project endpoint and the Get One Maintenance Window for One Project endpoint.
Note
This curl command uses a service account access token (OAuth 2.0) to authenticate instead of API keys. To learn more, see Get Started with the Atlas Administration API.
Delete Your Maintenance Window Configuration Settings
If you have maintenance windows, protected hours, or maintenance sequence configured, you can delete these settings using the Atlas UI, Atlas CLI, or the Atlas Administration API. Deleting your maintenance window configuration restores the default maintenance window settings.
Organization Settings
You can delete all configured maintenance sequence waves by clicking Delete sequence for all projects in the Maintenance Window and Sequence section.
To delete specific maintenance windows or sequence wave assignments:
If you have maintenance sequence waves configured, click the tab corresponding to the wave of the project whose maintenance window you want to delete.
Under Actions, click the icon next to the maintenance window you want to delete. This deletes the maintenance window and the assigned sequence wave.
To delete an assigned maintenance sequence wave without deleting the maintenance window:
Select one or more projects whose maintenance sequence wave you want to delete.
To delete the maintenance sequence wave of a single project, click the next to the project to open the Edit Maintenance Window page.
To delete the maintenance window of multiple projects, click the checkbox next to the projects you want to select. Then, click Edit Maintenance Window.
Select None using the dropdown under Sequence (per project).
Project Settings
To delete the configured maintenance window and sequence using the Atlas UI, click the icon in the Maintenance Window and Sequence section.
To delete an assigned maintenance sequence wave without deleting the maintenance window:
Click Edit in the Maintenance Window and Sequence section.
Select None using the dropdown under Sequence (per project).
Click Save to keep your changes or click Cancel to discard them.
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.
Atlas provides the Update One Maintenance Window for One Project endpoint.
Note
This curl command uses a service account access token (OAuth 2.0) to authenticate instead of API keys. To learn more, see Get Started with the Atlas Administration API.
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 Ownerrole 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 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 the icon next to Project Overview.
The Project Settings page displays.
Under the Database section in the left navigation, click Clusters.
In the maintenance banner, click View Details or View more scheduled maintenances.
A modal window titled Scheduled Maintenance Operations appears, showing the scheduled date and time along with the types of maintenance operations planned.
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.
Note
This curl command uses a service account access token (OAuth 2.0) to authenticate instead of API keys. To learn more, see Get Started with the Atlas Administration API.
curl --header "Authorization: Bearer {ACCESS-TOKEN}" \ --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
Deferring Maintenance with Maintenance Sequence Configured
You can only defer maintenance for projects with a maintenance sequence wave configured if they are assigned to Last Wave. Atlas limits these projects to at most one deferral.
Note
You can defer a single project maintenance event up to two times.
To defer scheduled maintenance:
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 the icon next to Project Overview.
The Project Settings page displays.
Under the Database section in the left navigation, click Clusters.
In the maintenance banner, click View Details or View more scheduled maintenances.
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 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.
Projected Maintenance Calendar Tool
To visualize when a maintenance event will roll out to your projects, you can use the Projected Maintenance Calendar tool. This tool allows you to enter potential maintenance window and sequence settings and a maintenance release date. Given these settings and release date, the tool displays the date and time at which Atlas would perform maintenance on the projects in each sequence wave.
This tool is not linked to your Atlas account. It can't read settings you have configured in Atlas or configure settings for your projects or organizations.