Migrate a Compose.io MongoDB Cluster to Atlas
MongoDB Atlas is a cloud service for running, monitoring, and maintaining MongoDB Deployments, including the provisioning of dedicated servers for MongoDB instances.
The following procedure migrates a MongoDB cluster hosted on Compose.io to Atlas. Because the procedure uses the Atlas Live Migration tool, the procedure only requires downtime while updating your applications to connect to the Atlas cluster.
The Atlas Live Migration tool requires that the source cluster runs MongoDB 3.0 or later. See Live Import Upgrade Path for more information.
Configure the Source Compose.io Cluster for Migration
Log into your Compose.io account and access the MongoDB cluster you want to migrate to Atlas.
Whitelist the Atlas Migration Servers
- From the cluster view, click Security.
- Click Add IP for Whitelist TCP/HTTP IPs.
Add the following IP addresses:
Enable Oplog Access for the Cluster
Note: Compose.io charges for access to the oplog.
- From the cluster view, select Add-ons.
- Click add for Oplog Access.
- In the Oplog Access configuration modal, select Enable SSL.
- Click Add MongoDB Oplog Access. Wait for Compose.io to finish enabling oplog access to the cluster.
- From the cluster view, select Add-ons, then click Edit for Oplog Access.
Keep this page open, as you will need the information presented on it for use with this procedure.
Configure the Destination Atlas Cluster for Migration
Log into your Atlas account and click Clusters in the left-hand navigation panel. Ensure you are in your preferred Atlas group by checking the Group dropdown in the top-left corner of the Atlas UI. You can create a new Atlas group if necessary.
If you have not yet created an Atlas cluster as the destination for the migration procedure, create one now.
When selecting a destination cluster, consider the following:
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 an instance with more processing power, bandwidth, or disk IO.
The destination Atlas cluster must be a replica set. You can scale the cluster to a sharded cluster after migration.
You cannot select an M0 (Free Tier) cluster as the destination for live migration.
The destination cluster should be empty, excluding data on the
localdatabases, to prevent namespace collisions. A namespace is the full path to a collection in
<database>.<collection>format. For example, if both the source and the destination cluster contain data in the
foo.barnamespace, the procedure will fail.
Configure MongoDB Users
The Atlas Live Migration tool does not migrate user and role data. You must configure the necessary MongoDB users, such that your applications have the same level of data and operational access as provided on the Compose.io cluster.
Whitelist Applications That Must Connect to the Cluster
Atlas defaults to blocking all incoming connections not on the IP whitelist. The Live Migration tool automatically adds a temporary whitelist entry for the Compose.io cluster. You must whitelist any other applications or services that need to connect to the Atlas cluster.
VPC Peering (AWS Only)
The Atlas Live Migration tool does not leverage any VPC peering connections configured for the destination cluster. If you require that the live migration procedure leverage a VPC peering connection, please contact MongoDB Support.
Configure your Application Server for Migration
Ensure your applications meet the following requirements before starting the migration process:
The application server must have support for TLS/SSL to connect to an Atlas cluster.
If the application server uses a MongoDB driver to connect and perform operations on the MongoDB cluster, you must update to a driver version that is recommended for the MongoDB version of the destination cluster. See the driver compatibility table for complete documentation.
If the application server uses a MongoDB component, such as the mongo shell, to connect and perform operations on the MongoDB cluster, you must update these components to match the MongoDB version of the destination cluster. Download the appropriate version of the MongoDB server package. The server package includes the
mongoshell and other components such as mongodump and mongorestore.
Migrate a Compose.io Cluster to Atlas
Important: The Live Migration tool requires a period of downtime where you cut over your applications to the Atlas cluster. Atlas provides a 72-hour extendable cutover period during which you can schedule the downtime.
Step 1: Open the Live Migration Configuration Dialog
In the Altas UI, from Clusters view click the ... button for the destination cluster and select Migrate Data To This Cluster.
Atlas provides a summary of the Live Migration procedure. Once you have read through it, click I'm Ready To Migrate to open the configuration dialog.
Step 2: Enter the Source Cluster Connection Information
The Live Migration configuration dialog requires the following information from the Compose.io Oplog Access portal:
Portof the oplog service,
Usernamefor the oplog user,
Passwordfor the oplog user, and
- The self-signed SSL Certificate for the SSL connection.
You can extract the
Oplog Portal connection string. For example, consider the
Oplog Portal connection string:
This connection string breaks down as follows:
- Hostname:Port :
- Username :
- Password :
For the self-signed SSL Certificate, perform the following steps:
In the Live Migration configuration dialog, toggle Is SSL Enabled to
Yesto display a text box for entering the certificate.
Retrieve the certificate from the Compose.io Oplog Portal. You may have to click a button in the Compose.io UI to display the full certificate.
Copy the entire certificate, including the
Paste the entire the certificate into the Atlas Live Migration configuration dialog.
Step 3: Validate the Live Migration Settings
Click Validate to prompt Atlas to confirm it can successfully connect to the Compose.io cluster. If the connection fails to validate, ensure you have entered all information correctly and that you have configured the Compose.io cluster whitelist.
If errors persist, open a support ticket in Atlas UI by clicking Support in the left-hand navigation and filling out the requested information.
Step 4: Begin the Live Migration Procedure
Once your connection is validated, click Start Migration. Atlas begins the migration procedure and displays a counter in the UI that represents the time remaining for the Atlas cluster to catch up to the Compose.io cluster.
When the timer turns green, click the Start Cut Over button. Atlas displays a walk-through with instructions on how to proceed with the cut over. Once you click the Start Cut Over button, Atlas 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 timer.
In general, you must:
- Stop all applications from reading or writing to the Compose.io cluster.
- Wait for the timer to hit
- Update applications with the Atlas cluster connection URI as displayed in Atlas.
- Update applications to use Atlas MongoDB users, such that they retain the same level of data and operational access.
- Restart your applications and confirm they are reading from and writing to the Atlas cluster.
Once your applications are up, you can confirm they have connected successfully to the Atlas cluster and are writing normally. When you have validated that your applications are working as expected, you can click I'm done to complete the migration procedure and stop reading data from the Compose.io cluster.