Skip to content

Commit 2c4c087

Browse files
jdestefano-mongojdestefano-mongo
authored
DOCSP-3706 - Reinstate mLab migration tutorial with migration team feedback. (#96)
1 parent 9c34c41 commit 2c4c087

9 files changed

+273
-0
lines changed

‎source/cloud/migrate-from-mlab.txt

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
.. guide::
2+
title: Migrate from mLab to MongoDB Atlas
3+
author: MongoDB Documentation Team
4+
type: Getting Started
5+
level: beginner
6+
product_version: 4.0
7+
result_description:
8+
9+
.. include:: /includes/mlab-mongodb.rst
10+
11+
.. include:: /includes/live-migration-description.rst
12+
13+
This guide will walk you through how to use the Atlas Live
14+
Migration Service to migrate data from mLab to MongoDB Atlas.
15+
time: 20
16+
prerequisites:
17+
.. include:: /includes/steps/migrate-mlab-pr.rst
18+
19+
check_your_environment:
20+
Free (Sandbox) and Shared Plan Migration
21+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22+
23+
Due to limitations on mLab Sandbox and Shared plan database access,
24+
the only way to migrate data to Atlas is to pipe :manual:`mongodump
25+
</reference/program/mongodump/>` to :manual:`mongorestore
26+
</reference/program/mongodump/>`.
27+
28+
It is possible to `upgrade
29+
<https://docs.mlab.com/subscriptions/#change-plans>`_ an mLab
30+
Sandbox deployment to a Dedicated deployment, but database downtime
31+
is required. You can upgrade a Shared deployment to a Dedicated
32+
deployment with no downtime by using a rolling upgrade procedure,
33+
as described in the `mLab documentation
34+
<https://docs.mlab.com/subscriptions/#change-plans-using-rnr>`_.
35+
36+
Dedicated Plan Migration
37+
~~~~~~~~~~~~~~~~~~~~~~~~
38+
39+
You can migrate data in an mLab Dedicated deployment to Atlas with
40+
no database downtime by using the `Atlas Live Migration Service
41+
<https://docs.atlas.mongodb.com/import/live-import/>`_. The
42+
following procedure will help you prepare your data for
43+
migration.
44+
45+
procedure:
46+
.. include:: /includes/steps/migrate-mlab.rst
47+
48+
summary:
49+
You created an Atlas cluster, migrated data from your old mLab
50+
cluster, and updated your applications to use the new Atlas
51+
cluster. Congratulations and welcome to MongoDB Atlas!
52+
whats_next:
53+
* :doc:`Connect to MongoDB </server/drivers>`

‎source/images/add-ip-ranges.png

35.7 KB
Loading

‎source/images/add-oplog-user.png

28.7 KB
Loading

‎source/images/live-migration-full.png

95.5 KB
Loading

‎source/images/mlab-network-access-mode.png

41.6 KB
Loading

‎source/includes/mlab-mongodb.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. admonition:: mLab is now a part of MongoDB, Inc.
2+
:class: note
3+
4+
The procedure to migrate from mLab to MongoDB Atlas will be
5+
further streamlined in the future. If you are looking to migrate
6+
immediately, use the following procedure to migrate your data
7+
using the Atlas Live Migration Service.

‎source/includes/steps-migrate-mlab-pr.yaml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
title: MongoDB Atlas account
2+
ref: atlas-account
3+
level: 4
4+
stepnum: 1
5+
content: |
6+
If you don't have an Atlas account, :doc:`create one
7+
</cloud/atlas>` now.
8+
---
9+
title: mLab MongoDB deployment
10+
ref: mlab-acount
11+
level: 4
12+
stepnum: 2
13+
content: |
14+
The type of migration from mLab you'll be able to perform depends
15+
on the the service level of your mLab deployment. Instructions for
16+
the various service levels can be found below.

‎source/includes/steps-migrate-mlab.yaml

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
title: Create an Atlas deployment
2+
ref: atlas-deployment
3+
level: 4
4+
stepnum: 1
5+
content: |
6+
If you don't already have an Atlas deployment, `create one
7+
<https://docs.atlas.mongodb.com/create-new-cluster/>`_ now. You'll need
8+
a `cluster tier
9+
<https://docs.atlas.mongodb.com/create-new-cluster/#c-select-the-cluster-tier>`_
10+
of ``M10`` or larger to perform Live Migration.
11+
---
12+
title: Check your mLab Network Access Mode
13+
ref: mlab-networking
14+
level: 4
15+
stepnum: 2
16+
content: |
17+
Log in to your `mLab account <https://mlab.com/login/>`_
18+
and navigate to your cluster console.
19+
Select the :guilabel:`Networking` tab.
20+
Your mLab deployment may be in one of three Network Access Modes:
21+
:guilabel:`Public`, :guilabel:`Private (Dual Access)` or
22+
:guilabel:`Private`. If your deployment is :guilabel:`Private`,
23+
no external access is allowed, so you will need to switch to one of
24+
the other two modes before proceeding with migration.
25+
26+
.. figure:: /images/mlab-network-access-mode.png
27+
:figwidth: 700px
28+
29+
.. note::
30+
31+
It will be helpful during the migration process to keep one
32+
browser window open on your mLab cluster console and one
33+
window open on your `Atlas console <https://cloud.mongodb.com>`_.
34+
---
35+
title: Create an oplog user on your admin database
36+
ref: create-oplog-reader
37+
level: 4
38+
stepnum: 3
39+
content: |
40+
To perform the migration process, you need a database user with
41+
permission to read the oplog on your ``admin`` database.
42+
43+
To create an oplog user:
44+
45+
a. Select :guilabel:`Databases`
46+
#. Under :guilabel:`System Databases`, select the :guilabel:`admin` database
47+
#. Select the :guilabel:`Users` tab
48+
#. Click the :guilabel:`Add oplog user` button and name the user
49+
:guilabel:`oplog-reader`
50+
51+
.. figure:: /images/add-oplog-user.png
52+
:figwidth: 700px
53+
---
54+
title: Begin the Atlas Live Migration process
55+
ref: begin-live-migration
56+
level: 4
57+
stepnum: 4
58+
content: |
59+
Navigate to your Atlas cluster. Click the ellipsis (:guilabel:`...`)
60+
button and select :guilabel:`Migrate Data to this Cluster`.
61+
62+
.. figure:: /images/atlas-deployment.png
63+
:figwidth: 700px
64+
---
65+
title: Review migration steps
66+
ref: review-steps
67+
level: 4
68+
stepnum: 5
69+
content: |
70+
Read through the overview of migration steps in the Live Migration
71+
dialog window, then click the green :guilabel:`I'm ready to migrate`
72+
button.
73+
---
74+
title: Add allowable IP address ranges to your mLab deployment
75+
ref: add-ip-ranges
76+
level: 4
77+
stepnum: 6
78+
content: |
79+
For this step you'll need to have browser tabs open
80+
with both the Atlas Live Migration dialog (from step 4)
81+
and your mLab cluster console.
82+
83+
From your mLab cluster console:
84+
85+
a. Select the :guilabel:`Networking` tab
86+
#. Click the :guilabel:`Add IP address range rule(s)` button
87+
#. Add all four of the IP address granges listed in the Atlas
88+
Migration Service dialog from step 5
89+
#. Optional: Add a :guilabel:`Description` for your IP range
90+
#. Click the blue :guilabel:`Add` button when you're finished
91+
92+
.. figure:: /images/add-ip-ranges.png
93+
:figwidth: 521px
94+
95+
You should now see all the Atlas IP ranges listed in the
96+
:guilabel:`Inbound allow rules` section. Click the
97+
:guilabel:`Apply security changes` button to finish the operation.
98+
99+
.. note::
100+
101+
Your IP address ranges may be different from those shown here.
102+
---
103+
title: Add the hostname and port of your mLab cluster primary to the
104+
Atlas Live Migration dialog
105+
ref: add-hostname-port
106+
level: 4
107+
stepnum: 7
108+
content: |
109+
Find the hostname and port number of your mLab cluster primary
110+
node in your mLab cluster console and add it to the Atlas Live
111+
Migration dialog.
112+
113+
.. important::
114+
115+
If your mLab cluster is running in the
116+
:guilabel:`Private (Dual Access)` networking mode, you will need to
117+
use the public hostname of the primary. If you provide the
118+
public hostname of a secondary, Live Migration will not be able to
119+
automatically detect the primary and the migration will fail.
120+
121+
To get the primary's public hostname, append ``-external`` to the
122+
string to the left of the first period in the primary's hostname.
123+
124+
For example, the public hostname for ``ds012345-a0.mlab.com:12345``
125+
is ``ds012345-a0-external.mlab.com:12345``.
126+
127+
---
128+
title: Enter the oplog user's credentials in the Live Migration dialog
129+
ref:
130+
level: 4
131+
stepnum: 8
132+
content: |
133+
Enter the username and password for :guilabel:`oplog-reader` in the
134+
Atlas Live Migration dialog window.
135+
---
136+
title: Specify if Live Migration should use SSL to connect to your mLab
137+
cluster
138+
ref: enter-cafile
139+
level: 4
140+
stepnum: 9
141+
content: |
142+
Dedicated mLab clusters deploy with the :setting:`net.ssl.mode` set
143+
to ``preferSSL`` by default. This allows the cluster to accept both
144+
TLS/SSL and non-TLS/non-SSL connections.
145+
146+
If you wish to connect to your mLab cluster using TLS/SSL, toggle
147+
:guilabel:`Is SSL enabled?` to :guilabel:`Yes`.
148+
149+
.. note::
150+
151+
You do not need to fill in the :guilabel:`Upload CA File` section
152+
that appears on the form after SSL is enabled when migrating from
153+
an mLab cluster.
154+
155+
---
156+
title: Validate your Live Migration form
157+
ref: validate-form
158+
level: 4
159+
stepnum: 10
160+
content: |
161+
Your Atlas Live Migration form should now look like this:
162+
163+
.. figure:: /images/live-migration-full.png
164+
:figwidth: 655px
165+
166+
Click the :guilabel:`Validate` button to check that all your form
167+
fields are valid and everything is ready to go. When your form
168+
is validated, click the :guilabel:`Start Migration` button.
169+
---
170+
title: Start migration
171+
ref: start-migration
172+
level: 4
173+
stepnum: 11
174+
content: |
175+
When the migration process begins, the Live Migration dialog window
176+
closes and you are returned to the Atlas cluster overview page. A
177+
progress bar shows the progess of your migration.
178+
179+
Once the migration is complete, you can begin to update your
180+
client applications to use the new Atlas connection string.
181+
182+
.. figure:: /images/migration-complete.png
183+
:figwidth: 700px
184+
---
185+
title: Start your cutover
186+
ref: start-cutover
187+
level: 4
188+
stepnum: 12
189+
content: |
190+
Your mLab cluster and your Atlas cluster are now in sync. Atlas will
191+
maintain this synchronized state for 72 hours. If you need more time,
192+
syncing can be extended for another 24 hours.
193+
194+
Click the green :guilabel:`Start cutover` button and follow the
195+
instructions listed in the dialog window.
196+
...

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Guides
1717
Migrate to MongoDB Atlas
1818
cloud/migrate-from-aws-to-atlas
1919
cloud/migrate-from-compose
20+
cloud/migrate-from-mlab
2021
server/import
2122
server/drivers
2223
CRUD Guides: Create, Read, Update, and Delete Data

0 commit comments

Comments
 (0)