Live Migrate Your Replica Set to Atlas¶

Upgrade Path¶

Atlas live migration supports the following migration paths:

Pre-Migration Validation¶

Atlas performs a number of validation checks on the source and destination cluster before starting the Live Migration procedure.

• The source cluster is a replica set.

  If the source is a standalone, convert the standalone to a replica set first before using Live Migration.

• The destination Atlas cluster must be a replica set.

Source Cluster Security¶

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

If the source cluster enforces authentication, create a user with the following privileges:

• Read all databases and collections. The readAnyDatabase role on the admin database covers this requirement.
• Read the oplog.

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

• For source clusters running MongoDB version 3.4 or later a user must have, at a minimum, both clusterMonitor and readAnyDatabase roles. For example:

  use admin
  db.createUser(
    {
      user: "mySourceUser",
      pwd: "mySourceP@$$word",
      roles: [ "clusterMonitor", "readAnyDatabase" ]
    }
  )

  • For source clusters running MongoDB version 3.2 a user must have, at a minimum, both clusterManager and readAnyDatabase roles, as well as read access on the local database. This requires a custom role, which you can create with the following commands:

    use admin
    db.createRole(
         {
           role: "migrate",
           privileges: [
             { resource: { db: "local", collection: "" }, actions: [ "find" ] }
           ],
           roles: ["readAnyDatabase", "clusterManager"]
         }
       )
     db.createUser(
         {
           user: "mySourceUser",
           pwd: "mySourceP@$$word",
           roles: [ "migrate" ]
         }
       )

  • For source clusters running MongoDB version 2.6 or 3.0 a user must have, at a minimum, the readAnyDatabase role. For example:

    use admin
       db.createUser(
         {
           user: "mySourceUser",
           pwd: "mySourceP@$$word",
           roles: [ "readAnyDatabase" ]
         }
       )

Specify the user name and password to Atlas when prompted by the Live Migration procedure.

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.

Destination Cluster Configuration¶

When configuring the destination cluster, consider the following:

• The live migration process streams data through a MongoDB-managed application 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

• Due to network latency, the live migration process may not be able to keep up with a source cluster that has an extremely heavy write load. In this situation, you can still migrate directly from the source cluster by pointing the mongomirror tool 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 tier with more processing power, bandwidth or disk IO.

• The destination Atlas cluster must be a replica set.
• You cannot select an M0 (Free Tier) or M2/M5 shared-tier cluster as the destination for live migration.
• Do not change the featureCompatibilityVersion flag while Atlas Live Migrate is running.

Database 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 uses SCRAM for user authentication. See Configure Database Users for a tutorial on creating database users in Atlas.

Avoid Namespace Changes¶

You should not make any namespace changes during the migration process, such as using the renameCollection command or executing an aggregation pipeline that includes the $out aggregation stage.

Rolling Restarts¶

After the migration process is complete, your destination replica set will restart each of its members one at a time. This is called a rolling restart, and as a consequence, a failover will occur on the primary. To ensure a smooth migration, it is recommended that you perform a Test Failover procedure prior to migrating your data to the destination cluster.

Pre-Migration Checklist¶

Before starting the import process:

• 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 New 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 the mongo shell 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 mongo Shell.

  Once you have verified your connectivity to your target cluster, start the import procedure.

Procedure¶