AWS documentdb documentation change
Summary
Added documentation for unblocking global cluster switchovers/failovers when engine versions mismatch, updated CLI command syntax, and clarified version compatibility requirements
Security assessment
Changes focus on operational procedures for version compatibility during disaster recovery operations. While critical for system availability, there's no evidence of addressing a specific security vulnerability or exploit. The updates improve documentation clarity and add recovery guidance for version mismatch scenarios.
Diff
diff --git a/documentdb/latest/developerguide/global-clusters-disaster-recovery.md b/documentdb/latest/developerguide/global-clusters-disaster-recovery.md index 733510462..a17811c92 100644 --- a/documentdb/latest/developerguide/global-clusters-disaster-recovery.md +++ b/documentdb/latest/developerguide/global-clusters-disaster-recovery.md @@ -5 +5 @@ -Performing a managed failover for an Amazon DocumentDB global clusterPerforming a manual failover for an Amazon DocumentDB global clusterPerforming a switchover for an Amazon DocumentDB global cluster +Performing a managed failover for an Amazon DocumentDB global clusterPerforming a manual failover for an Amazon DocumentDB global clusterPerforming a switchover for an Amazon DocumentDB global clusterUnblocking a global cluster switchover or failover @@ -16,0 +17,2 @@ Performing a managed failover for an Amazon DocumentDB global clusterPerforming + * Unblocking a global cluster switchover or failover + @@ -39 +41,3 @@ During a managed failover, your primary cluster is failed over to your choice of -You can only perform a managed cross-Region cluster failover on an Amazon DocumentDB global cluster if the primary and secondary clusters have the same major, minor, and patch level engine versions. If your engine versions are incompatible, you can perform the failover manually by following the steps in Performing a manual failover for an Amazon DocumentDB global cluster. +You can only perform a managed cross-Region cluster failover on an Amazon DocumentDB global cluster if the primary and all secondary clusters have the same engine versions. If your engine versions are incompatible, you can perform the failover manually by following the steps in Performing a manual failover for an Amazon DocumentDB global cluster. + +If the region's engine versions do not match, the failover will be blocked. Please check for any pending upgrades and apply them to ensure all region's engine versions match and the global cluster failover is unblocked. For more information, see Unblocking a global cluster switchover or failover. @@ -78 +82 @@ Using the AWS Management Console -**To perform the managed failover on your Amazon DocumentDB global cluster** +**Perform a managed failover on your Amazon DocumentDB global cluster** @@ -108 +112,3 @@ Using the AWS CLI -**To perform the managed failover on your Amazon DocumentDB global cluster** +**Perform a managed failover on your Amazon DocumentDB global cluster** + +Run the [`failover-global-cluster`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/failover-global-cluster.html) CLI command to fail over your Amazon DocumentDB global cluster. With the command, pass values for the following options: @@ -110 +116 @@ Using the AWS CLI -Use the `failover-global-cluster` CLI command to fail over your Amazon DocumentDB global cluster. With the command, pass values for the following parameters: + * `--region` @@ -112 +118 @@ Use the `failover-global-cluster` CLI command to fail over your Amazon DocumentD - * `--region` — Specify the AWS Regions where the primary cluster of the Amazon DocumentDB global cluster is running. + * `--global-cluster-identifier` @@ -114 +120 @@ Use the `failover-global-cluster` CLI command to fail over your Amazon DocumentD - * `--global-cluster-identifier` — Specify the name of your Amazon DocumentDB global cluster. + * `--target-db-cluster-identifier` @@ -116 +122 @@ Use the `failover-global-cluster` CLI command to fail over your Amazon DocumentD - * `--target-db-cluster-identifier` — Specify the Amazon Resource Name (ARN) of the Amazon DocumentDB secondary cluster that you want to promote to be the primary for the Amazon DocumentDB global cluster. + * `--allow-data-loss` @@ -118 +123,0 @@ Use the `failover-global-cluster` CLI command to fail over your Amazon DocumentD - * `--allow-data-loss` — Explicitly make this a failover operation instead of a switchover operation. A failover operation can result in some data loss if the asynchronous replication components haven't completed sending all replicated data to the secondary Region. @@ -121,0 +127 @@ Use the `failover-global-cluster` CLI command to fail over your Amazon DocumentD +In the following examples, replace each `user input placeholder` with your cluster's information. @@ -126,2 +132,3 @@ For Linux, macOS, or Unix: - aws docdb --region region_of_selected_secondary \ - failover-global-cluster --global-cluster-identifier global_cluster_id \ + aws docdb failover-global-cluster \ + --region region_of_selected_secondary \ + --global-cluster-identifier global_cluster_id \ @@ -134,2 +141,3 @@ For Windows: - aws docdb --region region_of_selected_secondary ^ - failover-global-cluster --global-cluster-identifier global_cluster_id ^ + aws docdb failover-global-cluster ^ + --region region_of_selected_secondary ^ + --global-cluster-identifier global_cluster_id ^ @@ -197 +205 @@ Switchovers are designed to be used on a healthy Amazon DocumentDB global cluste -To perform a switchover, your target secondary DB cluster must be running the exact same engine version as the primary, including the patch level. Before you begin the switchover, check the engine versions and pending maintenance action items in your global cluster and regional clusters to make sure that they support managed cross-Region switchover, and upgrade them if needed. Amazon DocumentDB will automatically block calls to the switchover cluster if the engine versions don't match. +To perform a switchover, all secondary regions must be running the exact same engine version as the primary. If the region's engine versions do not match, the switchover will be blocked. Please check for any pending upgrades and apply them to ensure all region's engine versions match and the global cluster switchover is unblocked. For more information, see Unblocking a global cluster switchover or failover. @@ -234 +242 @@ Using the AWS Management Console -**To perform the switchover on your Amazon DocumentDB global cluster** +**Perform a switchover on your Amazon DocumentDB global cluster** @@ -264 +272 @@ Using the AWS CLI -**To perform the switchover on your Amazon DocumentDB global cluster** +**Perform a switchover on your Amazon DocumentDB global cluster** @@ -266 +274 @@ Using the AWS CLI -Use the `switchover-global-cluster` CLI command to switch over your Amazon DocumentDB global cluster. With the command, pass values for the following parameters: +Run the [`switchover-global-cluster`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/switchover-global-cluster.html) CLI command to switch over your Amazon DocumentDB global cluster. With the command, pass values for the following options: @@ -268 +276 @@ Use the `switchover-global-cluster` CLI command to switch over your Amazon Docum - * `--region` — Specify the AWS Regions where the primary cluster of the Amazon DocumentDB global cluster is running. + * `--region` @@ -270 +278 @@ Use the `switchover-global-cluster` CLI command to switch over your Amazon Docum - * `--global-cluster-identifier` — Specify the name of your Amazon DocumentDB global cluster. + * `--global-cluster-identifier` @@ -272 +280 @@ Use the `switchover-global-cluster` CLI command to switch over your Amazon Docum - * `--target-db-cluster-identifier` — Specify the Amazon Resource Name (ARN) of the Amazon DocumentDB secondary cluster that you want to promote to be the primary for the Amazon DocumentDB global cluster. + * `--target-db-cluster-identifier` @@ -276,0 +285,2 @@ Use the `switchover-global-cluster` CLI command to switch over your Amazon Docum +In the following examples, replace each `user input placeholder` with your cluster's information. + @@ -280,2 +290,3 @@ For Linux, macOS, or Unix: - aws docdb --region region_of_primary \ - switchover-global-cluster --global-cluster-identifier global_cluster_id \ + aws docdb switchover-global-cluster \ + --region region_of_primary \ + --global-cluster-identifier global_cluster_id \ @@ -287,2 +298,3 @@ For Windows: - aws docdb --region region_of_primary ^ - switchover-global-cluster --global-cluster-identifier global_cluster_id ^ + aws docdb switchover-global-cluster ^ + --region region_of_primary ^ + --global-cluster-identifier global_cluster_id ^ @@ -290,0 +303,122 @@ For Windows: +## Unblocking a global cluster switchover or failover + +Global cluster switchovers and failovers are blocked when not all regional clusters in the global cluster are on the same engine version. If the versions do not match, you may see this error in response when calling a switchover or failover: **`The target DB cluster specified is running an engine version with a different patch level than the source DB cluster`**. We recommended routinely applying the latest engine versions to ensure you are running the latest updates to keep your global clusters in a healthy state. + +To resolve this error, please update all all secondary regions first, and then the primary region to the same engine version by applying any pending maintenance action items. To view pending maintenance action items, and to apply any needed changes to correct the issue, perform the instructions in one of the following tabs: + +Using the AWS Management Console + + +To unblock a global cluster switchover or failover, you must determine if there are any pending maintenance actions for your clusters and apply them. Follow these steps to view and apply maintenance actions: + + 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). + + 2. In the navigation pane, choose **Clusters**. + + 3. In the **Clusters** table, locate your global cluster in the **Cluster identifier** column. + + 4. If an update is available for your cluster, it is indicated by the word **Available** , **Required** , or **Next Window** in the **Maintenance** column. + + 5. To take an action, choose the cluster to show it's details, then choose **Maintenance & backups**. The **Pending Maintenance** items appear. + + 6. Under **Description** , if it indicates that a "New maintenance update is available", select it and then choose **Apply now**. + + + + +Repeat this procedure for each secondary cluster in the global cluster to ensure that all region cluster engine versions match so that the switchover or failover can proceed. + +Using the AWS CLI + + +To unblock a global cluster switchover, you must determine if there are any pending maintenance actions for the cluster and apply them. Follow these steps to view and apply maintenance actions: + + 1. Run the [`describe-pending-maintenance-actions`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-pending-maintenance-actions.html) CLI command with the `--resource-identifier` option to determine if any maintenance actions are available for your Amazon DocumentDB global cluster. + +In the following examples, replace each `user input placeholder` with your cluster's information. + +For Linux, macOS, or Unix: + + aws docdb describe-pending-maintenance-action \ + --resource-identifier arn:aws:rds:us-east-1:001234567890:cluster:docdb-2025-03-27-19-21-15 + +For Windows: + + aws docdb describe-pending-maintenance-action ^ + --resource-identifier arn:aws:rds:us-east-1:001234567890:cluster:docdb-2025-03-27-19-21-15 + +The result looks similar to this: + + { + "PendingMaintenanceActions": [ + { + "ResourceIdentifier": "arn:aws:rds:us-east-1:001234567890:cluster:docdb-2025-03-27-19-21-15", + "PendingMaintenanceActionDetails": [ + { + "Action": "system-update", + "CurrentApplyDate": "2025-04-11T03:01:00Z", + "Description": "db-version-upgrade", + "ForcedApplyDate": "2025-06-18T03:01:00Z", + "AutoAppliedAfterDate": "2025-05-11T03:01:00Z" + "OptInStatus": "pending" + } + ] + } + ] + } + + 2. If a maintenance action is needed, run the [`apply-pending-maintenance-action`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/apply-pending-maintenance-action.html) CLI command with the following options: + + * `--resource-identifier` + + * `--apply-action` + + * `--opt-in-type` + + * `--region` + +In the following examples, replace each `user input placeholder` with your cluster's information. + +For Linux, macOS, or Unix: + + aws docdb apply-pending-maintenance-action \ + --resource-identifier arn:aws:rds:us-east-1:001234567890:cluster:docdb-2025-03-27-19-21-15 \ + --apply-action system-update \ + --opt-in-type immediate \ + --region us-east-1 + +For Windows: + + aws docdb apply-pending-maintenance-action ^ + --resource-identifier arn:aws:rds:us-east-1:001234567890:cluster:docdb-2025-03-27-19-21-15 ^ + --apply-action system-update ^ + --opt-in-type immediate ^ + --region us-east-1 + + 3. Once the maintenance action has completed, run the [`describe-pending-maintenance-actions`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-pending-maintenance-actions.html) command again to ensure that there are no other actions pending for your cluster. + +The result you want is: + + { + "PendingMaintenanceActions": [] + } + + + + +Repeat this procedure for each secondary cluster in the global cluster to ensure that all region cluster engine versions match so that the switchover or failover can proceed. + +Using the Amazon DocumentDB API + + +To unblock a global cluster switchover, you must determine if there are any pending maintenance actions for the cluster and apply them. Use the following APIs to view and apply maintenance actions: