Migrate a MongoDB Replica Set from AWS to MongoDB Atlas on AWS

The MongoDB Atlas Live Migration Service helps you migrate MongoDB databases to our fully managed cloud database, MongoDB Atlas, running on AWS quickly and securely. It works by connecting to your existing MongoDB database and synchronizing it with a cluster running in Atlas all while your application continues to function normally. Once the data between the two clusters has been synchronized, you can simply update the database connection string in your application to cut over to your cluster in Atlas.

Time required: 20 minutes

What You'll Need

Your data is currently in a MongoDB database.
This guide focuses on migrating to MongoDB Atlas on AWS from an existing self-managed MongoDB deployment on AWS. If you have data in other database systems, such as MySQL, PostgreSQL, or DynamoDB, please contact us for help with your migration.
Update your MongoDB drivers and make any necessary code changes at the application level to ensure compatibility.
Your current deployment is a MongoDB replica set or sharded cluster.
If your deployment is currently a standalone instance, you must first convert it to a replica set.
If you're migrating a replica set, it is running MongoDB 2.6 or higher.
The Atlas Live Migration Service can move your data directly into a newer database version. For more information about the supported upgrade paths, see the Atlas documentation.
If you're running a version older than 2.6, see Upgrade MongoDB to 2.6 for upgrade instructions.
If you're migrating a sharded cluster, it is running MongoDB 4.0 or higher.
The Atlas Live Migration Service can move your data directly the same database version. For more information about the supported upgrade paths, see the Atlas documentation.
If you're running a version older than 4.0, see Upgrade MongoDB to 4.0 for upgrade instructions.
(Optional) Enabled authentication on your source deployment.
The migration process requires that authentication is enabled on your source cluster in AWS. See Enable Auth for instructions on enabling authentication. You can verify that authentication is enabled on your source cluster using the mongosh command:
```
mongosh <mongodb-connection-string> -u <mongodb-username> -p --authenticationDatabase admin
```

The database user from your source cluster on AWS that you will use to perform the migration has the required MongoDB roles.

The user must have the clusterMonitor and backup roles. To verify that the database user that you intend to use for migration has the appropriate roles, run the db.getUser() command against the admin database.

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

Procedure

Launch your target replica set in MongoDB Atlas running on AWS.

See Create a MongoDB Account and Create a New Cluster for instructions.

Note

Your target cluster must use M10 or larger instance nodes. For development or staging environments, deploy a cluster with M10 or M20 instance nodes. For production workloads, select M30 or larger instance nodes.

Open Atlas Live Migration Service.

Navigate to your Atlas cluster. Click the ellipsis (...) button and select Migrate Data to this Cluster.

This image highlights the Migrate Data to this Cluster
option on a cluster card in Atlas.

click to enlarge

Click General Live Migration.

Click I'm ready to migrate.

Add the IP address for the Atlas Live Migration Service on your AWS source cluster.

At the top of the Migrate Data to Cluster modal, Atlas displays the IP address ranges that must be accessible from your source cluster. The address ranges displayed depend on the location of your target cluster and can change, so verify that you enter the address ranges as displayed in the modal.

AWS EC2 servers are protected from unauthorized network access using Security Groups. To add new IP address ranges to the IP access list, either create a new Security Group, or modify your existing Security Group to permit inbound network access from the displayed IP address ranges.

Here is an example security group that grants access to Atlas Live Migration Service.

Image shows editing and adding inbound rules.

click to enlarge

If you create a new Security Group, you must associate it with the EC2 instances running your source cluster. In the AWS EC2 console, click the Actions dropdown and select Change Security Group.

GIF demonstrating changing a security group.

For additional information on creating or modifying Security Groups, see Adding Rules to a Security Group in the AWS EC2 documentation.

Validate your AWS credentials with Atlas Live Migration Service.

On the Migrate Data to Cluster modal, enter the hostname and port number of the primary node in your source AWS source cluster that Atlas will use to perform the data migration.

Note

The address must be resolvable over the public internet, so do not use the private IP address of the node.

Enter the MongoDB username and password from the AWS source cluster in Username/Password.

If TLS/SSL is enabled on the source cluster, toggle the Is TLS/SSL enabled to Yes and upload the CA file that your source AWS cluster uses.

Click Validate.

Click Start Migration.

A countdown timer in a progress bar indicates how much time remains before your target cluster is ready to migrate data from your source cluster. Wait until the countdown timer and the Prepare to Cutover button are green before proceeding to the next step.

Click Prepare to Cutover.

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 cutover 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 Prepare to Cutover.

Atlas displays a walk-through screen with instructions on how to proceed with the cutover. These steps are also outlined below:

Stop your application. This ensures that no additional writes are generated to the source cluster.
Wait for the optime gap to reach zero. When the counter reaches zero, the source and destination clusters are in sync.
Restart your application using the new connection string provided in step 3 of the Live Migrate cutover UI.

Once you have completed the cutover procedure and confirmed your applications are working normally with the Atlas cluster, click Cut Over to complete the migration procedure. This allows Atlas to:

Mark the migration plan as complete.
Remove the Application Server subnets from the destination cluster IP access list.
Remove the MongoDB user that Live Migrate used to import data to the destination cluster.

Migration Support

If you have any questions regarding migration beyond what is covered in this documentation, or if you encounter an error during migration, please see the Atlas documentation on requesting support.

Summary

You created an Atlas cluster, migrated data from your previous AWS MongoDB cluster, and updated your applications to use the new MongoDB Atlas cluster running on AWS. For more information on the data migration process, see Live Migrate Your Replica Set to Atlas and mongomirror.