Maintaining Amazon DocumentDB
Periodically, Amazon DocumentDB performs maintenance on Amazon DocumentDB resources. Maintenance most often involves updates to the database engine (cluster maintenance) or the instance's underlying operating system (OS) (instance maintenance).
Some maintenance items require that Amazon DocumentDB take your instance offline for a short time. Maintenance items that require an instance to be offline include required operating system or engine patching. Required patching is automatically scheduled only for patches that are related to security and instance reliability. You should expect that when maintenance is performed on your cluster or instance, if the instance is a primary instance, it will fail over. To improve your availability, we recommend that you use more than one instance for your Amazon DocumentDB clusters. For more information, see Amazon DocumentDB Failover.
Deferred cluster and instance modifications, that you have chosen not to apply immediately, are also applied during the maintenance window. Both cluster and instances maintenance have their own respective maintenance windows. By default, when you create a cluster, Amazon DocumentDB assigns a maintenance window for both a cluster and each individual instance. You can choose the maintenance window when creating a cluster or an instance. You can also modify the maintenance windows at any time to fit your business schedules or practices. It is generally advised to choose maintenance windows that minimize the impact of the maintenance on your application (for example, on evenings or weekends). This guidance is highly contextual upon the type of application and usage patterns that you experience.
Topics
Determining Pending Amazon DocumentDB Maintenance Actions
You can view whether a maintenance update is available for your cluster by using the AWS Management Console or the AWS CLI.
If an update is available, you can do one of the following:
-
Defer the maintenance actions.
-
Apply the maintenance actions immediately.
-
Schedule the maintenance actions to start during your next maintenance window.
-
Take no action.
Important
Certain OS updates are marked as Required. If you defer a required update, you receive a notice from Amazon DocumentDB indicating when the update will be performed on your instance or cluster. Other updates are Available. You can defer these updates indefinitely.
The maintenance window determines when pending operations start, but it does not limit the total execution time of these operations. Maintenance operations are not guaranteed to finish before the maintenance window ends, and they can continue beyond the specified end time.
Applying Amazon DocumentDB Updates
With Amazon DocumentDB, you can choose when to apply maintenance operations. You can decide when Amazon DocumentDB applies updates using the AWS Management Console or AWS CLI.
Use the procedures in this topic to immediately upgrade or schedule an upgrade for your cluster.
Apply Dates
Each maintenance action has a respective apply date that you can find when describing the pending maintenance actions. When you read the output of pending maintenance actions from the AWS CLI, three dates are listed:
-
CurrentApplyDate—The date the maintenance action will get applied either immediately or during the next maintenance window. If the maintenance is optional, this value can benull. -
ForcedApplyDate—The date when the maintenance will be automatically applied, independent of your maintenance window. -
AutoAppliedAfterDate—The date after which the maintenance will be applied during the cluster's maintenance window.
User-Initiated Updates
As an Amazon DocumentDB user, you can initiate updates to your clusters or instances. For example, you can modify an instance's class to one with more or less memory, or you can change a cluster's parameter group. Amazon DocumentDB views these changes differently from Amazon DocumentDB initiated updates. For more information about modifying a cluster or instance, see the following:
To see a list of pending user initiated modifications, run the following command.
To see pending user initiated changes for your instances
For Linux, macOS, or Unix:
aws docdb describe-db-instances \ --query 'DBInstances[*].[DBClusterIdentifier,DBInstanceIdentifier,PendingModifiedValues]'
For Windows:
aws docdb describe-db-instances ^ --query 'DBInstances[*].[DBClusterIdentifier,DBInstanceIdentifier,PendingModifiedValues]'
Output from this operation looks something like the following (JSON format).
In this case, sample-cluster-instance has a pending change to a db.r5.xlarge instance class, while
sample-cluster-instance-2 has no pending changes.
[
[
"sample-cluster",
"sample-cluster-instance",
{
"DBInstanceClass": "db.r5.xlarge"
}
],
[
"sample-cluster",
"sample-cluster-instance-2",
{}
]
]Managing Your Amazon DocumentDB Maintenance Windows
Each instance and cluster has a weekly maintenance window during which any pending changes are applied. The maintenance window is an opportunity to control when modifications and software patching occur, in the event either are requested or required. If a maintenance event is scheduled for a given week, it is initiated during the 30-minute maintenance window that you identify. Most maintenance events also complete during the 30-minute maintenance window, although larger maintenance events might take more than 30 minutes to complete.
The 30-minute maintenance window is selected at random from an 8-hour block of time per Region. If you don't specify a preferred maintenance window when you create the instance or cluster, Amazon DocumentDB assigns a 30-minute maintenance window on a randomly selected day of the week.
The following table lists the time blocks for each Region from which default maintenance windows are assigned.
| Region | UTC Time Block |
|---|---|
| US East (Ohio) | 03:00-11:00 |
| US East (N. Virginia) | 03:00-11:00 |
| US West (Oregon) | 06:00-14:00 |
| South America (São Paulo) | 04:00-12:00 |
| Asia Pacific (Hong Kong) | 14:00-22:00 |
| Asia Pacific (Hyderabad) | 06:30–14:30 |
| Asia Pacific (Mumbai) | 17:30-01:30 |
| Asia Pacific (Seoul) | 13:00-21:00 |
| Asia Pacific (Singapore) | 14:00-22:00 |
| Asia Pacific (Sydney) | 12:00-20:00 |
| Asia Pacific (Tokyo) | 13:00-21:00 |
| Canada (Central) | 03:00-11:00 |
| Europe (Frankfurt) | 23:00-07:00 |
| Europe (Ireland) | 22:00-06:00 |
| Europe (London) | 22:00-06:00 |
| Europe (Milan) | 23:00-07:00 |
| Europe (Paris) | 22:00-06:00 |
| China (Beijing) | 14:00-22:00 |
| China (Ningxia) | 14:00-22:00 |
| AWS GovCloud (US-West) | 06:00-14:00 |
| AWS GovCloud (US-East) | 17:00-01:00 |
Managing Your Amazon DocumentDB Maintenance Windows
The maintenance window should fall at the time of lowest usage and thus might need changing from time to time. Your cluster or instance is unavailable during this time only if system changes (such as a scale storage operation or an instance class change) are being applied and require an outage. And then it is unavailable only for the minimum amount of time required to make the necessary changes.
For upgrades to the database engine, Amazon DocumentDB uses the cluster's preferred maintenance window and not the maintenance window for individual instances.
To change the maintenance window
-
For a cluster, see Modifying an Amazon DocumentDB cluster.
-
For an instance, see Modifying an Amazon DocumentDB instance.
Working with operating system updates
Instances in Amazon DocumentDB clusters occasionally require operating system updates. Amazon DocumentDB upgrades the operating system to a newer version to improve database performance and customers’ overall security posture. Operating system updates don't change the cluster engine version or instance class of an Amazon DocumentDB instance.
We recommend that you update the reader instances in a cluster first, then the writer instance to maximize the availability of your cluster. We don't recommend updating reader and writer instances at the same time, because you might incur longer downtime in the event of a failover.
Operating system updates don’t have an apply date and can be applied at any time. We recommend that you apply them periodically to keep your Amazon DocumentDB databases up to date. Amazon DocumentDB does not apply these updates automatically. To be notified when a new optional update becomes available, you can subscribe to RDS-EVENT-0230 in the security patching event category. For information about subscribing to Amazon DocumentDB events, see Subscribing to Amazon DocumentDB Event Subscriptions.
Note
For certain management features, Amazon DocumentDB uses operational technology that is shared with Amazon Relational Database Service (Amazon RDS).
Important
Your Amazon DocumentDB instance will be taken offline during the operating system upgrade.
Note
Staying current on all optional and mandatory updates might be required to meet various compliance obligations. We recommend that you apply all updates made available by Amazon DocumentDB routinely during your maintenance windows.
You can use the AWS Management Console or the AWS CLI to determine whether an update is optional or mandatory.
Availability of operating system updates
Operating system updates are specific to Amazon DocumentDB engine versions and instance classes.
Therefore, Amazon DocumentDB instances receive or require updates at different times.
When an operating system update is available for your instance based on its engine version and instance class, the update appears in the console.
It can also be viewed by running the AWS CLI describe-pending-maintenance-actions command or by calling the DescribePendingMaintenanceActions API operation.
If an update is available for your instance, you can update your operating system by following the instructions in Applying Amazon DocumentDB Updates.
