AWS documentdb documentation change
Summary
Restructured maintenance documentation to clarify cluster vs instance maintenance, introduced lifecycle categories (optional/required/forced/minor versions), added detailed maintenance window tables per region, and expanded patching behavior including read availability impacts and global cluster handling.
Security assessment
The update explicitly documents that required patches contain security fixes and forced patches address critical security issues. However, there is no evidence this change addresses a specific vulnerability; it's a general documentation improvement about existing security maintenance processes.
Diff
diff --git a/documentdb/latest/devguide/db-instance-maintain.md b/documentdb/latest/devguide/db-instance-maintain.md index 6a10a71c1..482f2ed51 100644 --- a//documentdb/latest/devguide/db-instance-maintain.md +++ b//documentdb/latest/devguide/db-instance-maintain.md @@ -7 +7 @@ -Engine patch notificationsView pending maintenanceEngine updatesUser-initiated updatesManage maintenance windowsOperating system updatesGlobal clusters +Version numberingManage maintenance windowsEngine patch notificationsView pending maintenanceEngine updatesMinor versionsOperating system updatesUser-initiated updatesGlobal clusters @@ -11 +11 @@ Engine patch notificationsView pending maintenanceEngine updatesUser-initiated u -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). Database engine updates are required patches and include security fixes, bug fixes, and enhancements to the database engine. While most operating system patches are optional, if you don't apply them for a while, the patch may be required and auto applied to maintain your security posture. So, we recommend that you apply operating system updates to your Amazon DocumentDB instances as soon as they are available. +Amazon DocumentDB periodically performs two kinds of maintenance: @@ -13 +13 @@ Periodically, Amazon DocumentDB performs maintenance on Amazon DocumentDB resour -Database engine patches require that you take your Amazon DocumentDB clusters offline for a short time. Once available, these patches are automatically scheduled to apply during an upcoming scheduled maintenance window of your Amazon DocumentDB cluster. + * **Cluster maintenance** updates the database engine. Engine updates carry security fixes, bug fixes, new features, and other engine enhancements. @@ -15 +15 @@ Database engine patches require that you take your Amazon DocumentDB clusters of -Both cluster and instances maintenance have their own respective maintenance windows. Cluster and instance modifications that you have chosen not to apply immediately, are also applied during the maintenance window. 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). + * **Instance maintenance** updates the operating system (OS) on the instance. @@ -17 +16,0 @@ Both cluster and instances maintenance have their own respective maintenance win -###### Topics @@ -19 +17,0 @@ Both cluster and instances maintenance have their own respective maintenance win - * Notifications for Amazon DocumentDB engine patches @@ -21 +18,0 @@ Both cluster and instances maintenance have their own respective maintenance win - * Viewing pending Amazon DocumentDB maintenance actions @@ -23 +20 @@ Both cluster and instances maintenance have their own respective maintenance win - * Amazon DocumentDB engine updates +Engine patches and OS updates use the same three lifecycle categories— _optional_ , _required_ , and _forced_ —with the same notification and apply behavior for each category. Engine releases also have a fourth category: _minor versions_ , which you upgrade to manually. The categories are: @@ -25 +22 @@ Both cluster and instances maintenance have their own respective maintenance win - * User-initiated updates + * **Optional** —contains non-critical improvements. No auto-apply date and no AHD notification; apply when it suits you. (For OS updates, you can subscribe to `RDS-EVENT-0230` to be notified when one becomes available.) @@ -27 +24 @@ Both cluster and instances maintenance have their own respective maintenance win - * Managing your Amazon DocumentDB maintenance windows + * **Required** —contains security and other critical fixes. You receive a notification through the Health Dashboard (AHD) and e-mail. A required action auto-applies during your cluster or instance maintenance window after its `AutoAppliedAfterDate`. You can defer by changing the maintenance window before that date. @@ -29 +26 @@ Both cluster and instances maintenance have their own respective maintenance win - * Amazon DocumentDB operating system updates + * **Forced** —a rare, highly critical fix. Auto-applies outside your maintenance window after its `ForcedApplyDate`. Amazon DocumentDB only designates an action forced when no other option is available. @@ -31 +28 @@ Both cluster and instances maintenance have their own respective maintenance win - * Global clusters patching + * **Minor version** (engine releases only)—a numbered engine release on top of a major version (for example, `5.0.1`). User-driven: you upgrade by modifying the cluster's engine version. Never auto-applies; no AHD notification. Minor versions are not published for major versions earlier than 5.0. @@ -36 +33 @@ Both cluster and instances maintenance have their own respective maintenance win -## Notifications for Amazon DocumentDB engine patches +Engine patches are released into a single category (optional, required, or forced) and stay there. OS updates progress: most start as optional and, if not applied, transition to required and eventually forced. The exact timing depends on the patch and is published in the AHD notification and the date fields returned by `describe-pending-maintenance-actions` (see Apply dates). The Amazon DocumentDB [Release notes](https://docs.aws.amazon.com/documentdb/latest/devguide/release-notes.html) use these category names when announcing engine changes. @@ -38 +35 @@ Both cluster and instances maintenance have their own respective maintenance win -You will receive maintenance notifications for required database engine patches through health events in the Health Dashboard (AHD) in the AWS console and through e-mails. When an Amazon DocumentDB engine maintenance patch becomes available in a particular AWS region, all impacted Amazon DocumentDB user accounts in the region will receive an AHD and email notification for each Amazon DocumentDB version affected by the patch. You can view these notifications under the **Scheduled changes** section of the AHD in the AWS console. The notification will have details about timing of patch availability, auto apply schedule, list of impacted clusters, and release notes. This notification will also be delivered via e-mail to the AWS account’s root user email address. +Applying any engine patch takes the cluster offline briefly. The rest of this topic walks through how maintenance windows work, how to find pending work, how to apply engine patches and minor versions, how OS updates work, and special handling for global clusters. @@ -40,9 +37 @@ You will receive maintenance notifications for required database engine patches - - -Once you receive this notification, you can choose to self-apply these engine patches to your Amazon DocumentDB clusters before the scheduled auto-apply date. Or you can wait for the engine patches to get auto-applied during an upcoming maintenance window (default option). - -###### Note - -The **Status** for the notification in the AHD will be set to 'Ongoing' until a new Amazon DocumentDB engine patch with a new engine patch version is released. - -Once the engine patch is applied to your Amazon DocumentDB cluster, the cluster's engine patch version will be updated to reflect the version in the notification. You can run the `db.runCommand({getEngineVersion: 1})` command to verify this update. +###### Topics @@ -50 +39 @@ Once the engine patch is applied to your Amazon DocumentDB cluster, the cluster' -AWS Health also integrates with Amazon EventBridge which uses events to build scalable event-driven applications and integrates with over 20 targets, including AWS Lambda, Amazon Simple Queue Service (SQS), and others. You can use `AWS_DOCDB_DB_PATCH_UPGRADE_MAINTENANCE_SCHEDULED` event code to setup Amazon EventBridge before engine patches become available. You can setup EventBridge to respond to the event and auto-perform actions such as capturing event information, initiating additional events, sending notifications via additional channels such as push notifications to the AWS Console Mobile Application, and taking corrective or other actions, when an Amazon DocumentDB engine patch becomes available in your region. + * Engine version numbering @@ -52 +41 @@ AWS Health also integrates with Amazon EventBridge which uses events to build sc -In the rare scenario of Amazon DocumentDB cancelling an engine patch, you will receive an AHD notification as well as an e-mail informing you about the cancellation. Accordingly, you can use the `AWS_DOCDB_DB_PATCH_UPGRADE_MAINTENANCE_CANCELLED` event code to setup Amazon EventBridge to respond to this event. View the _Amazon EventBridge User Guide_ to learn more about using [Amazon EventBridge rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html). + * Managing your Amazon DocumentDB maintenance windows @@ -54 +43 @@ In the rare scenario of Amazon DocumentDB cancelling an engine patch, you will r -## Viewing pending Amazon DocumentDB maintenance actions + * Notifications for Amazon DocumentDB engine patches @@ -56 +45 @@ In the rare scenario of Amazon DocumentDB cancelling an engine patch, you will r -You can view whether a maintenance update is available for your cluster by using the AWS Management Console or the AWS CLI. + * Viewing pending Amazon DocumentDB maintenance actions @@ -58 +47 @@ You can view whether a maintenance update is available for your cluster by using -If an update is available, you can do one of the following: + * Amazon DocumentDB engine updates @@ -60 +49 @@ If an update is available, you can do one of the following: - * Defer a maintenance action that is currently scheduled for next maintenance window (for OS patches only). + * Minor version upgrades @@ -62 +51 @@ If an update is available, you can do one of the following: - * Apply the maintenance actions immediately. + * Amazon DocumentDB operating system updates @@ -64 +53 @@ If an update is available, you can do one of the following: - * Schedule the maintenance actions to start during your next maintenance window. + * User-initiated updates @@ -65,0 +55 @@ If an update is available, you can do one of the following: + * Global clusters patching @@ -69 +58,0 @@ If an update is available, you can do one of the following: -###### Note @@ -71 +60 @@ If an update is available, you can do one of the following: -If you take no action, required maintenance actions such as engine patches will be auto applied in an upcoming scheduled maintenance window. +## Engine version numbering @@ -73 +62 @@ If you take no action, required maintenance actions such as engine patches will -The maintenance window determines when pending operations start, but it does not limit the total execution time of these operations. +Amazon DocumentDB uses two separate version identifiers: @@ -75 +64 @@ The maintenance window determines when pending operations start, but it does not -Using the AWS Management Console + * **Engine version** —a three-part number in the form ``major`.`major`.`minor`` (for example, `5.0.0` or `5.0.1`). The first two parts (`5.0`) are the MongoDB compatibility version; the third part is the minor version, incremented when Amazon DocumentDB publishes a minor release containing bug fixes and non-breaking improvements. This is the version you specify when creating or upgrading a cluster. @@ -76,0 +66 @@ Using the AWS Management Console + * **Engine patch version** —a separate three-part number in the form ``major`.0.`patch`` (for example, `3.0.17983`) that identifies the patch level applied to your cluster. The middle digit is always `0`. Patch versions contain critical security and stability fixes. @@ -78 +67,0 @@ Using the AWS Management Console - 1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb). @@ -80 +68,0 @@ Using the AWS Management Console - 2. In the navigation pane, choose **Clusters**. @@ -82 +69,0 @@ Using the AWS Management Console - 3. If an update is available, it is indicated by the word **Available** , **Required** , or **Next Window** in the **Maintenance** column for the cluster on the Amazon DocumentDB console, as shown here: @@ -84 +71 @@ Using the AWS Management Console - +You can determine the engine version from the engine patch version's prefix, as shown in the following table. @@ -86 +73,6 @@ Using the AWS Management Console - 4. To take an action, choose the cluster to show its details, then choose **Maintenance & backups**. The **Pending Maintenance** items appear. +Engine patch version prefix | Amazon DocumentDB engine version +---|--- +`1.0.`x`` | 3.6 +`2.0.`x`` | 4.0 +`3.0.`x`` | 5.0 +`4.0.`x`` | 8.0 @@ -88 +80 @@ Using the AWS Management Console - +To check the patch version your cluster is running, connect and run `db.runCommand({getEngineVersion: 1})`. @@ -89,0 +82 @@ Using the AWS Management Console +For the list of released engine patch versions and what each one contains, see [Release notes](./release-notes.html). @@ -90,0 +84 @@ Using the AWS Management Console +## Managing your Amazon DocumentDB maintenance windows @@ -91,0 +86 @@ Using the AWS Management Console +Every cluster and every instance has its own weekly 30-minute maintenance window—the period when scheduled modifications and software patching run. Most events complete within 30 minutes; larger ones can run longer. @@ -93 +88 @@ Using the AWS Management Console -Using the AWS CLI +If you don't choose a window when creating the resource, Amazon DocumentDB assigns one at random within an 8-hour daily block defined for the Region, on a randomly selected day. Choose windows that minimize impact to your application—evenings or weekends, for example. @@ -94,0 +90 @@ Using the AWS CLI +For database engine upgrades, Amazon DocumentDB uses the cluster's window, not the windows of individual instances. @@ -96 +92 @@ Using the AWS CLI -Use the following AWS CLI operation to determine what maintenance actions are pending. The output here shows no pending maintenance actions. +The following table shows the default time blocks per Region. @@ -97,0 +94,36 @@ Use the following AWS CLI operation to determine what maintenance actions are pe +Region Name | Region | UTC Time Block +---|---|--- +US East (Ohio) | us-east-2 | 03:00-11:00 +US East (N. Virginia) | us-east-1 | 03:00-11:00 +US West (Oregon) | us-west-2 | 06:00-14:00 +Africa (Cape Town) | af-south-1 | 03:00–11:00 +Asia Pacific (Hong Kong) | ap-east-1 | 06:00-14:00 +Asia Pacific (Hyderabad) | ap-south-2 | 06:30–14:30 +Asia Pacific (Malaysia) | ap-southeast-5 | 13:00-21:00 +Asia Pacific (Mumbai) | ap-south-1 | 06:00-14:00 +Asia Pacific (Osaka) | ap-northeast-3 | 12:00-20:00 +Asia Pacific (Seoul) | ap-northeast-2 | 13:00-21:00 +Asia Pacific (Singapore) | ap-southeast-1 | 14:00-22:00 +Asia Pacific (Sydney) | ap-southeast-2 | 12:00-20:00 +Asia Pacific (Jakarta) | ap-southeast-3 | 08:00-16:00 +Asia Pacific (Melbourne) | ap-southeast-4 | 11:00-19:00 +Asia Pacific (Thailand) | ap-southeast-7 | 15:00-23:00 +Asia Pacific (Tokyo) | ap-northeast-1 | 13:00-21:00 +Canada (Central) | ca-central-1 | 03:00-11:00 +Canada West (Calgary) | ca-west-1 | 18:00-02:00 +China (Beijing) | cn-north-1 | 06:00-14:00 +China (Ningxia) | cn-northwest-1 | 06:00-14:00 +Europe (Frankfurt) | eu-central-1 | 21:00-05:00 +Europe (Zurich) | eu-central-2 | 02:00-10:00 +Europe (Ireland) | eu-west-1 | 22:00-06:00 +Europe (London) | eu-west-2 | 22:00-06:00 +Europe (Milan) | eu-south-1 | 02:00-10:00 +Europe (Paris) | eu-west-3 | 23:59-07:29 +Europe (Spain) | eu-south-2 | 02:00–10:00 +Europe (Stockholm) | eu-north-1 | 04:00–12:00 +Mexico (Central) | mx-central-1 | 03:00-11:00 +Middle East (UAE) | me-central-1 | 05:00–13:00 +South America (São Paulo) | sa-east-1 | 00:00-08:00 +Israel (Tel Aviv) | il-central-1 | 04:00-12:00 +AWS GovCloud (US-East) | us-gov-east-1 | 17:00-01:00 +AWS GovCloud (US-West) | us-gov-west-1 | 06:00-14:00 @@ -99 +131 @@ Use the following AWS CLI operation to determine what maintenance actions are pe - aws docdb describe-pending-maintenance-actions +### Changing your Amazon DocumentDB maintenance windows @@ -101 +133 @@ Use the following AWS CLI operation to determine what maintenance actions are pe -Output from this operation looks something like the following (JSON format). +Choose the lowest-traffic window you can, and adjust over time as your traffic patterns shift. The cluster or instance is unavailable during the window only if a system change—a scale-storage operation or an instance class change, for example—requires an outage, and only for as long as that change actually needs. @@ -102,0 +135 @@ Output from this operation looks something like the following (JSON format). +###### To change the maintenance window @@ -104,3 +137 @@ Output from this operation looks something like the following (JSON format). - { - "PendingMaintenanceActions": [] - } + * For a cluster, see [Modifying an Amazon DocumentDB cluster](./db-cluster-modify.html). @@ -108 +139 @@ Output from this operation looks something like the following (JSON format). -## Amazon DocumentDB engine updates + * For an instance, see [Modifying an Amazon DocumentDB instance](./db-instance-modify.html). @@ -110 +140,0 @@ Output from this operation looks something like the following (JSON format). -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. @@ -112 +141,0 @@ With Amazon DocumentDB, you can choose when to apply maintenance operations. You -Use the procedures in this topic to immediately upgrade or schedule an upgrade for your cluster. @@ -114 +142,0 @@ Use the procedures in this topic to immediately upgrade or schedule an upgrade f -Using the AWS Management Console @@ -115,0 +144 @@ Using the AWS Management Console +## Notifications for Amazon DocumentDB engine patches @@ -117 +146 @@ Using the AWS Management Console -You can use the console to manage updates for your Amazon DocumentDB clusters. +When a _required_ engine patch becomes available in an AWS Region, every AWS account with an affected Amazon DocumentDB cluster in that Region receives a notification through the Health Dashboard (AHD) and through e-mail (sent to the AWS account's root user address). One notification is delivered per affected Amazon DocumentDB engine version. You can find them under **Scheduled changes** in the AHD. Each notification lists the patch availability timing, the auto-apply schedule, the affected clusters, and the release notes. @@ -119 +148 @@ You can use the console to manage updates for your Amazon DocumentDB clusters. -###### To manage an update for a cluster + @@ -121 +150 @@ You can use the console to manage updates for your Amazon DocumentDB clusters. - 1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb). +Notifications go out approximately two days before the auto-apply window opens. For example, a required patch released Monday at 00:00 UTC becomes eligible for auto-apply on Wednesday at 00:00 UTC. If your cluster's maintenance window is Wednesday at 12:00 UTC, the patch auto-applies that Wednesday—about 12 hours after the auto-apply window opens. If your maintenance window is Tuesday at 12:00 UTC, the patch waits a full week before auto-applying. @@ -123 +152 @@ You can use the console to manage updates for your Amazon DocumentDB clusters. - 2. In the navigation pane, choose **Clusters**. +You have two options after receiving the notification: self-apply the patch before the auto-apply date, or wait for it to auto-apply during an upcoming maintenance window (the default). To self-apply, open the cluster's **Maintenance & backups** tab and look for the entry of type `system-update`.