Assess a MongoDB installation and plan for migration to Azure Cosmos DB for MongoDB vCore

Carry out up-front planning tasks and make critical decisions before migrating your data to Azure Cosmos DB for MongoDB vCore. These decisions make your migration process run smoothly.

Prerequisites

• An existing Azure Cosmos DB for MongoDB vCore cluster.
  • If you don't have an Azure subscription, create an account for free.
  • If you have an existing Azure subscription, create a new Azure Cosmos DB for MongoDB vCore cluster.
• An existing MongoDB installation.

Assess the compatibility and readiness of your resources for migration

Before planning your migration, assess the state of your existing MongoDB resources to help plan for migration. Use the Azure Cosmos DB Migration extension in VS Code to assess the compatibility and readiness of your workloads while planning the migration from MongoDB to Azure Cosmos DB for MongoDB vCore. The end-to-end assessment and find out the actions that you need to take to seamlessly run your workloads on Azure Cosmos DB. The assessment report presents findings at the account, database, and collection levels, each marked as Critical, Warning, or Informational based on severity to aid prioritization. The report includes:

• Unsupported Features and Syntax: It flags unsupported MongoDB features, commands, query syntax, and index types, with usage frequency to prioritize fixes.

• Resource-Specific Recommendations: Each finding includes the affected resource name, actionable recommendations, and relevant technical details for remediation.

• Environment Overview: Summarizes key aspects of the source MongoDB environment—such as version, license, instance type, and stats for databases and collections.

• Compatibility and Platform Constraints: Details Cosmos DB-specific quotas, limits, and potential shard key incompatibilities for sharded workloads.

Run an Assessment

1. To get started, install the Azure Cosmos DB Migration extension in VS Code. This will automatically install its prerequisite, the DocumentDB for VS Code extension.

2. Open the DocumentDB for VS Code extension.

3. Add the MongoDB server you want to assess for migration to the Document DB Connections list.

4. Expand the selected connection, then Right-click and choose Data Migration....

5. From the command palette, select Pre-Migration Assessment for Azure Cosmos DB for MongoDB.

6. The assessment wizard guides you through three steps. In the Start Validation step, select Run Validation to verify credentials, prerequisites, and connectivity before proceeding.

   Important

   To perform an assessment, the connected MongoDB user must have the readAnyDatabase and clusterMonitor roles assigned on the source instance.

7. In the Fill in Assessment Details step, provide the necessary inputs:

   • Enter a title in the Assessment name field.
   • Select vCore from the Offering dropdown.
   • Provide the path to MongoDB logs.

   Tip

   While optional, specifying the logs path allows for more detailed findings at the collection level. If omitted, the tool relies on data from the serverStatus command, which only reflects feature usage since the last restart. Allow sufficient time to pass after the last server restart for an accurate workload assessment.

   • Provide the path to data assessment logs.

   Tip

   Though optional, supplying data assessment logs enhances workload insights. These logs are generated by scanning data and reading verbose logs. The data assessment runs independently as a CLI before initiating the migration assessment, and the resulting JSON is used here. Download the data assessment CLI here.

8. Select Start Assessment to begin the assessment process.

9. In the Get Your Report step, wait for the assessment to complete. The duration depends on the size of your source server.

10. Once the assessment is finished, select Download Report to retrieve the HTML report.

View Past Assessments

Reviewing previous assessments can be valuable. Use the View Past Assessments tab to access detailed historical reports. The assessment list includes all assessments initiated on the current machine for the selected connection.

FAQ

How do I proceed if the "Run Validation" step fails?

Check the error message displayed in the extension to determine the cause of the validation failure. Common issues include an inability to connect to the MongoDB endpoint or insufficient user privileges on the connected server.

To run an assessment, ensure that the connected MongoDB user has the readAnyDatabase and clusterMonitor roles assigned on the source instance.

Use grantRolesToUser to assign the necessary roles to the current user.

How can I view collection and database names in "Feature Compatibility" assessments?

The serverStatus command is used for feature compatibility assessments. However, this command doesn't provide database or collection names, which prevents the extension from reporting them.

For more detailed assessment results, rerun the assessment and specify the folder containing MongoDB logs in the Log Folder Path field.

How do I configure my source server firewall to prevent connectivity issues?

Ensure that the source MongoDB instance allows incoming connections from your machine.

How many assessments can I run concurrently?

There's no limit to the number of assessments you can run at the same time. However, running multiple assessments in parallel strain the compute resources on both your machine and the source server, potentially affecting performance.

What information is included in an assessment report?

The report begins with key details about the assessment, including a summary of the source MongoDB environment. This section covers the source MongoDB version, license type, and instance type. It also lists the assessed databases and collections, along with their assessment summaries and migration readiness.

Findings are categorized into Critical, Warning, and Informational, helping you prioritize them based on importance.

The assessment includes checks for:

What type of logs does the extension generate?

The extension records errors, warnings, and other diagnostic logs in the default log directory:

• Windows - C:\Users\<username>\.dmamongo\logs\
• Linux - ~/.dmamongo/logs
• macOS - /Users/<username>/.dmamongo/logs

Capacity planning

Cluster Tier

Begin with a cluster tier that aligns with your source database configurations. Conduct load and performance tests to determine the optimal balance between cost and performance.

Storage Tier

Ensure your target account is provisioned with adequate storage to meet your data requirements during and after migration. Start by migrating a small dataset to assess storage consumption, then scale the estimate based on the total data size to determine the necessary storage allocation. Reserve extra space to accommodate incoming data and future growth.

Next step