Guide to Migrating (Early) to Atlas

This page provides a list of the prerequisites for migrating to Atlas and a step-by-step guide to the migration process.

For details on migration timing and our FAQ please visit https://docs.mlab.com/mlab-to-atlas/.

Migration Prerequisites

  1. Ensure minimum required versions:
  2. Review the following key differences between mLab and Atlas:
    • Atlas plans are packaged differently than mLab’s in that clusters, backups, data transfer, and support are priced separately.
    • The Atlas M0 (free) tier does not support Atlas backups. The Atlas M2 and M5 tiers currently do not support Atlas backups but will starting July 2019.
    • Atlas currently does not have a Heroku add-on (see FAQ).
    • Atlas currently does not have a Data API (see FAQ).
    • Atlas currently does not support archiving backups to custom S3 buckets but it does have an API for programmatically accessing backups.
    • Atlas does not support sharing of EBS Snapshots but it does have an API for programmatically accessing backups.
    • Atlas restricts the ability to use certain database commands, some of which were allowed on mLab.
    • Atlas supports Analytics Nodes using replica set tags instead of using hidden nodes.
    • Atlas servers always run with requireSSL and only accept TLS/SSL encrypted connections.
  3. Ensure that all recurring query patterns are well-indexed and that your deployment is running healthy on mLab.
    • If your deployment is on a Shared or Dedicated plan visit the “Slow Queries” tab to view and build the indexes recommended by mLab’s Slow Queries Analyzer. This will allow for a smoother migration process.
    • After building indexes ensure either by streaming the Primary’s database server log from the “Logs” tab or by waiting 24 hours to get a fresh “Slow Queries” tab report that there aren’t any operations that are running with frequency that are slow. By default all operations over 100ms will appear in the database server log.
  4. Consider enabling SSL on your mLab deployment before migrating.
    • If the target Atlas cluster will be on dedicated resources (M10 or above) AND if your mLab deployment is not located in one of Atlas’ six Live Migration regions—AWS us-east-1 (N. Virginia), AWS us-west-2 (Oregon), AWS eu-west-1 (Dublin), AWS eu-central-1 (Frankfurt), AWS eu-west-2 (London), AWS ap-southeast-2 (Sydney)—we recommend enabling SSL on mLab before migrating.
    • If your deployment is hosted in one of the above Live Migration regions, traffic will stay within the cloud provider’s local network.
  5. Immediately before starting to migrate a specific mLab deployment to Atlas:
    • Ensure that you’ve completed the Steps 1 through 6 of the Migration Steps below.

Migration Steps

After identifying the first mLab deployment that you’d like to migrate to Atlas and after reviewing the migration prerequisites detailed above, follow the following 10 steps to migrate your first mLab deployment to Atlas.

The steps to migrate from mLab to MongoDB Atlas will continue to be streamlined by improvements in the product in the coming months.

1. Create your Atlas organization and project(s)

  1. Visit https://mongodb.com/cloud/atlas and register for an Atlas account.
    • The email address that you sign up with will become the username that you use to log in.
  2. (Optional) Rename the default organization.
    • If you will be using this account on behalf of a company, rename it to the name of the company.
  3. (Optional) Rename the default project.
    • Common names are “<your app’s name> Production” and “<your app’s name> Development”.
  4. (Optional) Create multiple projects within your Atlas organization.

2. Connect your Atlas organization to the source mLab account

You can create a connection between the source mLab account (the account from which you want to migrate deployment(s)) to the target Atlas organization in order to make it easier to migrate your mLab deployment(s) to Atlas and invite your mLab account users to your Atlas organization.

Steps:

  1. Log in to the target Atlas organization as an Atlas Organization Owner.
    • Only the Organization Owner will be able to establish a connection to the source mLab account.
  2. From the “Context” menu in the top-left corner select the target Atlas organization.
  3. In the left navigation pane, select “Settings”.
  4. On the “General Settings” tab, click on the “Connect to mLab” button.
    • Note that this tool (in beta) is in active development and is expected to frequently change.
    • Also note that this tool currently only helps with migrations into the Atlas dedicated tiers (M10+).
  5. Log in to the source mLab account from the same browser if you haven’t already as an mLab Admin User.
  6. In mLab’s UI review the text presented by the “Authorize MongoDB Atlas” form and click “Authorize” to complete the connecting of your mLab account with your Atlas organization.

The “mLab Account” tab in the left navigation pane should now be highlighted, and you should see the “mLab Account” view. This view lists your mLab deployments on the “Deployments” tab and lists your mLab account users on the Account Users tab. This view makes it easier to invite your mLab account users to your Atlas organization and to migrate your mLab deployment(s) to Atlas.

If you’ve navigated away from this “mLab Account” view you can return back. From the Context menu ensure that the organization is selected and in the left navigation pane click on the “mLab Account” link.

3. Invite the source mLab account’s users to your Atlas organization and grant project access

After the connection between the source mLab account and the target Atlas organization has been established you will be able to see a list of the account users which exist on the source mLab account and have the opportunity to invite a given mLab user’s email address to your Atlas organization.

Unlike with mLab, a given email address (and username) on Atlas can be associated with many Atlas organizations.

Steps:

  1. Navigate to the “mLab Account” view.
    • In the left navigation pane, click “mLab Account”.
  2. Select the “Account Users” tab.

  3. Open the “Invite mLab User to Organization” dialog.
    • Locate the user that you want to invite to the target Atlas organization.
    • Click the ellipses (…) button for that user.
    • Click “Invite User”.
  4. In the dialog, click “Send Invitation”.
    • The dialog will close and Atlas will send an email to that user’s email address inviting them to the Atlas organization. The subject of this email will start with “Invitation to MongoDB Cloud”.
    • If this email address is new to Atlas (i.e., isn’t associated with an existing Atlas user), when the invitation is accepted, this email address will become the username for the new Atlas user. This new Atlas user will only be able to log into Atlas and not mLab.
    • Otherwise when the invitation is accepted, this user will now see your Atlas organization associated with their profile.
  5. Ensure that the correct target project is selected.
    • From the “Context” menu in the top-left corner select a specific project.
  6. Grant access to the target project.
    • View Atlas documentation on managing project access and project roles.
    • The Atlas user that initiates a migration into a target Atlas cluster needs to have “Project Owner” access.

4. Configure IP whitelist and database users for the target Atlas project

To access your target Atlas cluster, you’ll need to ensure that any necessary whitelist entries and MongoDB users have been created.

Unlike with mLab, different Atlas clusters can share the same database users and network configuration. Specifically, be aware that Atlas clusters within a given Atlas project share the same database users and whitelisted IP addresses.

IP Whitelist

To access the Atlas cluster, you must connect from an IP address on the Atlas project’s IP whitelist. You can add IP address ranges from the “Security” -> “IP Whitelist” tab for your project.

View Atlas documentation on configuring whitelist entries.

MongoDB Users

To access the Atlas cluster, you must authenticate using a MongoDB User that has access to the desired database(s) on your Atlas cluster. You can create database users from the “Security” -> “MongoDB Users” tab for your project.

View Atlas documentation on configuring MongoDB users.

mLab admin database users have the root role on the admin database. The Atlas privilege that is most equivalent is Atlas admin but be aware that this privilege does not have all the permissions that mLab admin database users have.

5. Create the target Atlas cluster

Before starting the migration process, you must create the target for the migration.

To create an Atlas cluster:

  1. Ensure that the correct target project (within the correct organization) is selected.
    • From the “Context” menu in the top-left corner select a specific project.
  2. Click on the “Build a Cluster” or “Build a New Cluster” button to create an Atlas cluster, noting our recommendations in the table below.
IMPORTANT:  
Cloud Provider & Region Select the same region as the source mLab deployment.
Cluster Tier Size the target Atlas cluster to be at least as performant as the source mLab deployment in order to make the migration process as smooth as possible. You’ll be able to seamlessly downgrade on Atlas within the Atlas Dedicated tiers (M10+) once the migration is complete.

Note that the Atlas Live Migration process is only available for the Atlas M10+ tiers.
Additional Settings > Version On the M10+ tiers select the same MongoDB release version as the source mLab deployment (3.4 or 3.6).
Additional Settings > Backup On the M10+ tiers select “Cloud Provider Snapshots” as the backup solution.
Cluster Name If you want to customize the name of your Atlas cluster, now is the time. This name will be part of the cluster’s connection string, and you will not be able to change it later.

6. Test connectivity from all application clients

A critical step to ensuring a migration to Atlas with very minimal downtime is testing connectivity to the target Atlas cluster from all applications before cutting over from the source mLab deployment.

For each application that depends on this deployment:

  1. Log into a representative client machine.
  2. From that machine, download and install the mongo shell.
  3. From that machine, connect to your cluster using the exact connection string that has been published in Atlas’ UI.

This will ensure that each of your applications has network connectivity and working database credentials.

7. Migrate the source mLab deployment to the target Atlas cluster

After the connection between the source mLab account and the target Atlas organization has been established you will be able to see a list of your mLab deployments and their migration status.

Using the Atlas Live Migration process

Available only for mLab for-pay deployments migrating to Atlas M10+ tiers.

Atlas can perform a live migration of the source mLab deployment to the target Atlas cluster, keeping the target in sync with the source until you cut your applications over to the target Atlas cluster.

Do not cutover to the target Atlas cluster until you have tested connectivity from all applications (Step 4 above) and ensured that all writes have stopped on the source mLab deployment.

Consider doing a trial run of this process by performing a partial migration that stops before the “Cut over” step. Once you are ready, start the Live Migration process again.

  1. Navigate to the “mLab Account” view.
    • In the left navigation pane, click “mLab Account”.
  2. Start the migration process.
    • Locate the mLab deployment that you want to start migrating to Atlas.
    • Click the ellipses (…) button for that deployment.
    • Click “Configure Migration” to start the migration wizard.
    • Follow the steps in the migration wizard but do not cutover until you’ve tested connectivity from all applications (Step 4 above) and stopped all writes to the source mLab deployment.
  3. Wait until the source and target deployments are in sync.
    • When Atlas detects that the source and target 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.
  4. Prepare to cutover.
    • Click the “Start Cutover” button to open a walk-through screen with instructions on how to proceed.
    • Copy and paste the connection string for your target Atlas cluster and prepare to change your connection string.
  5. Cutover.
    • Stop writes to the source mLab deployment by stopping all application clients.
    • Wait for the optime gap to reach 0 (this should be very quick).
    • Restart application clients with the target Atlas connection string.

To migrate an mLab Shared plan deployment to an Atlas M10+ tier, you may use the Atlas Live Migration process but only if it is initiated via the “mLab Account” view while your Atlas organization is connected to your mLab account.

Using mongodump/mongorestore

Recommended for migrating mLab Sandbox deployments as well as for migrating small Shared plan deployments migrating to the Atlas M2/M5 shared tier.

In the coming months Atlas will be releasing an easier way for migrating mLab Sandbox and small Shared plan deployments to Atlas. We recommend waiting to migrate if you want to avoid a manual migration process.

Manual Steps:

  1. Stop your app(s) and any other processes writing to the source mLab deployment.
  2. Backup the mLab source using mongodump.
  3. Restore the backup to the target Atlas cluster using mongorestore.
  4. Change your connection string info in your app(s)
  5. Restart your app(s)

8. Customize the backup policy for your Atlas cluster (M10+)

We recommend reviewing the backup schedule and retention policy for your target Atlas cluster.

Be aware that:

View Atlas documentation on Snapshot Scheduling and Retention Policy.

9. Test failover and ensure resilience

Atlas performs maintenance periodically. This maintenance can happen at any time unless you’ve configured a maintenance window. To ensure that maintenance on Atlas is seamless for your application(s):

  1. Configure your application(s) to use the exact connection string published in Atlas’ UI.
  2. Test failover on Atlas.
  3. (Optional) Configure a maintenance window for your Atlas project.

10. Select a support plan for your Atlas organization

MongoDB Atlas offers three types of support plans:

img-atlas-support-plans

If you are in development or are running a non-critical application, the Developer Support plan is a great choice. This plan has been designed to provide in-depth technical support but with slower response times.

If your application(s) have demanding uptime and/or performance requirements, we highly recommend a Premium Support plan. These plans are designed to provide high-touch, in-depth technical support for advanced issues such as performance tuning, as well as rapid response times for emergencies, 24x7.

To select the Developer Support plan:

  1. From the “Context” menu in the top-left corner select the target Atlas organization.
  2. In the left navigation pane, select “Support”.

To select a Premium Support plan, email support@mlab.com for help. Currently it’s not possible to self-service the selection of one of these plans.

11. Delete the source mLab deployment

To stop incurring charges on mLab for a for-pay deployment, you must ensure that the mLab deployment has been deleted. We recommend deleting it as soon as you are confident that you no longer need it.

Note that mLab bills at the start of each month for all chargeable services provided in the prior month, so you will still be charged one additional time even after your mLab account stops incurring charges.

Reference

Sizing the Target Atlas Cluster

The Atlas M0, M2, and M5 plans run on shared resources (VM/disk) while the Atlas M10 plans and above run on dedicated resources.

mLab Plan Suggested Atlas Tier
Sandbox M0 (free) or M2
Shared M2, M5, or M10
Dedicated M10 and above

mLab Sandbox

You may migrate your free mLab Sandbox database to the Atlas M0 (free tier).

However, if you need automated backups, you should migrate it to the Atlas M2 or above. Note that the Atlas M2/M5 tiers will not have automated backups until July 2019.

Also note that the Atlas M0 tier has operational limitations that you should be aware of.

mLab Shared

If your deployment is currently running on an mLab Shared plan, the tier that we suggest on Atlas depends on the size of your database.

mLab Size 2 Suggested Atlas Tier  
Less than 1.6 GB M2 Review warnings below
Between 1.6 GB and 4 GB M5 Review warnings below
More than 4 GB M10 Ensure CPU usage will not be too high

Atlas M2/M5 Warnings:

Atlas M10 Warning:

The Atlas M10 tier (which is similar to mLab’s M1 tier) has just 1 CPU core.

As such before migrating from an mLab Shared plan to the Atlas M10 make sure that you visit the mLab “Slow Queries” tab to view and build the indexes recommended by mLab’s Slow Queries Analyzer. If the “Slow Queries” tab continues to show a high rate of slow operations, please email support@mlab.com for help before attempting to migrate to Atlas.

mLab Dedicated

If your deployment is currently running on an mLab Dedicated plan, the following table shows the equivalent Atlas tier.

Note that Atlas sets limits for concurrent incoming connections based on instance size.

mLab Plan Equivalent Atlas Tier
M1 Standard or High Storage M10
M2 Standard or High Storage M20
M3 Standard or High Storage M30
M4 Standard or High Storage M40 (General class)
M5 Standard or High Storage M50 (General class)
M6 Standard or High Storage M60 (General class)
M7 Standard or High Storage M80 (Low-CPU)
M8 Standard or High Storage M200 (Low-CPU)
   
M3 High Performance (legacy) M40 (Local NVMe SSD)
M4 High Performance (legacy) M40 (Local NVMe SSD)
M5 High Performance M50 (Local NVMe SSD)
M6 High Performance M60 (Local NVMe SSD)
M7 High Performance M80 (Local NVMe SSD)

Choosing the Atlas disk type and size (M10 and above)

AWS

mLab’s Dedicated Standard and High Storage plans use AWS’s General Purpose SSD (gp2) EBS volumes. By default Atlas uses the same volume type.

The performance of this volume type is tied to volume size. As such when you create your cluster on Atlas:

Google Cloud Platform (GCP) and Azure 2 (AZR2)

mLab’s Dedicated plans on GCP and Azure 2 use the same disk type as Atlas. On GCP both use GCP’s SSD Persistent Disks. On Azure both use Premium SSD Managed Disks.

The performance of these disk types is tied to disk size. As such when you create your cluster on Atlas:

Azure Classic (AZR)

mLab’s Azure Classic Dedicated plans use magnetic disks (Azure’s page blobs and disks) while Atlas uses Premium SSD Managed Disks.

Disk I/O will be significantly improved on your target Atlas cluster. As such when you create your cluster on Atlas:









  1. Usage costs are the sum of cluster (VM/disk), data transfer, and backup costs. 

  2. Size of data plus indexes of mLab deployment. This is the value under the “SIZE” heading in mLab’s UI.