Import Data into Cluster >
Live Migrate Your Cluster to Atlas

Live Migrate Your Cluster to Atlas¶

On this page

Considerations
Procedure
Migration Support

Atlas can perform a live migration of a source replica set to an Atlas cluster, keeping the cluster in sync with the remote source until you cut your applications over to the Atlas cluster.

Note

You cannot select an M0 (Free Tier) cluster as the source or destination for live migration. To migrate data from an M0 (Free Tier) cluster to a paid cluster, see Migrate Data from an M0 (Free Tier) Cluster to a Paid Cluster.

Atlas does not support live migrations from or to a sharded cluster.

Considerations¶

Upgrade Path¶

Atlas live migration supports the following migration paths:

Source Replica Set Version	Destination Cluster version
3.0	3.2 or 3.4
3.2	3.2 or 3.4
3.4	3.4

Supported Authentication Mechanism¶

Atlas only supports SCRAM-SHA-1 for connecting to source clusters enforcing authentication.

If the source cluster uses a different authentication mechanism, to connect you can use the Migrate with mongomirror tool to migrate data from the source cluster to the destination Atlas cluster.

MongoDB Users and Roles¶

Atlas does not migrate any user or role data to the destination cluster.

If the source cluster enforced authentication, you must re-create the credentials used by your applications on the destination Atlas cluster. Atlas only supports SCRAM-SHA-1 for user authentication. See Add MongoDB Users for a tutorial on creating MongoDB users in Atlas.

IP Whitelisting¶

Source Cluster IP Whitelist¶

If your source cluster is protected by a firewall, grant access to the following Atlas IP ranges:

4.71.186.128/25
4.35.16.128/25

Atlas Cluster IP Whitelist¶

Atlas only allows connections to a cluster from entries in the group’s whitelist. You must add IP addresses such as application servers to the group whitelist manually. Do this before beginning the migration procedure.

Atlas temporarily adds the IP address of the Atlas migration to the group whitelist. During the migration procedure, you cannot edit or delete this entry. Atlas removes the entry automatically once the procedure completes.

For documentation on adding entries to the Atlas whitelist, see Add Entries to the Whitelist.

Cut Over Downtime¶

The live migration procedure requires shutting down your applications as part of the cut over process. This results in some downtime while the migration procedure completes, as well as the time required to update your applications to point to the destination cluster and restart them.

Destination Cluster Configuration¶

When configuring the destination cluster, consider the following:

The live migration process streams data through a migration application server running in AWS US-East. This implicitly requires two network hops to reach the destination cluster irrespective of the location of the source and destination clusters. Due to the potential latency, the live migration application may not be able to keep up with a source cluster that has an extremely heavy write load. You can instead use the mongomirror tool directly from the source cluster, pointing to the destination Atlas cluster.
The live migration process may not be able to keep up with a source cluster whose write workload is greater than what can be transferred and applied to the destination cluster. You may need to scale the destination cluster up to a instance with more processing power, bandwidth or disk IO.
The destination Atlas cluster must be a replica set.
You cannot select an M0 (Free Tier) cluster as the destination for live migration.

Data Transfer Charges¶

Atlas charges for data transfer between the Atlas cluster and another server. The migration procedure incurs data charges based on the amount of data transferred from the source cluster to the Atlas cluster.

For more information on data transfer charges, see Data Transfer.

Procedure¶

1

Create a destination Atlas cluster.¶

Skip this step if you already have an Atlas cluster as the destination of the live migration process.

Create a new Atlas cluster, configuring it as needed. For complete documentation on creating an Atlas cluster, see Create a Cluster.

Once Atlas has deployed your new cluster, proceed to the next step.

2

Start the Migration Process.¶

Click the ellipses ... icon for the destination Atlas cluster.
Click Migrate Data to this Cluster.
Atlas displays a walk-through screen with instructions on how to proceed with the live migration. Prepare the information as stated in the walk-through screen, then click I’m Ready To Migrate.
Atlas displays a walk-through screen that collects information required to connect to the source cluster.
- Enter the hostname and port of the primary member of the source cluster into the provided text box. For example, mongoPrimary.example.net:27017.
- If the source cluster enforces authentication, enter a username and password into the provided text boxes. The username must correspond to a MongoDB user on the admin database with the following permissions:
  - readAnyDatabase on the admin database.
  - read on the local database.
- If the source cluster uses TLS/SSL, toggle the SSL button.
- If the source replica set uses TLS/SSL and is not using a public Certificate Authority (CA), copy the contents of the source cluster’s CA file into the provided text box.
Click Validate to confirm that Atlas can connect to the source replica set.

If validation fails, check that:
- You have whitelisted Atlas on your source cluster.
- The provided user credentials, if any, exist on the source cluster and have the required permissions.
- The SSL toggle is enabled only if the source cluster requires it.
- The CA file provided, if any, is valid and correct.
Click Start Migration to start the migration process.

Once the migration process begins, the Atlas UI displays the Migrating Data walk-through screen for the destination Atlas cluster. This walk-through screen updates as destination cluster proceeds through the migration process, as well as the time remaining for the destination cluster to sync with the source cluster.

When the migration timer and the Start Cut Over button turn green, proceed to the next step.

3

Perform the cutover.¶

When Atlas detects that the source and destination clusters are nearly in sync, it starts an extendable 72 hour timer to begin the cut over procedure. If the 72 hour period passes, Atlas stops synchronizing with the source cluster. You can extend the time remaining by 24 hours by clicking the Extend time hyperlink below the <time> left to cut over timer.

Once you are prepared to cut your applications over to the destination Atlas cluster, click Start Cut Over.
Atlas displays a walk-through screen with instructions on how to proceed with the cut over.

Perform the steps described in the walk-through screen to cut over your applications to the Atlas cluster. The walk-through screen provides the cluster connection string your applications use for connectivity.
Once you have completed the cut over procedure and confirmed your applications are working normally with the Atlas cluster, click I’m Done to complete the migration procedure.

Migration Support¶

If you have any questions regarding migration support beyond what is covered in this documentation, or if you encounter an error during migration, please file a support ticket through the Atlas UI.

To file a support ticket,

Click Support in the left-hand navigation
For Atlas Issue Category, select Other
For Priority, select the appropriate priority. For questions, please select Medium Priority. If there was a failure in migration, please select High Priority.
For Request Summary, please include Live Migration in the your summary.
For More details, please include any other relevant details to your question or migration error.

← Import Data into Cluster Migrate with mongomirror →