AWS documentdb documentation change
Summary
Major restructuring and update of the Amazon DocumentDB in-place major version upgrade (MVU) documentation. Changes include: updated section headers and table of contents, added support for upgrading from version 5.0 to 8.0, clarified prerequisites and best practices, reorganized troubleshooting, and removed outdated information about MVU not being supported for version 8.0.
Security assessment
The changes are a comprehensive documentation update and reorganization. There is no mention of security vulnerabilities, patches, or incidents. The update focuses on feature support (adding 8.0 upgrade path), clarifying procedures, and improving readability. No security-specific features, configurations, or warnings were added.
Diff
diff --git a/documentdb/latest/developerguide/docdb-mvu.md b/documentdb/latest/developerguide/docdb-mvu.md index 7a07a88df..2067d8ae8 100644 --- a//documentdb/latest/developerguide/docdb-mvu.md +++ b//documentdb/latest/developerguide/docdb-mvu.md @@ -7 +7 @@ -MVU prerequisites and limitationsBest practices for in-place major version upgradesPerforming an in-place major version upgradeDifferences between Amazon DocumentDB 3.6/4.0 to 5.0 upgraded clusters and new Amazon DocumentDB 5.0 clustersTroubleshooting an in-place major version upgrade +Supported upgrade pathsPrerequisitesBest practicesWhat changes after upgrading from Amazon DocumentDB 5.0 to 8.0Post-upgrade considerations for clusters upgraded from 3.6 or 4.0Performing the upgradeTroubleshooting @@ -11,3 +11 @@ MVU prerequisites and limitationsBest practices for in-place major version upgra -Amazon DocumentDB makes new versions of database engines generally available only after extensive testing. You can choose how and when to upgrade your Amazon DocumentDB clusters to the new version. - -Currently, Amazon DocumentDB supports four major versions: Amazon DocumentDB 3.6, 4.0, 5.0, and 8.0. You can perform an in-place major version upgrade (MVU) of your database while keeping the same endpoints, storage, and tags of the clusters and can continue using your applications without any modifications. This feature is available for free in all regions where Amazon DocumentDB 5.0 is available. Note: MVU is currently not supported for Amazon DocumentDB 8.0. +You can perform an in-place major version upgrade (MVU) of your Amazon DocumentDB cluster while keeping the same endpoints, storage, and tags. Your applications continue to work without modifications. This feature is available at no additional cost in all regions where Amazon DocumentDB is available. @@ -17,3 +15 @@ Currently, Amazon DocumentDB supports four major versions: Amazon DocumentDB 3.6 -Your Amazon DocumentDB clusters will be unavailable during the in-place major version upgrade and your clusters will experience multiple reboots. Please refrain from connecting, reading, or writing to the cluster after starting the upgrade. Upgrade downtime can vary from cluster to cluster depending on number of collections, indexes, databases, and instances. We recommend performing the upgrade during your maintenance window or during low utilization hours. Once your cluster has been upgraded, you cannot downgrade the cluster to previous version, but you can choose to restore your pre-upgrade snapshot to a new cluster. - -###### Topics +Your cluster will be unavailable during the upgrade and will experience multiple reboots. Do not connect to, read from, or write to the cluster after starting the upgrade. Downtime varies depending on the number of collections, indexes, databases, and instances. We recommend performing the upgrade during your maintenance window or low-utilization hours. @@ -21 +17 @@ Your Amazon DocumentDB clusters will be unavailable during the in-place major ve - * MVU prerequisites and limitations +Once upgraded, you cannot downgrade to a previous version. You can restore your pre-upgrade snapshot to a new cluster if needed. @@ -23 +19 @@ Your Amazon DocumentDB clusters will be unavailable during the in-place major ve - * Best practices for in-place major version upgrades +###### Topics @@ -25 +21 @@ Your Amazon DocumentDB clusters will be unavailable during the in-place major ve - * Performing an in-place major version upgrade + * Supported upgrade paths @@ -27 +23 @@ Your Amazon DocumentDB clusters will be unavailable during the in-place major ve - * Differences between Amazon DocumentDB 3.6/4.0 to 5.0 upgraded clusters and new Amazon DocumentDB 5.0 clusters + * Prerequisites @@ -29 +25 @@ Your Amazon DocumentDB clusters will be unavailable during the in-place major ve - * Troubleshooting an in-place major version upgrade + * Best practices @@ -30,0 +27 @@ Your Amazon DocumentDB clusters will be unavailable during the in-place major ve + * What changes after upgrading from Amazon DocumentDB 5.0 to 8.0 @@ -31,0 +29 @@ Your Amazon DocumentDB clusters will be unavailable during the in-place major ve + * Post-upgrade considerations for clusters upgraded from 3.6 or 4.0 @@ -32,0 +31 @@ Your Amazon DocumentDB clusters will be unavailable during the in-place major ve + * Performing the upgrade @@ -34 +33 @@ Your Amazon DocumentDB clusters will be unavailable during the in-place major ve -## MVU prerequisites and limitations + * Troubleshooting @@ -36 +34,0 @@ Your Amazon DocumentDB clusters will be unavailable during the in-place major ve -The following are prerequisites and limitations to in-place major version upgrade that you may need to understand and act on before performing the upgrade: @@ -38 +35,0 @@ The following are prerequisites and limitations to in-place major version upgrad -###### Important @@ -40 +36,0 @@ The following are prerequisites and limitations to in-place major version upgrad -MVU is currently not supported for Amazon DocumentDB 8.0. To use engine version 8.0, create a new 8.0 cluster and migrate your data. MVU support for 8.0 is planned for a future release. @@ -42 +38 @@ MVU is currently not supported for Amazon DocumentDB 8.0. To use engine version - * **Instance Type** — Amazon DocumentDB 4.0/5.0 does not support r4.* instances. In order to proceed with an in-place major version upgrade, modify r4.* instances to r5.* instances. See [Modifying an Amazon DocumentDB instance](./db-instance-modify.html) for more information. Please refer to [Supported instance classes by region](./db-instance-classes.html#db-instance-classes-by-region) for supported instances based on the Amazon DocumentDB engine version. +## Supported upgrade paths @@ -44 +40,5 @@ MVU is currently not supported for Amazon DocumentDB 8.0. To use engine version - * **Instance OS patches** — An in-place major version upgrade needs the latest operating system (OS) patch to proceed. Please apply any pending OS maintenance actions on the instances before proceeding with the in-place upgrade. For more information, see [Amazon DocumentDB operating system updates](./db-instance-maintain.html#os-system-updates). +Source version | Target version +---|--- +Amazon DocumentDB 3.6 | Amazon DocumentDB 5.0 +Amazon DocumentDB 4.0 | Amazon DocumentDB 5.0 +Amazon DocumentDB 5.0 | Amazon DocumentDB 8.0 @@ -48 +48 @@ MVU is currently not supported for Amazon DocumentDB 8.0. To use engine version -In some situations, if you have pending cluster level engine patches, instance OS patches are not visible. You may need to apply cluster level engine patches before proceeding with applying instance OS patches and, subsequently, the in-place major version upgrade. See [Performing a patch update to a cluster's engine version](./db-cluster-version-upgrade.html). +In-place MVU is not supported for global clusters or elastic clusters. To upgrade a global cluster, remove the secondary clusters, convert the primary to a regional cluster, perform the MVU, then recreate the global cluster by adding secondary clusters using the same names to retain your endpoints. You will incur I/O charges while the upgraded primary replicates data to the new secondaries. For detailed steps, see [Removing a cluster from an Amazon DocumentDB global cluster](./global-clusters.manage.html#global-clusters.remove). @@ -50 +50 @@ In some situations, if you have pending cluster level engine patches, instance O - * In-place major version upgrade is available in all regions where Amazon DocumentDB 5.0 is available. +## Prerequisites @@ -52 +52 @@ In some situations, if you have pending cluster level engine patches, instance O - * In-place major version upgrade is not supported with Amazon DocumentDB 4.0 as the target version. + * **Instance type** — Amazon DocumentDB 4.0+ does not support db.r4 instances. Modify any `db.r4.*` instances to `db.r5.*` instances or newer before upgrading. See [Modifying an Amazon DocumentDB instance](./db-instance-modify.html) and [Supported instance classes by region](./db-instance-classes.html#db-instance-classes-by-region). @@ -54 +54 @@ In some situations, if you have pending cluster level engine patches, instance O - * In-place major version upgrade is not currently supported on Amazon DocumentDB global clusters and elastic clusters. + * **OS patches** — Apply any pending OS maintenance actions on all instances before upgrading. See [Amazon DocumentDB operating system updates](./db-instance-maintain.html#os-system-updates). @@ -58 +58 @@ In some situations, if you have pending cluster level engine patches, instance O -To upgrade your global clusters, delete your secondary clusters from the global cluster, convert the primary cluster to a regional cluster, perform an in-place major version upgrade on the regional (primary) cluster, then recreate the global cluster by adding secondary clusters using the same name in order to retain the same endpoints as earlier. Note that you will incur IO charges while your upgraded primary cluster replicates data to your newly added secondary clusters. For detailed steps on how to remove secondary clusters from global cluster before deleting, see [Removing a cluster from an Amazon DocumentDB global cluster](./global-clusters.manage.html#global-clusters.remove). +Pending cluster-level engine patches may hide instance OS patches. Apply engine patches first if needed. See [Performing a patch update to a cluster's engine version](./db-cluster-version-upgrade.html). @@ -60 +60 @@ To upgrade your global clusters, delete your secondary clusters from the global - * If you have a large amount of indexes (>3,000) operating in burstable performance instances (e.g. t3.medium or t4g.medium), you must scale up your primary instance to a larger instance (for example, at least r5.large) to perform the in-place major version upgrade. You can choose to scale down the instance size once your in-place major version upgrade is complete. See the table below for the maximum number of indexes supported on the db.t3 and db.t4g instance types for an in-place major version upgrade: + * **Index limits on burstable instances (t-family instances)** — If you have more than 3,000 indexes on burstable instances, scale up the primary to at least db.r5.large before upgrading. You can scale back down after the upgrade completes. @@ -62 +62 @@ To upgrade your global clusters, delete your secondary clusters from the global -Instance | Maximum indexes supported for in-place MVU +Instance | Maximum indexes for MVU @@ -66,0 +67 @@ db.t3.medium | 10K + * **Parameter group** — We recommend having a custom cluster parameter group for the target version ready before upgrading. If one is not specified, the default parameter group for the target version will be used (for example, `default.docdb5.0` or `default.docdb8.0`). @@ -67,0 +69 @@ db.t3.medium | 10K + * **Manual snapshot** — Create a manual snapshot before upgrading. The upgrade process creates an automatic snapshot named `preupgrade-<name>-<version>-<timestamp>`, but we strongly recommend having your own backup. See [Creating a manual cluster snapshot](./backup_restore-create_manual_cluster_snapshot.html). @@ -68,0 +71 @@ db.t3.medium | 10K +###### Note @@ -70,31 +73 @@ db.t3.medium | 10K -## Best practices for in-place major version upgrades - -###### Topics - - * Test in-place major version upgrades using cloned clusters - - * Before an in-place major version upgrade - - * During an in-place major version upgrade - - * After an in-place major version upgrade - - - - -### Test in-place major version upgrades using cloned clusters - - 1. To test in-place major version upgrades, we recommend using fast cloning feature to create a clone of your target cluster. You will not incur any storage costs for testing in-place major version upgrade on a cloned volume, unless you modify any data on the cluster. For more information on volume clone, see [Cloning a volume for an Amazon DocumentDB cluster](./db-cluster-cloning.html). - - 2. To get a more realistic estimate of the time taken to complete the in-place major version upgrade, match the instance count of the cloned cluster to the targeted cluster. - - 3. We recommend fully testing the newly upgraded Amazon DocumentDB 5.0 cluster for any functional differences to ensure everything is working as expected. - - - - -### Before an in-place major version upgrade - - 1. Have a version-compatible cluster parameter group ready. - -Use the Amazon DocumentDB default cluster parameter group for the new engine version or create your own custom cluster parameter group for the new engine version. +The auto snapshot created by the upgrade process will not be automatically deleted after the in-place major version upgrade has completed. This snapshot will not incur any charges as long as it is within the retention period. You can choose to delete this snapshot once you have verified a successful upgrade of your cluster. @@ -102 +75 @@ Use the Amazon DocumentDB default cluster parameter group for the new engine ver -If you associate an Amazon DocumentDB cluster parameter group as a part of the upgrade request, the in-place major version upgrade will automatically reboot the cluster to apply the new parameter group. + @@ -104 +76,0 @@ If you associate an Amazon DocumentDB cluster parameter group as a part of the u - 2. Ensure that you’ve satisfied the prerequisites for an in-place major version upgrade as mentioned in the Prerequisites and limitations section. @@ -106 +77,0 @@ If you associate an Amazon DocumentDB cluster parameter group as a part of the u - 3. Create a manual snapshot. @@ -108 +78,0 @@ If you associate an Amazon DocumentDB cluster parameter group as a part of the u -The upgrade process creates a snapshot of your database cluster during upgrading. It is strongly recommended to create your own manual snapshot before the upgrade process. See [Creating a manual cluster snapshot](./backup_restore-create_manual_cluster_snapshot.html). @@ -110 +80 @@ The upgrade process creates a snapshot of your database cluster during upgrading -###### Note +## Best practices @@ -112 +82 @@ The upgrade process creates a snapshot of your database cluster during upgrading -The auto snapshot created by the upgrade process will not be automatically deleted after the in-place major version upgrade has completed. This snapshot will not incur any charges as long as it is within the retention period. You can choose to delete this snapshot once you have verified a successful upgrade of your cluster. +### Before upgrade — testing with a clone @@ -114 +84 @@ The auto snapshot created by the upgrade process will not be automatically delet -The snapshot is named as `preupgrade-<name>-<version>-<timestamp>`. + 1. Use [Cloning a volume for an Amazon DocumentDB cluster](./db-cluster-cloning.html) to create a clone of your cluster. You will not incur storage costs unless you modify data on the clone. @@ -116 +86 @@ The snapshot is named as `preupgrade-<name>-<version>-<timestamp>`. - + 2. Match the instance count of the clone to the target cluster for a realistic time estimate. @@ -118 +88 @@ The snapshot is named as `preupgrade-<name>-<version>-<timestamp>`. - 4. Check if you already scheduled an in-place major version upgrade of your cluster. + 3. Perform the MVU on the clone and fully test for functional differences. @@ -120 +90 @@ The snapshot is named as `preupgrade-<name>-<version>-<timestamp>`. -If you have modified the cluster and selected to apply it in the next maintenance window, in-place major version upgrade schedule will not be visible on console, but you can view it in the CLI. You can run the [`describe-db-clusters`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-db-clusters.html) command to check if an in-place major version upgrade is already scheduled: + 4. Check if an upgrade is already scheduled by running [`describe-db-clusters`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-db-clusters.html) and looking for `PendingModifiedValues.EngineVersion`. If you have modified the cluster and selected to apply it in the next maintenance window, the schedule will not be visible in the console but you can view it in the AWS CLI: @@ -122 +92 @@ If you have modified the cluster and selected to apply it in the next maintenanc - aws docdb describe-db-cluster \ + aws docdb describe-db-clusters \ @@ -126,4 +95,0 @@ If you have modified the cluster and selected to apply it in the next maintenanc -In the example above, replace each `user input placeholder` with your cluster's information. - -The command returns the following output: - @@ -134 +100,3 @@ The command returns the following output: - 5. Perform multiple dry-runs using volume clone in lower environments to test the cluster post in-place major version upgrade on any execution plan and functional differences. We recommend cloning with the same number and size of instances to get a better estimate of in-place major version upgrade run time. For more information, see [Cloning a volume for an Amazon DocumentDB cluster](./db-cluster-cloning.html). + 5. If testing is successful, proceed with the upgrade on your production cluster. + + @@ -136 +103,0 @@ The command returns the following output: - 6. If the previous step is successful, proceed with in-place major version upgrade on the production cluster. @@ -137,0 +105 @@ The command returns the following output: +### During the upgrade @@ -138,0 +107 @@ The command returns the following output: +You can monitor progress of your in-place major version upgrade by subscribing to cluster maintenance events. When the upgrade completes, you will receive the "Database cluster major version has been upgraded" event. This and other events occurring during the upgrade appear in the **Events and Tags** section of the cluster detail page in the Amazon DocumentDB console. The cluster status then changes from `upgrading` to `available`. @@ -139,0 +109 @@ The command returns the following output: +The following events are generated during the upgrade: @@ -141 +111 @@ The command returns the following output: -### During an in-place major version upgrade + 1. Database cluster engine major version upgrade started. Cluster remains online. @@ -143 +113 @@ The command returns the following output: -You can monitor progress of your in-place major version upgrade by subscribing to cluster maintenance events. When the upgrade completes, you will receive the “Database cluster major version has been upgraded” event. This and other events occurring during the upgrade appear in the ‘Events and Tags’ section of the cluster detail page in the Amazon DocumentDB console. The cluster status then changes from ‘upgrading’ to ‘available’. + 2. Upgrade preparation in progress: Starting online upgrade prechecks. @@ -145 +115 @@ You can monitor progress of your in-place major version upgrade by subscribing t -From CLI, you can run `aws docdb create-event-subscription` to create events and `aws docdb describe-events` to monitor progress. You can also setup event notifications for the above events to Amazon SNS as the target to be notified via email, push messages, and other methods. For more information, see [Subscribing to Amazon DocumentDB events](./event-subscriptions.subscribe.html). + 3. Upgrade preparation in progress: Completed online upgrade prechecks. @@ -147 +117 @@ From CLI, you can run `aws docdb create-event-subscription` to create events and -In-place major version upgrade generates the following events during the upgrade: + 4. Taking database cluster offline while the primary instance completes the patch/upgrade process. @@ -149 +119 @@ In-place major version upgrade generates the following events during the upgrade - * Upgrade in progress: Creating pre-upgrade snapshot [preupgrade-<cluster-name>-<timestamp>] + 5. Upgrade preparation in progress: Starting offline upgrade prechecks. @@ -151 +121 @@ In-place major version upgrade generates the following events during the upgrade - * Upgrade in progress: Cloning volume. + 6. Upgrade preparation in progress: Completed offline upgrade prechecks. @@ -153 +123 @@ In-place major version upgrade generates the following events during the upgrade - * Upgrade in progress: Upgrading writer. + 7. Upgrade in progress: Creating pre-upgrade snapshot [preupgrade-<cluster-name>-<version-from>-to-<version-to>-<timestamp>]. @@ -155 +125 @@ In-place major version upgrade generates the following events during the upgrade - * Upgrade in progress: Upgrading readers. + 8. Upgrade in progress: Cloning volume. @@ -157 +127 @@ In-place major version upgrade generates the following events during the upgrade - * Database cluster major version has been upgraded. + 9. Upgrade in progress: Upgrading writer. @@ -158,0 +129 @@ In-place major version upgrade generates the following events during the upgrade + 10. Upgrade in progress: Upgrading readers. @@ -159,0 +131 @@ In-place major version upgrade generates the following events during the upgrade + 11. Database cluster engine major version has been upgraded. @@ -162 +134,3 @@ In-place major version upgrade generates the following events during the upgrade -Events are also visible on the console under the **Events** page: + +