AWS documentdb documentation change
Summary
Updated product name references from 'DocumentDB' to 'Amazon DocumentDB' throughout the document for branding consistency
Security assessment
Changes are branding/naming convention updates without any mention of vulnerabilities, security patches, or access control modifications. The updates standardize product naming but do not alter security controls or introduce new security features.
Diff
diff --git a/documentdb/latest/developerguide/docdb-migration-runbook.md b/documentdb/latest/developerguide/docdb-migration-runbook.md index 04bdec1ff..2f0e81d4b 100644 --- a//documentdb/latest/developerguide/docdb-migration-runbook.md +++ b//documentdb/latest/developerguide/docdb-migration-runbook.md @@ -11 +11 @@ This runbook provides a comprehensive guide for migrating a MongoDB database to -Given the differences in implementation and supported features between MongoDB and DocumentDB, this runbook emphasizes a structured and systematic approach. It outlines essential pre-migration assessments, highlights compatibility considerations, and details the key tasks required to ensure a successful migration with minimal disruption. +Given the differences in implementation and supported features between MongoDB and Amazon DocumentDB, this runbook emphasizes a structured and systematic approach. It outlines essential pre-migration assessments, highlights compatibility considerations, and details the key tasks required to ensure a successful migration with minimal disruption. @@ -15 +15 @@ The runbook is organized into the following topics: - * **Compatibility** — Understand the supported MongoDB features and data types in DocumentDB, and identify potential incompatibilities. + * **Compatibility** — Understand the supported MongoDB features and data types in Amazon DocumentDB, and identify potential incompatibilities. @@ -19 +19 @@ The runbook is organized into the following topics: - * **Index migration** — Analyze strategies for extracting and transforming MongoDB indexes for optimal performance in DocumentDB. + * **Index migration** — Analyze strategies for extracting and transforming MongoDB indexes for optimal performance in Amazon DocumentDB. @@ -21 +21 @@ The runbook is organized into the following topics: - * **User migration** — Detail the approach for migrating database users, roles, and access controls to DocumentDB. + * **User migration** — Detail the approach for migrating database users, roles, and access controls to Amazon DocumentDB. @@ -40 +40 @@ By following the guidance in this runbook, teams can ensure a smooth, secure, an - * DocumentDB compatibility assessment tool + * Amazon DocumentDB compatibility assessment tool @@ -47 +47 @@ When migrating from MongoDB to Amazon DocumentDB, a thorough initial assessment -Since DocumentDB is compatible with MongoDB 3.6, 4.0, and 5.0 API's, applications using newer MongoDB-specific features may require refactoring. Critical areas to evaluate include sharding mechanisms(DocumentDB uses a different approach), transaction implementations, change streams functionality, and index types (particularly sparse and partial indexes). +Since Amazon DocumentDB is compatible with MongoDB 3.6, 4.0, and 5.0 API's, applications using newer MongoDB-specific features may require refactoring. Critical areas to evaluate include sharding mechanisms(Amazon DocumentDB uses a different approach), transaction implementations, change streams functionality, and index types (particularly sparse and partial indexes). @@ -49 +49 @@ Since DocumentDB is compatible with MongoDB 3.6, 4.0, and 5.0 API's, application -Performance characteristics also differ, with DocumentDB optimized for enterprise workloads with predictable performance. Testing should involve running representative workloads against both systems to identify query patterns that might need optimization. +Performance characteristics also differ, with Amazon DocumentDB optimized for enterprise workloads with predictable performance. Testing should involve running representative workloads against both systems to identify query patterns that might need optimization. @@ -96 +96 @@ For a comprehensive overview of Amazon DocumentDB's capabilities, refer to the [ -DocumentDB does not support all the indexes offered by MongoDB. We provide a free [index tool](https://github.com/awslabs/amazon-documentdb-tools/blob/master/index-tool/README.md) to check the compatibility. We recommend running the index tool to assess incompatibility and plan workarounds accordingly. +Amazon DocumentDB does not support all the indexes offered by MongoDB. We provide a free [index tool](https://github.com/awslabs/amazon-documentdb-tools/blob/master/index-tool/README.md) to check the compatibility. We recommend running the index tool to assess incompatibility and plan workarounds accordingly. @@ -98 +98 @@ DocumentDB does not support all the indexes offered by MongoDB. We provide a fre -### DocumentDB compatibility assessment tool +### Amazon DocumentDB compatibility assessment tool @@ -100 +100 @@ DocumentDB does not support all the indexes offered by MongoDB. We provide a fre -The [MongoDB to DocumentDB Compatibility Tool](https://github.com/awslabs/amazon-documentdb-tools/blob/master/index-tool/README.md) is an open-source utility available on GitHub that helps evaluate MongoDB workload compatibility with Amazon DocumentDB by analyzing MongoDB logs or application source code. +The [MongoDB to Amazon DocumentDB Compatibility Tool](https://github.com/awslabs/amazon-documentdb-tools/blob/master/compat-tool/README.md) is an open-source utility available on GitHub that helps evaluate MongoDB workload compatibility with Amazon DocumentDB by analyzing MongoDB logs or application source code. @@ -148 +148 @@ The [MongoDB to DocumentDB Compatibility Tool](https://github.com/awslabs/amazon - * Detects client-side logic that might be affected by DocumentDB differences + * Detects client-side logic that might be affected by Amazon DocumentDB differences @@ -166,0 +167,2 @@ For best results, we recommend using both assessment methods when possible to ge +Migrating from MongoDB to Amazon DocumentDB requires a thorough understanding of the existing database workload. Workload discovery is the process of analyzing your database usage patterns, data structures, query performance, and operational dependencies to ensure a seamless transition with minimal disruption. This section outlines the key steps involved in workload discovery to facilitate an effective migration from MongoDB to Amazon DocumentDB. + @@ -182,2 +183,0 @@ For best results, we recommend using both assessment methods when possible to ge -Migrating from MongoDB to Amazon DocumentDB requires a thorough understanding of the existing database workload. Workload discovery is the process of analyzing your database usage patterns, data structures, query performance, and operational dependencies to ensure a seamless transition with minimal disruption. This section outlines the key steps involved in workload discovery to facilitate an effective migration from MongoDB to DocumentDB. - @@ -188 +188 @@ Before migration, it is crucial to evaluate the current MongoDB environment, inc - * **Cluster architecture** — Identify the number of nodes, replica sets, and sharding configurations. When migrating from MongoDB to DocumentDB, understanding your MongoDB sharding configuration is important because DocumentDB does not support user-controlled sharding. Applications designed for a sharded MongoDB environment will need architectural changes, as DocumentDB uses a different scaling approach with its storage-based architecture. You'll need to adapt your data distribution strategy and possibly consolidate sharded collections when moving to DocumentDB. + * **Cluster architecture** — Identify the number of nodes, replica sets, and sharding configurations. When migrating from MongoDB to Amazon DocumentDB, understanding your MongoDB sharding configuration is important because Amazon DocumentDB does not support user-controlled sharding. Applications designed for a sharded MongoDB environment will need architectural changes, as Amazon DocumentDB uses a different scaling approach with its storage-based architecture. You'll need to adapt your data distribution strategy and possibly consolidate sharded collections when moving to Amazon DocumentDB. @@ -205 +205 @@ Although Amazon DocumentDB is MongoDB-compatible, there are differences in suppo - * **Schema design** — Ensure that document structures, embedded documents, and references align with [Amazon DocumentDB’s best practices](chrome-extension://efaidnbmnnnibpcajpcglclefindmkaj/https://d1.awsstatic.com/product-marketing/Data%20modeling%20with%20Amazon%20DocumentDB.pdf?). + * **Schema design** — Ensure that document structures, embedded documents, and references align with [Amazon DocumentDB’s best practices](https://d1.awsstatic.com/product-marketing/Data%20modeling%20with%20Amazon%20DocumentDB.pdf). @@ -218 +218 @@ Understanding query behavior helps optimize migration and post-migration perform - * **Index usage** — Assess whether indexes are effectively utilized or need optimization in Amazon DocumentDB. To assess index usage and optimize performance in DocumentDB, use the `$indexStats` aggregation pipeline stage combined with the `explain()` method on your critical queries. Start by running `db.collection.aggregate([{$indexStats{}}])` to identify which indexes are being used. You can do more detailed analysis by executing you most frequent queries with `explainPlan`. + * **Index usage** — Assess whether indexes are effectively utilized or need optimization in Amazon DocumentDB. To assess index usage and optimize performance in Amazon DocumentDB, use the `$indexStats` aggregation pipeline stage combined with the `explain()` method on your critical queries. Start by running `db.collection.aggregate([{$indexStats{}}])` to identify which indexes are being used. You can do more detailed analysis by executing you most frequent queries with `explainPlan`. @@ -229 +229 @@ Understanding query behavior helps optimize migration and post-migration perform - * **MongoDB RBAC to DocumentDB IAM and RBAC** — Map MongoDB's role-based access control users and roles to AWS Identity and Access Management (IAM) policies and DocumentDB SCRAM authentication users. + * **MongoDB RBAC to Amazon DocumentDB IAM and RBAC** — Map MongoDB's role-based access control users and roles to AWS Identity and Access Management (IAM) policies and Amazon DocumentDB SCRAM authentication users. @@ -231 +231 @@ Understanding query behavior helps optimize migration and post-migration perform - * **User migration strategy** — Plan for migrating database users, custom roles, and privileges to DocumentDB's supported authentication mechanisms. + * **User migration strategy** — Plan for migrating database users, custom roles, and privileges to Amazon DocumentDB's supported authentication mechanisms. @@ -233 +233 @@ Understanding query behavior helps optimize migration and post-migration perform - * **Privilege differences** — Identify MongoDB privileges without direct DocumentDB equivalents (for example, cluster administration roles). + * **Privilege differences** — Identify MongoDB privileges without direct Amazon DocumentDB equivalents (for example, cluster administration roles). @@ -235 +235 @@ Understanding query behavior helps optimize migration and post-migration perform - * **Application authentication** — Update connection strings and credential management for DocumentDB's password policies. You can use secrets manager to store your credentials and rotate passwords. + * **Application authentication** — Update connection strings and credential management for Amazon DocumentDB's password policies. You can use secrets manager to store your credentials and rotate passwords. @@ -258 +258 @@ To maintain system reliability, workload discovery should also include: - * **AWS Backup integration** — Leverage AWS Backup for centralized backup management across AWS services including DocumentDB. + * **AWS Backup integration** — Leverage AWS Backup for centralized backup management across AWS services including Amazon DocumentDB. @@ -260 +260 @@ To maintain system reliability, workload discovery should also include: - * **CloudWatch metrics** — Map MongoDB monitoring metrics to DocumentDB CloudWatch metrics for CPU, memory, connections, and storage. + * **CloudWatch metrics** — Map MongoDB monitoring metrics to Amazon DocumentDB CloudWatch metrics for CPU, memory, connections, and storage. @@ -264 +264 @@ To maintain system reliability, workload discovery should also include: - * **Profiler** — Configure DocumentDB profiler to capture slow-running operations (similar to MongoDB's profiler but with DocumentDB-specific settings). + * **Profiler** — Configure Amazon DocumentDB profiler to capture slow-running operations (similar to MongoDB's profiler but with Amazon DocumentDB-specific settings). @@ -270 +270 @@ To maintain system reliability, workload discovery should also include: - * **CloudWatch Events** — Set up event-driven monitoring for DocumentDB cluster events. + * **CloudWatch Events** — Set up event-driven monitoring for Amazon DocumentDB cluster events. @@ -285 +285 @@ To maintain system reliability, workload discovery should also include: -Migrating from MongoDB to Amazon DocumentDB involves transferring not just data but also indexes to maintain query performance and optimize database operations. This section outlines the detailed step-by-step process for migrating indexes from MongoDB to DocumentDB while ensuring compatibility and efficiency. +Migrating from MongoDB to Amazon DocumentDB involves transferring not just data but also indexes to maintain query performance and optimize database operations. This section outlines the detailed step-by-step process for migrating indexes from MongoDB to Amazon DocumentDB while ensuring compatibility and efficiency. @@ -287 +287 @@ Migrating from MongoDB to Amazon DocumentDB involves transferring not just data -### Using the DocumentDB index tool +### Using the Amazon DocumentDB index tool @@ -304 +304 @@ Migrating from MongoDB to Amazon DocumentDB involves transferring not just data -**Export indexes from DocumentDB (if migrating from DocumentDB)** +**Export indexes from Amazon DocumentDB (if migrating from Amazon DocumentDB)** @@ -327 +327 @@ Migrating from MongoDB to Amazon DocumentDB involves transferring not just data -Migrating users from MongoDB to Amazon DocumentDB is essential for maintaining access control, authentication, and database security. This section outlines detailed steps to successfully migrate MongoDB users while preserving their roles and permissions using the DocumentDB export user tool. +Migrating users from MongoDB to Amazon DocumentDB is essential for maintaining access control, authentication, and database security. This section outlines detailed steps to successfully migrate MongoDB users while preserving their roles and permissions using the Amazon DocumentDB export user tool. @@ -329 +329 @@ Migrating users from MongoDB to Amazon DocumentDB is essential for maintaining a -### Using DocumentDB export users tool +### Using Amazon DocumentDB export users tool @@ -331 +331 @@ Migrating users from MongoDB to Amazon DocumentDB is essential for maintaining a -The [`Export Users tool`](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/export-users) exports users and roles from MongoDB or DocumentDB to JavaScript files, which can then be used to recreate them in another cluster. +The [`Export Users tool`](https://github.com/awslabs/amazon-documentdb-tools/tree/master/migration/export-users) exports users and roles from MongoDB or Amazon DocumentDB to JavaScript files, which can then be used to recreate them in another cluster. @@ -367 +367 @@ The [`Export Users tool`](https://github.com/awslabs/amazon-documentdb-tools/tre -**Step 3: Restore Custom Roles to DocumentDB** +**Step 3: Restore Custom Roles to Amazon DocumentDB** @@ -378 +378 @@ The [`Export Users tool`](https://github.com/awslabs/amazon-documentdb-tools/tre -**Step 4: Restore Users to DocumentDB** +**Step 4: Restore Users to Amazon DocumentDB** @@ -404 +404 @@ The [`Export Users tool`](https://github.com/awslabs/amazon-documentdb-tools/tre -This method provides a secure and flexible approach to migrating users and roles from MongoDB to DocumentDB while allowing for password resets during the migration process. +This method provides a secure and flexible approach to migrating users and roles from MongoDB to Amazon DocumentDB while allowing for password resets during the migration process. @@ -416 +416 @@ This method provides a secure and flexible approach to migrating users and roles - * Prepare a DocumentDB cluster + * Prepare an Amazon DocumentDB cluster @@ -429 +429 @@ This method provides a secure and flexible approach to migrating users and roles -This section provides detailed steps to perform an online migration from MongoDB to Amazon DocumentDB using AWS DMS to enable minimal downtime and continuous replication. To begin, you set up a DocumentDB cluster as the target and ensure your MongoDB instance is properly configured as the source, typically requiring replica set mode for change data capture. Next, you create a DMS replication instance and define source and target endpoints with the necessary connection details. After validating the endpoints, you configure and start a migration task that can include full data load, ongoing replication, or both. +This section provides detailed steps to perform an online migration from MongoDB to Amazon DocumentDB using AWS DMS to enable minimal downtime and continuous replication. To begin, you set up an Amazon DocumentDB cluster as the target and ensure your MongoDB instance is properly configured as the source, typically requiring replica set mode for change data capture. Next, you create a DMS replication instance and define source and target endpoints with the necessary connection details. After validating the endpoints, you configure and start a migration task that can include full data load, ongoing replication, or both. @@ -431 +431 @@ This section provides detailed steps to perform an online migration from MongoDB -#### Configure target (DocumentDB) +#### Configure target (Amazon DocumentDB) @@ -435 +435 @@ This section provides detailed steps to perform an online migration from MongoDB -If you already have provisioned a DocumentDB cluster to migrate to, you can skip this step. +If you already have provisioned a Amazon DocumentDB cluster to migrate to, you can skip this step. @@ -441 +441 @@ See the AWS Management Console or AWS CLI procedures in [Creating Amazon Documen -**Create a DocumentDB cluster** +**Create an Amazon DocumentDB cluster** @@ -445 +445 @@ See the AWS Management Console or AWS CLI procedures in [Creating Amazon Documen -While there are other procedures for creating a DocumentDB cluster in this guide, the steps in this section apply specifically to the task of migrating large amounts of data to a new cluster. +While there are other procedures for creating an Amazon DocumentDB cluster in this guide, the steps in this section apply specifically to the task of migrating large amounts of data to a new cluster. @@ -483 +483 @@ As a best practice, we recommend choosing as big an instance as you are able to - 9. In the **Network settings** section, choose a VPC and subnet group, and then configure the VPC security group. Make sure your DocumentDB security group allows inbound connection from the DMS instance’s security group by updating inbound rules. + 9. In the **Network settings** section, choose a VPC and subnet group, and then configure the VPC security group. Make sure your Amazon DocumentDB security group allows inbound connection from the DMS instance’s security group by updating inbound rules. @@ -498 +498 @@ The deployment time typically takes between 10 an 15 minutes, -MongoDB and DocumentDB can both serve as migration sources, depending on your scenario: +MongoDB and Amazon DocumentDB can both serve as migration sources, depending on your scenario: @@ -502 +502 @@ MongoDB and DocumentDB can both serve as migration sources, depending on your sc - * **DocumentDB as source** — Typically used for cross-region replication, version upgrades, or migrating to other database services like MongoDB Atlas. Requires enabling change streams by setting the `change_stream_log_retention_duration` parameter in the cluster parameter group to capture ongoing changes during migration. Make sure your `change_stream_log_retention_duration` setting is large enough to cover the time needed to complete the Full Load. + * **Amazon DocumentDB as source** — Typically used for cross-region replication, version upgrades, or migrating to other database services like MongoDB Atlas. Requires [Enabling change streams](./change_streams.html#change_streams-enabling) by setting the `change_stream_log_retention_duration` parameter in the cluster parameter group to capture ongoing changes during migration. Make sure your `change_stream_log_retention_duration` setting is large enough to cover the time needed to complete the Full Load. @@ -563 +563 @@ When configuring network connectivity for MongoDB to DMS migration: -**DocumentDB source** +**Amazon DocumentDB source** @@ -565 +565 @@ When configuring network connectivity for MongoDB to DMS migration: -Configure your source DocumentDB security group to allow inbound traffic from the DMS replication instance security group. +Configure your source Amazon DocumentDB security group to allow inbound traffic from the DMS replication instance security group. @@ -585 +585 @@ Configure your DMS infrastructure using the following steps: - * Choose the same VPC as DocumentDB. + * Choose the same VPC as Amazon DocumentDB. @@ -587 +587 @@ Configure your DMS infrastructure using the following steps: - * Ensure **Security groups** allow inbound traffic from source and DocumentDB. + * Ensure **Security groups** allow inbound traffic from source and Amazon DocumentDB. @@ -614 +614 @@ Configure your DMS infrastructure using the following steps: - * For **Server name** , enter **MongoDB-server**. + * For **Server name** , enter your `MongoDB server DNS name/IP address`. @@ -639 +639 @@ Configure your DMS infrastructure using the following steps: -**For a DocumentDB source** +**For an Amazon DocumentDB source** @@ -651 +651 @@ Configure your DMS infrastructure using the following steps: - * Choose **DocumentDB** as the **Source engine**. + * Choose **Amazon DocumentDB** as the **Source engine**. @@ -655 +655 @@ Configure your DMS infrastructure using the following steps: - * For **Server name** , enter **DocumentDB-server**. + * For **Server name** , enter your `source Amazon DocumentDB cluster endpoint`. @@ -657 +657 @@ Configure your DMS infrastructure using the following steps: - * For **Port** , enter **27017** (default DocumentDB port). + * For **Port** , enter **27017** (default Amazon DocumentDB port). @@ -659 +659 @@ Configure your DMS infrastructure using the following steps: - * For **SSL mode** , choose **verify-full** (recommended for DocumentDB). + * For **SSL mode** , choose **verify-full** (recommended for Amazon DocumentDB). @@ -667 +667 @@ Configure your DMS infrastructure using the following steps: - * **Username** and **Password** : Enter DocumentDB credentials. + * **Username** and **Password** : Enter Amazon DocumentDB credentials. @@ -678 +678 @@ Configure your DMS infrastructure using the following steps: -##### Create a target endpoint (DocumentDB) +##### Create a target endpoint (Amazon DocumentDB) @@ -690 +690 @@ Configure your DMS infrastructure using the following steps: - * Choose **DocumentDB** as the **Target engine**. + * Choose **Amazon DocumentDB** as the **Target engine**. @@ -694 +694 @@ Configure your DMS infrastructure using the following steps: - * If you choose **AWS Secrets Manager** , choose the secret where you store your DocumentDB credentials in the **Secret** field. + * If you choose **AWS Secrets Manager** , choose the secret where you store your Amazon DocumentDB credentials in the **Secret** field. @@ -698 +698 @@ Configure your DMS infrastructure using the following steps: - * For **Server name** , enter **DocumentDB-server**. + * For **Server name** , enter your `target Amazon DocumentDB cluster endpoint`. @@ -700 +700 @@ Configure your DMS infrastructure using the following steps: - * For **Port** , enter **27017** (default DocumentDB port). + * For **Port** , enter **27017** (default Amazon DocumentDB port). @@ -702 +702 @@ Configure your DMS infrastructure using the following steps: - * For **SSL mode** , choose **verify-full** (recommended for DocumentDB). + * For **SSL mode** , choose **verify-full** (recommended for Amazon DocumentDB). @@ -710 +710 @@ Configure your DMS infrastructure using the following steps: - * **Username** and **Password** : Enter DocumentDB credentials. + * **Username** and **Password** : Enter Amazon DocumentDB credentials. @@ -800 +800 @@ This section outlines the process to perform an offline migration from a self-ma -**Target DocumentDB requirements** +**Target Amazon DocumentDB requirements** @@ -804 +804 @@ This section outlines the process to perform an offline migration from a self-ma - * Ensure there is an EC2 instance in the same VPC as DocumentDB to facilitate the migration. + * Ensure there is an EC2 instance in the same VPC as Amazon DocumentDB to facilitate the migration. @@ -806 +806 @@ This section outlines the process to perform an offline migration from a self-ma - * Network connectivity must be available between your source environment and DocumentDB. + * Network connectivity must be available between your source environment and Amazon DocumentDB. @@ -810 +810 @@ This section outlines the process to perform an offline migration from a self-ma - * Appropriate IAM permissions must be configured to access DocumentDB, + * Appropriate IAM permissions must be configured to access Amazon DocumentDB, @@ -826 +826 @@ This section outlines the process to perform an offline migration from a self-ma -### Prepare a DocumentDB cluster +### Prepare an Amazon DocumentDB cluster @@ -828 +828 @@ This section outlines the process to perform an offline migration from a self-ma