Live Migrate (Pull) a MongoDB 6.0.17+ or 7.0.13+ Cluster into Atlas

Network Access

Configure network permissions for the following components:

Pre-Migration Validation

Before starting the following live migration procedure, Atlas runs validation checks on the source and destination clusters and verifies that:

• The source and destination cluster's MongoDB version is at least FCV 6.0.17+ and is matching, or at least FCV 7.0.13+ and is matching.

• The source cluster's database user has the correct permissions as described in Source Cluster Security.

• The source cluster does not contain the mongosync_reserved_for_internal_use metadata database. You must manually drop that database before starting the migration.

• The destination Atlas cluster must have no data. If the cluster has any data before you begin, you have the option to clear data on the destination cluster during the live migration process. Alternatively, you can manually delete the data on the destination cluster before starting the migration procedure.

Source Cluster Security

Various built-in roles provide sufficient privileges. For example:

For source replica set clusters, a MongoDB user must have the readAnyDatabase and backup roles.

For source sharded clusters a MongoDB user must have the readAnyDatabase, backup, and clusterMonitor roles.

To verify that the database user who will run the live migration process has these roles, run the db.getUser() command on the admin database. For example, for a replica set, run:

use admin
db.getUser("admin")
{
    "_id" : "admin.admin",
    "user" : "admin",
    "db" : "admin",
    "roles" : [
  {
    "role" : "backup",
    "db" : "admin"
  },
  {
    "role" : "readAnyDatabase",
    "db" : "admin"
  }
 ]
} ...

Specify the username and password to Atlas when prompted by the walk-through screen of the live migration procedure.

Atlas only supports SCRAM for connecting to source clusters that enforce authentication.

How MongoDB Secures its Live Migration Servers

In any pull-type live migration to Atlas, Atlas manages the server that runs the live migration and sends data from the source to the destination cluster.

MongoDB takes the following measures to protect the integrity and confidentiality of your data in transit to Atlas:

• MongoDB encrypts data in transit between the Atlas-managed live migration server and the destination cluster. If you require encryption for data in transit between the source cluster and the Atlas-managed migration server, configure TLS on your source cluster.

• MongoDB protects access to the Atlas-managed migration server instances as it protects access to any other parts of Atlas.

• In rare cases where intervention is required to investigate and restore critical services, MongoDB adheres to the principle of least privilege and authorizes only a small group of privileged users to access your Atlas clusters for a minimum limited time necessary to repair the critical issue. MongoDB requires MFA for these users to log in to Atlas clusters and to establish an SSH connection via the bastion host. Granting this type of privileged user access requires approval by MongoDB senior management. MongoDB doesn't allow access by any other MongoDB personnel to your MongoDB Atlas clusters.

• MongoDB allows use of privileged user accounts for privileged activities only. To perform non-privileged activities, privileged users must use a separate account. Privileged user accounts can't use shared credentials. Privileged user accounts must follow the password requirements described in Section 4.3.3 of the Atlas Security whitepaper.

• You can restrict access to your clusters by all MongoDB personnel, including privileged users, in Atlas. If you choose to restrict such access and MongoDB determines that access is necessary to resolve a support issue, MongoDB must first request your permission and you may then decide whether to temporarily restore privileged user access for up to 24 hours. You can revoke the temporary 24-hour access grant at any time. Enabling this restriction may result in increased time for the response and resolution of support issues and, as a result, may negatively impact the availability of your Atlas clusters.

• MongoDB reviews privileged user access authorization on a quarterly basis. Additionally, MongoDB revokes a privileged user's access when it is no longer needed, including within 24 hours of that privileged user changing roles or leaving the company. We also log any access by MongoDB personnel to your Atlas clusters, retain audit logs for at least six years, and include a timestamp, actor, action, and output. MongoDB uses a combination of automated and manual reviews to scan those audit logs.

To learn more about Atlas security, see the Atlas Security whitepaper. In particular, review the section "MongoDB Personnel Access to MongoDB Atlas Clusters".

Network Encryption

During pull live migrations, if the source cluster does not use TLS encryption for its data, the traffic from the source cluster to Atlas is not encrypted. Determine if this is acceptable before you start a pull live migration procedure.

Database Users and Roles

Atlas doesn't migrate any user or role data to the destination cluster.

If the source cluster doesn't use authentication, you must create a user in Atlas because Atlas doesn't support running without authentication.

If the source cluster enforces authentication, you must recreate the credentials that your applications use on the destination Atlas cluster. Atlas uses SCRAM for user authentication. To learn more, see Configure Database Users.

Oplog Requirements

Source cluster requirements:

• To ensure that the live migration's lag window stays within the bounds of the oplog replication lag window, do one of the following actions on the source cluster:

  • Increase the minimum oplog window. Use this option if storage auto-scaling is enabled (this is the default) on the source cluster.

  • Increase the fixed oplog size. Use this option if you disable storage auto-scaling on the source cluster.

Destination cluster requirements:

• To accommodate potential storage size fluctuations related to oplog size requirements, we recommend that you choose a destination cluster tier that is at least two tiers above the source cluster.

• Live migration performs embedded verification by default, which requires that the destination cluster has a large oplog size. This prevents the verification process errors due to a constrained oplog size.

  • If storage auto-scaling is disabled on the destination cluster, increase the oplog size on the destination cluster to a high enough fixed value.

  • If storage auto-scaling is enabled on the destination cluster, set high enough minimum oplog window on the destination cluster.

  If you can't allocate a large enough oplog size or increase a minimum oplog window on the destination cluster, disable the Verify data post-migration (recommended) switch in the live migration UI and use one of the live migration verification methods described in Cluster-to-Cluster Sync: Verify Data Transfer.

Source and Destination Cluster Balancers

To avoid any impact on write performance during migration, Atlas stops the sharded cluster balancers on the source and destination clusters at the start of the procedure, and starts the balancers at the end of the procedure.

If you cancel live migration, Atlas restarts the balancers on the source and destination clusters.

If Atlas can't restart the load balancer on the source or destination clusters at the end of a successful live migration, a warning banner indicates that you must manually restart the source or destination cluster balancer.

Destination Cluster Configuration

When you configure the destination cluster, consider the following:

• The destination Atlas cluster must have no data. If the cluster has any data before you begin, you have the option to clear data on the destination cluster during the live migration process. Alternatively, you can manually delete the data on the destination cluster before starting the migration procedure.

• The live migration process streams data through a MongoDB-managed live migration server. Each server runs on infrastructure hosted in the nearest region to the source cluster. The following regions are available:

  Europe

  • Frankfurt

  • Ireland

  • London

  Americas

  • Eastern US

  • Western US

  APAC

  • Mumbai

  • Singapore

  • Sydney

  • Tokyo

• Use the cloud region for the destination cluster in Atlas that has the lowest network latency relative to the application servers or to your deployment hosted on the source cluster. Ideally, your application's servers should be running in the cloud in the same region as the destination Atlas cluster's primary region. To learn more, see Cloud Providers.

• The destination cluster in Atlas must match or exceed the source deployment in terms of RAM, CPU, and storage. Provision a destination cluster of an adequate size so that it can accommodate both the migration process and the expected workload, or scale up the destination cluster to a tier with more processing power, bandwidth or disk IO.

• To maximize migration performance, use at least an M40 cluster for the destination cluster. When migrating large data sets, use an M80 cluster with 6000 IOPS disks or higher.

  You can also choose to temporarily increase the destination Atlas cluster's size for the duration of the migration process.

  After you migrate your application's workload to a cluster in Atlas, contact support for assistance with further performance tuning and sizing of your destination cluster to minimize costs.

• To avoid unexpected sizing changes, disable auto-scaling on the destination cluster. To learn more, see Manage Clusters.

• To prevent unbounded oplog collection growth, and to ensure that the live migration's lag window stays within the bounds of the oplog replication lag window, set an oplog size to a large enough fixed value for the duration of the live migration process.

  To learn more, see:

  • Scale a Cluster

  • Atlas Configuration Options

  • oplog Sizing in the Cluster-to-Cluster Sync documentation.

  If you are observing performance issues even after you've followed these recommendations, contact support.

• You can't select an M0 (Free Tier), a Flex cluster, or an M2/M5 shared tier cluster as the destination cluster for live migration.

• Don't change the featureCompatibilityVersion flag while Atlas live migration is running.

Avoid Workloads on the Destination Cluster

Writes are blocked during the live migration:

• When a live migration starts, writes to the destination cluster are blocked. Attempts to perform writes to the destination cluster fail.

• After a live migration completes successfully or fails, writes to the destination cluster may continue.

Don't run multiple migrations to the same destination cluster at the same time.

Don't start the cutover process for your applications to the destination cluster while the live migration process is syncing.

Avoid Cloud Backups

Atlas stops taking on-demand cloud backup snapshots of the target cluster during live migration. Once you complete the cutover step in the live migration procedure on this page, Atlas resumes taking cloud backup snapshots based on your backup policy.

Avoid Elections

The live migration process makes a best attempt to continue a migration during temporary network interruptions and elections on the source or destination clusters. However, these events might cause the live migration process to fail. If the live migration process can't recover automatically, restart it from the beginning.

Pre-Migration Checklist

Before starting the live migration procedure:

• If you don't already have a destination cluster, create a new Atlas deployment and configure it as needed. For complete documentation on creating an Atlas cluster, see Create a Cluster.

• After your Atlas cluster is deployed, ensure that you can connect to it from all client hardware where your applications run. Testing your connection string helps ensure that your data migration process can complete with minimal downtime.

  1. Download and install mongosh on a representative client machine, if you don't already have it.

  2. Connect to your destination cluster using the connection string from the Atlas UI. For more information, see Connect via mongosh.

  Once you have verified your connectivity to your destination cluster, start the live migration procedure.

Procedure