Live Migrate Your Sharded Cluster from Ops Manager or Cloud Manager¶

On this page

Restrictions

Prerequisites
Considerations
Migrate Your Cluster

Atlas can perform a Live Migration of a source sharded cluster managed by Cloud Manager or Ops Manager to a sharded Atlas cluster, keeping the target cluster in sync with the source cluster until you cut your applications over to the target cluster in Atlas.

Once you reach the cutover step in the following procedure, stop writes to the source cluster: stop your application instances, point them to the Atlas cluster, and restart them.

Restrictions¶

You cannot select an M0 (Free Tier) or M2/M5 shared cluster as the source or target for Live Migration. To migrate data from an M0 (Free Tier) or M2/M5 shared cluster to a paid cluster, see Modify a Cluster.
Live Migration does not support VPC peering or private endpoints for either the source or target cluster.

For a procedure on live migrating a replica set cluster, see Live Migrate Your Replica Set from Ops Manager or Cloud Manager.

Prerequisites¶

Before you begin the Live Migration from Cloud Manager or Ops Manager to Atlas:

Create an Atlas Account.
Create an Atlas organization and then create a project in this organization.
Ensure that you have the Atlas Organization Owner role.
Deploy your cluster in this project.
Connect to your cluster from all client servers where your applications run.
On your source cluster in Cloud Manager or Ops Manager, prepare the following items:
- Provision a migration host in Ops Manager, or provision a migration host in Cloud Manager.
- Obtain the following external IP addresses from your Cloud Manager or Ops Manager administrator:
  - If migrating from Ops Manager, the external IP addresses or CIDR blocks of the Ops Manager instances. If migrating from Cloud Manager, Atlas automatically obtains these addresses.
  - The external IP addresses or CIDR blocks of the provisioned migration hosts in Cloud Manager or Ops Manager.
- The username and password used to connect to the source cluster.
- If the source cluster uses TLS/SSL with a Custom Root Certificate Authority (CA), to ensure the hosts can read the certificate, add the source cluster's CA file to the migration hosts.
- If you migrate a sharded source cluster with a sharded load balancer, disable sharded collection management in Ops Manager, or disable sharded collection management in Cloud Manager. If you don't disable the sharded load balancer, the Live Migration process might fail.

Live Migration Workflow¶

This section outlines the workflow. For detailed steps, see the procedure for migrating a sharded cluster from Ops Manager or Cloud Manager to Atlas.

"To live migrate your deployment to Atlas, generate a link-token,
provision a migration host, and start live migration."

The stages in the live migration workflow are:

Stage 1: Link with Atlas. Perform this step in Atlas, after you have created your Atlas account, organization, project, deployed your paid cluster in this project, and can connect to it.
1. In the Atlas organization, go to Live Migration.
2. Select Migrate from Ops Manager or Cloud Manager and start the Live Migration wizard.
3. If you are migrating from MongoDB Community using Ops Manager, accept the Ops Manager Migration Agreement.
4. If you are migrating from Ops Manager, enter the external IP addresses of your Ops Manager instances to the Atlas access list. If you are migrating from Cloud Manager, skip this step.
Stage 2: Provision Migration Host.
- Provision a migration host in Ops Manager, or provision a migration host in Cloud Manager. A migration host runs a dedicated MongoDB Agent that orchestrates the Live Migration process from Cloud Manager or Ops Manager to Atlas.
- In the Live Migration: Connect to Atlas section of your Cloud Manager or Ops Manager organization's Settings page, select Connect to Atlas and paste the the link-token that you created in Atlas. To learn more, see Connect to Atlas for Live Migration in Ops Manager, or Connect to Atlas for Live Migration in Cloud Manager.
Stage 3: Start the Migration. In Atlas, follow the steps in the wizard to start the Live Migration process.

Upgrade Path¶

Atlas Live Migration supports the following migration paths:

Live Migration from Cloud Manager or Ops Manager to Atlas is supported for all platforms on which you can provision a migration host. You can create a migration host on the following platforms:

Amazon Linux 2 (linux-x86_64-enterprise-amazon2)
ARM64 Ubuntu 16.04
ARM64 Ubuntu 18.04
ARM64 Ubuntu 20.04
Debian 10
Debian 8.1
Debian 9.2
PPC64LE RHEL 7.1
PPC64LE RHEL 8.1
PPC64LE Ubuntu 16.04
PPC64LE Ubuntu 18.04
RHEL 6.2
RHEL 7.0
RHEL 8.0
s390x RHEL 6.7
s390x RHEL 7.2
s390x SLES 12
s390x Ubuntu 16.04
s390x Ubuntu 18.04
SLES 12
SLES 15
Ubuntu 18.04
Ubuntu 20.04

If you want to live migrate your data from a Windows- or macOS-based deployment to Atlas, you must provision your migration host on one of the supported platforms.

Source Sharded Cluster MongoDB Version	Destination Sharded Cluster MongoDB Version
3.6	3.6
4.0	4.0
4.2	4.2
4.4	4.4

Important

If you are migrating from a MongoDB 3.6 cluster, update and test your applications in context of the target Atlas cluster.

Network Access for Live Migrating from Ops Manager or Cloud Manager¶

Contact your Cloud Manager or Ops Manager service administrator and obtain external IP addresses for the following components:

External IP Address of the Source Cluster in the Ops Manager¶

If you are migrating from Ops Manager, the Live Migration service in Atlas requires an external IP address or an external CIDR block of the Ops Manager instance in the source cluster deployment. This address could be from a single Ops Manager instance, or, if the source deployment uses multiple Ops Manager instances, from the gateway the Ops Manager instances will use to reach Atlas.

The Live Migration service uses this external IP address when generating a link-token. A link-token is a string that contains the information necessary to connect from Cloud Manager or Ops Manager to Atlas during a Live Migration from a Cloud Manager or Ops Manager deployment to a cluster in Atlas.

External IP Address of the Migration Host in Ops Manager or Cloud Manager¶

Before you begin the Live Migration procedure, add the IP addresses or CIDR blocks of your migration hosts to the project IP access list. Atlas only allows connections to the target cluster from hosts with entries in the project's access list.

Pre-Migration Validation¶

Before starting the Live Migration procedure, Atlas runs validation checks on the source and target clusters.

The source cluster is a sharded cluster.
The target Atlas cluster must be a sharded cluster.

Considerations¶

Target Cluster Configuration¶

When configuring the target cluster, consider the following:

The target Atlas cluster must be a sharded cluster.
You can't 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 Migration is running.

Database Users and Roles¶

Atlas doesn't migrate any user or role data to the target cluster.

If the source cluster enforced authentication, before you migrate you must re-create the appropriate authentication mechanism used by your applications on the target Atlas cluster. The following table lists authentication mechanisms and how to configure them in Atlas.

Authentication Mechanism	Configuration Method
SCRAM	Create database users.
LDAP	Set up LDAP.
AWS KMS, Azure Key Vault, Google Cloud KMS	Set up KMS encryption.

Avoid Namespace Changes¶

Don't 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.

Avoid Elections¶

The Live Migration process makes a best attempt to continue a migration during temporary network interruptions and elections on the source or target clusters. However, these events might cause the Live Migration process to fail. If the Live Migration process can't recover automatically, restart it from the beginning.

Rolling Restarts¶

After the migration process completes, your cluster restarts 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, consider running a Test Failover procedure before migrating your data to the target cluster.

Staging and Production Environments¶

Consider running the following procedure twice. Perform a partial migration that stops at the Perform the Cutover step first. This creates an up-to-date Atlas-backed staging cluster to test application behavior and performance using the latest driver version that supports the MongoDB version of the Atlas cluster.

After you test your application, run the full migration procedure using a separate Atlas cluster to create your Atlas-backed production environment.

Dropping Data in the Target Cluster¶

If your target sharded cluster contains existing data, the Live Migration service detects this and warns you that it will drop data and collections from the target sharded cluster before live migrating data into it.

Migrating from MongoDB Community¶

If you are migrating to Atlas from MongoDB Community using Ops Manager, you must accept the Ops Manager Migration Agreement as the first step in the Live Migration procedure.

Migrate Your Cluster¶

Important

Avoid making changes to the source cluster configuration while the Live Migration procedure runs, such as removing sharded cluster members or modifying mongod runtime settings, such as featureCompatibilityVersion.

Procedure¶

Start the migration process.¶

In the left-side panel of your organization's page, click Live Migration.
Click Migrate from Ops Manager or Cloud Manager.
Click I'm Ready to Start and, if you are migrating from MongoDB Community using Ops Manager, click Ops Manager License Agreement to read and accept it. To read the text of the agreement outside of the Live Migration Wizard, see the Ops Manager Migration Agreement.

Atlas displays a Live Migration wizard with instructions on how to proceed with the Live Migration process. The process pushes the data from your source cluster to the new target cluster. After you complete the wizard steps, you can point your application to the new cluster.

Link with Atlas.¶

Click Generate Link-Token. Atlas displays the page for generating a link-token.
- If you are migrating from Ops Manager, enter the external IP addresses or a CIDR block of your Ops Manager instances to add them to the access list of the API Key embedded in the link-token. This allows Ops Manager to send project and cluster information to Atlas. Ops Manager does not send any data stored in your MongoDB databases in this step. For example, enter 23.248.95.14.
- If you are migrating from Cloud Manager, skip this step.
Click Next to see a page that contains the generated link-token.
Copy the link-token and store it in a secure location. Atlas never displays the contents of the link-token. Atlas also does not display the link-token after generating it. Do not share it publicly.
Note
Use one unique link-token for live migrating all projects in one Cloud Manager or Ops Manager organization to Atlas.
Click Done.

Paste the link-token into Ops Manager or Cloud Manager.¶

Access the organization in Cloud Manager or Ops Manager:
Open Ops Manager or Cloud Manager, and navigate to the organization whose project's cluster you are live migrating to Atlas.
Click Settings in the left navigation panel.
In the Live Migration: Connect to Atlas section, click Connect to Atlas. The Connect to Atlas dialog opens.
Paste the link-token you generated in the previous step of the Live Migration wizard and click Connect to Atlas. Cloud Manager or Ops Manager establishes the connection to Atlas. Use the Refresh button to send an update to Atlas, if needed. To learn more, see Connect to Atlas for Live Migration in Ops Manager, or Connect to Atlas for Live Migration in Cloud Manager.

Create the target Atlas cluster.¶

If you haven't already, create a target cluster in Atlas. See Prerequisites.

Initiate the migration from the target cluster.¶

Click Select Target Cluster from Projects.
Go to your target Atlas cluster's project and find your target cluster.
Click and select Migrate Data to this Cluster from the dropdown list to start the migration. The Migrate Data to This Cluster page opens.
Click Migrate from Ops Manager or Cloud Manager and fill in the fields as follows:
- Select the source project in Cloud Manager or Ops Manager, if it is not already selected.
- Select a migration host for handling the migration.
- Review the IP address access list to ensure that the migration host's external IP address is included in this list. If it is not added, add it now:
  - Click Set Network Access for Host
  - Click + Add IP Address
  - Return to the Live Migration wizard. Select the source cluster from the drop-down and choose Migrate data to this cluster under .
- Select the source cluster from the drop-down.
- If the source cluster uses TLS/SSL, toggle the Is SSL enabled? button.
- If the source cluster uses TLS/SSL with a custom Root Certificate Authority (CA), copy the path to the CA file from your migration host and paste this path into the provided text box. This file must be present on the migration host, to ensure the host can read the certificate.
- If your replica set target cluster has data, and you want to preserve it, keep the Clear any existing data on your target cluster option unchecked. The Live Migration service warns you if it finds duplicate namespaces. If you want to delete the existing data, check this option.
- Click Validate. The validation process ensures that your migration host is reachable, and performs other validation checks to ensure that you can start Live Migration to Atlas.
  If validation fails, check the migration host, the validity of your external IP addresses or CIDR block, and the link-token.
- If validation succeeds, click Next. The Migrate from Ops Manager or Cloud Manager page displays.

Start the migration.¶

Review the report listing your source organization, project and cluster, and the migration host that will be used for the Live Migration process.
Click Start the Migration.

Prepare to Cut Over.¶

A lag time value is displayed during the final oplog tailing phase that represents the current lag between the source and target clusters. This lag time might fluctuate depending on the rate of oplog generation on the source, but should decrease over time as oplog entries are copied to the target cluster.

When the lag timer and the Prepare to Cutover button turn green, click it to proceed to the next step.

Perform the cutover.¶

Follow the steps on the Your migration is almost complete page:

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 that is displayed in step 3 of the page in the User Interface.

Once you confirm that your applications are working with the Atlas cluster, click Cut Over to complete the migration process. This allows Atlas to mark the migration plan as complete.

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 request support through the Atlas UI.

To file a support ticket:

Click Support in the left-hand navigation.
Click Request Support.
For Issue Category, select Help with live migration.
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 your summary.
For More details, please include any other relevant details to your question or migration error.
Click the Request Support button to submit the form.

← Live Migrate Your Replica Set from Ops Manager or Cloud Manager Live Migrate Your Data →