Migrate from Azure Cosmos DB for MongoDB to Azure DocumentDB

  • Applies to: MongoDB

Important

Are you looking to migrate an existing MongoDB application or use MongoDB Query Language (MQL) features? Consider Azure DocumentDB.

Are you looking for a database solution for high-scale scenarios with a 99.999% availability service level agreement (SLA), instant autoscale, and automatic failover across multiple regions? Consider Azure Cosmos DB for NoSQL.

In this guide, you take an existing collection and migrate it from Azure Cosmos DB for MongoDB to Azure DocumentDB using the tooling built-in to the service and Azure portal.

Prerequisites

  • An Azure subscription

    • If you don't have an Azure subscription, create a free account before you begin.

  • A target Azure DocumentDB cluster

  • An Azure Key Vault account (not required if your Azure DocumentDB supports Microsoft Entra ID authentication)

Configure managed identity for your source account

  1. Sign in to the Azure portal (https://portal.azure.com).

  2. Navigate to your source Azure Cosmos DB for MongoDB account.

  3. In your source account, navigate to Settings > Identity.

  4. Turn on the system-assigned managed identity for your source account by setting the Status option to On. Note down the value of the Object (principal) ID to use later in this guide.

    Screenshot of the Azure portal Identity settings page showing system-assigned managed identity configuration options.

    Tip

    If you're using a user-assigned managed identity instead, ensure that at least one user-assigned managed identity is assigned to the source account.

  5. Run the command to update your source account to use the preferred identity mechanism as the default identity.

    az cosmosdb update \
    --resource-group "<resource-group-name>" \
    --name "<source-account-name>" \
    --default-identity "SystemAssignedIdentity"

    Tip

    If you're using a user-assigned managed identity instead, run this command:

    az cosmosdb update \
    --resource-group "<resource-group-name>" \
    --name "<source-account-name>" \
    --default-identity "UserAssignedIdentity=<fully-qualified-resource-id-of-user-assigned-managed-identity>"

Set up Azure Key Vault (Optional)

Tip

The migration job can use the target DocumentDB's native authentication credentials or use Microsoft Entra ID to connect. You don't need to set up Azure Key Vault if you're planning to use Microsoft Entra ID authentication.

When using DocumentDB's native authentication, the migration job uses an Azure Key Vault to retrieve the target authentication credentials.

To store the credentials in your existing key vault.

  1. Navigate to your existing key vault.

  2. If the Key Vault uses the Role-Based Access Control (RBAC) permission model, select the Access Control (IAM) option in the resource menu and assign the Key Vault Secret User role to the principal ID (object ID) of the managed identity used for your source account. Otherwise, use the Access policies option in the resource menu to create an access policy with Get and List Secret permissions, then assign it to the principal ID (object ID).

  3. Navigate to Objects > Secrets, select Generate/Import to create a new secret. Use these values for your secret:

    Description
    Name Secret names are used to identify the secret and can only contain alphanumeric characters and dashes. This value is eventually used in the migration job's Secret Name field.
    Secret value Paste the native authentication credentials for your Azure Cosmos DB for MongoDB target cluster here.

    Note

    Ensure you use the native DocumentDB connection string as the Secret value.

  4. In your newly created secret, gather the value of Vault URI. This value is eventually used in the migration job's Vault URI field.

Create migration job

First, create a migration job with the configuration required to start migrating data to the target cluster.

  1. Sign in to the Azure portal (https://portal.azure.com).

  2. Navigate to your Azure Cosmos DB for MongoDB account again.

  3. On the account page, select Migrate to DocumentDB from the resource menu.

    Screenshot of home page in the migration to DocumentDB workflow.

  4. Select Start a new migration job.

Select migration mode

The Select Migration Mode section is used to provide the migration mode that's most appropriate for your migration needs.

  1. Select the appropriate mode from these options:

    Description
    Offline Offline migration captures a snapshot of the collection at the beginning, offering a simpler and predictable approach. It works well when using a static copy of the collection is acceptable, and real-time updates aren't essential. Use this option for nonproduction migrations.
    Online Online migration copies collection data, ensuring updates are also replicated during the process. This method is advantageous with minimal downtime, allowing continuous operations for business continuity. Use this option when ongoing operations are crucial, and reducing downtime is a priority.

    Screenshot of the mode selection options for a migration job.

    Note

    Continuous Backup is a prerequisite for online migrations. For more information, see continuous backup.

  2. Select Next.

Configure target migration credentials

The Select Target Account section is used to provide the connection details to the target Azure DocumentDB cluster. The migration job can use the target DocumentDB's native authentication credentials or use Microsoft Entra ID to connect.

As a security best practice, Microsoft Entra ID is the preferred authentication mechanism.

Configure using DocumentDB's native authentication

  1. Set the Vault URI and Secret Name fields to the values you recorded earlier in this guide.

    Screenshot of target selection section.

  2. Select Next.

Configure using Microsoft Entra ID authentication

  1. Make sure the managed identity has been assigned read-write privileges on the target DocumentDB cluster.
  2. Set the Azure DocumentDB (with MongoDB Compatibility) account name field value.

Update target firewall

The Update Target Firewall section is used to make sure that the target Azure DocumentDB cluster's firewall doesn't block the migration job requests.

  1. Observe the IP Address in this step.

    Screenshot of the target firewall check section and the source account's IP address.

  2. Navigate to your target Azure DocumentDB cluster using another browser window or tab.

  3. Select Networking in the Settings section of the resource menu.

  4. Add a rule to allow access to the migration job's IP address. For more information, see manage cluster-level firewall rules.

  5. Navigate back to the browser window or tab with the migration job configuration steps.

  6. Select Next.

Note

If network security is enabled on your Azure Key Vault, ensure the same IP is added to the Azure Key Vault Firewall as well.

Configure and start job

Use the Select Collections and Confirm & Submit sections to finalize your job's configuration.

  1. Select the collections you plan to migrate in the Select Collections section.

    Screenshot of the section to select collections to migrate.

  2. Select Next.

  3. Review the job configuration and provide a unique job name.

    Important

    1. The migration job doesn't transfer the indexes to the target collections. Before proceeding, use this sample migration script to create the indexes on the target collections. Once the indexes are ready, select the checkbox.
    2. The migration job doesn't support changing the shard key. If you need a different shard key, migrate the data as an unsharded collection. Once the migration is complete, shard the collection on target using the desired shard key.

  4. Select Submit to create and start the job.

Monitor migration jobs

Once a job is submitted, you can monitor the status of the newly created job along with other pending or completed jobs.

  1. Navigate to your source Azure Cosmos DB for MongoDB account.

  2. On the account page, select Migrate to DocumentDB from the resource menu.

  3. Select Monitor existing migration job(s).

    Screenshot of the page where existing migration jobs can be monitored or modified.

  4. All migration jobs created for the current source account are listed.

  5. Optionally, to change the status of a job, select the context menu (..) corresponding to the specific job. Options include:

    Option Description
    Pause Temporarily pause a currently running job
    Resume Resume a paused job
    Cancel Permanently cancel a currently running job
    Cutover Finalize the migration when the source and target are synced

    Note

    The cutover option is only applicable to online migrations. Once cutover is completed, the sync between the source account and target cluster is terminated. After performing a cutover, you should update the credentials in your client application to target the new Azure DocumentDB cluster.

  • Last updated on