Skip to content

Commit c885e79

Browse files
erabil-mdberabil-mdb
authored
Merge pull request #211 from erabil-mdb/DOCSP-25787
(DOCSP-25787) Added and re-styled missing Compose Migration guide.
2 parents 28982b2 + 04c7964 commit c885e79

File tree

7 files changed

+349
-0
lines changed

7 files changed

+349
-0
lines changed

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

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
:orphan:
2+
:template: guide
3+
4+
.. _guide-migrate-compose:
5+
6+
=====================================
7+
Migrate from Compose to MongoDB Atlas
8+
=====================================
9+
10+
.. default-domain:: mongodb
11+
12+
.. contents:: On this page
13+
:local:
14+
:backlinks: none
15+
:depth: 1
16+
:class: singlecol
17+
18+
Overview
19+
--------
20+
21+
.. short-description::
22+
23+
Migrate data from Compose to MongoDB Atlas.
24+
25+
This guide walks you through how to migrate data from Compose to MongoDB Atlas
26+
using the Atlas Live Migration process.
27+
28+
.. include:: /includes/live_migration_description.rst
29+
30+
.. time:: 20
31+
32+
What You'll Need
33+
----------------
34+
35+
.. include:: /includes/migration_pr_compose.rst
36+
37+
Procedure
38+
---------
39+
40+
.. procedure::
41+
:style: normal
42+
43+
.. step:: Create an Atlas deployment.
44+
45+
If you don't already have an Atlas deployment, :atlas:`create one
46+
</tutorial/create-new-cluster>` now.
47+
You'll need a :atlas:`cluster tier
48+
</tutorial/create-new-cluster/#select-the-cluster-tier>`
49+
of ``M10`` or larger to perform Live Migration.
50+
51+
.. step:: Log in to your Compose account.
52+
53+
Log in to your `Compose account <https://app.compose.io/session/new>`_
54+
and navigate to the deployment you want to migrate to Atlas.
55+
56+
.. note::
57+
It will be helpful during the migration process to keep one
58+
browser window open on your Compose deployment console and one
59+
window open on your `Atlas console <https://cloud.mongodb.com>`_.
60+
61+
.. step:: Create an oplog user.
62+
63+
.. procedure::
64+
:style: connected
65+
66+
.. step:: Click the :guilabel:`Add-ons` link in the left-side navigation.
67+
If you don't have the :guilabel:`Oplog Access` add-on, add it with the
68+
:guilabel:`Add` button.
69+
70+
.. step:: If you already have the :guilabel:`Oplog Access` add-on, click
71+
:guilabel:`Configure` to see the oplog user username and password.
72+
73+
.. figure:: /images/compose-oplog-addon.png
74+
:figwidth: 700px
75+
:alt: Shows the oplog username and password fields within the
76+
Oplog Access add-on.
77+
78+
To perform the migration process, the oplog user must have
79+
the following privileges:
80+
81+
- The :manual:`readAnyDatabase </reference/built-in-roles/#mongodb-authrole-readAnyDatabase>` role.
82+
- The :manual:`clusterMonitor </reference/built-in-roles/#mongodb-authrole-clusterMonitor>` role.
83+
- The :manual:`backup </reference/built-in-roles/#mongodb-authrole-backup>` role.
84+
85+
If you can't grant these permissions to the oplog user,
86+
the Live Migration process will not work. In this case, use
87+
:atlas:`mongodump and mongorestore </import/mongorestore/>` to migrate
88+
your data to Atlas.
89+
90+
.. step:: Review migration steps.
91+
92+
Read through the overview of migration steps in the Live Migration
93+
dialog window, then click the green :guilabel:`I'm ready to migrate`
94+
button.
95+
96+
.. step:: Add IP address ranges to your Compose deployment whitelist.
97+
98+
.. procedure::
99+
:style: connected
100+
101+
.. step:: Open two browser tabs:
102+
103+
- For the Atlas Live Migration process dialog from the previous step.
104+
- For your Compose deployment dashboard.
105+
106+
.. step:: On your Compose deployment dashboard, click the :guilabel:`Security`
107+
link in the left-side navigation. The :guilabel:`Whitelist TCP/HTTP
108+
IPs` section displays a list of IP address ranges which are allowed
109+
to access your Compose deployment.
110+
111+
.. step:: Add the IP address range which is listed at the top of the
112+
Atlas Migration process dialog window.
113+
114+
.. figure:: /images/compose-add-ips.png
115+
:figwidth: 700px
116+
:alt: Shows IP address range entered in the Whiltelist TCP/HTTP
117+
IPs section.
118+
119+
.. note::
120+
Your Atlas migration IP address ranges may be different from
121+
those shown here.
122+
123+
.. step:: Add the hostname and port of your Compose deployment to the
124+
Atlas Live Migration dialog.
125+
126+
On the :guilabel:`Oplog Access` add-on page, you'll find a connection
127+
string with a hostname and port for oplog access. Copy them to the Atlas
128+
Live Migration dialog.
129+
130+
.. figure:: /images/compose-hostname.png
131+
:figwidth: 650px
132+
:alt: Shows field filled in with a hostname and port.
133+
134+
.. step:: Enter the oplog user's credentials in the Live Migration dialog.
135+
136+
Enter the username and password for :guilabel:`oploguser` in the
137+
Atlas Live Migration dialog window.
138+
139+
.. step:: Enter your Compose TLS/SSL Certificate data.
140+
141+
If you don't have TLS/SSL enabled on your Compose deployment, skip this
142+
step.
143+
144+
.. important::
145+
146+
In some Compose deployments, you can no longer view your TLS/SSL
147+
certificate in the Compose UI. If this is the case for your
148+
deployment, you have two options:
149+
150+
- Contact Compose directly to request your TLS/SSL certificate.
151+
- Use :atlas:`MongoMirror </import/mongomirror/>` to migrate your data to Atlas.
152+
153+
See the `Compose documentation
154+
<https://help.compose.com/docs/lets-encrypt-certificates>`__ for more
155+
information about SSL certificates.
156+
157+
On the :guilabel:`Oplog Access` add-on page, you'll find an SSL
158+
certificate. Copy it to the CAFile text box on the Atlas Live
159+
Migration dialog.
160+
161+
.. figure:: /images/compose-cafile.png
162+
:figwidth: 664px
163+
:alt: Shows an SSL certificate pasted into the CAFile text box.
164+
165+
.. note::
166+
Copy the entire certificate file, including the
167+
``BEGIN CERTIFICATE`` and ``END CERTIFICATE`` lines.
168+
169+
.. step:: Validate your Live Migration form.
170+
171+
Click the :guilabel:`Validate` button to check that all your form
172+
fields are valid and your clusters are ready for migration. When your
173+
form is validated, you're ready to begin the migration.
174+
175+
.. step:: Click :guilabel:`Start Migration`.
176+
177+
A countdown timer in a progress bar indicates how much time remains
178+
before your target cluster is ready to migrate data from your source
179+
cluster. Wait until the countdown timer and the :guilabel:`Prepare to Cutover`
180+
button are green before proceeding to the next step.
181+
182+
.. step:: Click :guilabel:`Prepare to Cutover`.
183+
184+
.. step:: Perform the cutover.
185+
186+
When Atlas detects that the source and destination clusters are nearly
187+
in sync, it starts an extendable 72 hour timer to begin the cutover
188+
procedure. If the 72 hour period passes, Atlas stops synchronizing with
189+
the source cluster. You can extend the time remaining by 24 hours by
190+
clicking the :guilabel:`Extend time` hyperlink below the :guilabel:`<time>
191+
left to cut over` timer.
192+
193+
.. procedure::
194+
:style: connected
195+
196+
.. step:: Once you are prepared to cut your applications over to the
197+
destination Atlas cluster, click :guilabel:`Prepare to Cutover`.
198+
199+
.. step:: Atlas displays a walk-through screen with instructions
200+
on how to proceed with the cutover. These steps are also outlined
201+
below:
202+
203+
1. Stop your application. This ensures that no additional writes
204+
are generated to the source cluster.
205+
206+
#. Wait for the optime gap to reach zero. When the counter reaches
207+
zero, the source and destination clusters are in sync.
208+
209+
#. Restart your application using the new connection string
210+
provided in step 3 of the Live Migrate cutover UI.
211+
212+
.. step:: Once you are prepared to cut your applications over to the
213+
destination Atlas cluster, click :guilabel:`Prepare to Cutover`.
214+
215+
.. step:: Once you have completed the cutover procedure and confirmed
216+
your applications are working normally with the Atlas cluster,
217+
click :guilabel:`Cut Over` to complete the migration procedure.
218+
This allows Atlas to:
219+
220+
- Mark the migration plan as complete.
221+
- Remove the Application Server subnets from the destination
222+
cluster IP access list.
223+
- Remove the MongoDB user that Live Migrate used to import data
224+
to the destination cluster.
225+
226+
227+
Migration Support
228+
-----------------
229+
230+
If you have any questions regarding migration beyond what is covered
231+
in this documentation, or if you encounter an error during migration, please
232+
see the Atlas documentation on
233+
:atlas:`requesting support </support/#request-support>`.
234+
235+
Summary
236+
-------
237+
238+
You created an Atlas cluster, migrated data from your old Compose cluster, and
239+
updated your applications to use the new Atlas Cluster. Congratulations and
240+
welcome to MongoDB Atlas!
241+
242+
.. guide-next::

‎source/images/compose-add-ips.png‎

21.2 KB
Loading

‎source/images/compose-cafile.png‎

92.2 KB
Loading

‎source/images/compose-hostname.png‎

27.9 KB
Loading

‎source/images/compose-oplog-addon.png‎

102 KB
Loading

‎source/includes/live_migration_description.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
The MongoDB Atlas Live Migration Service helps you migrate MongoDB databases to
2+
our fully managed cloud database, MongoDB Atlas, quickly and securely. It works
3+
by connecting to your existing MongoDB database and synchronizing it with a
4+
cluster running in Atlas all while your application continues to function
5+
normally. Once the data between the two clusters has been synchronized, you can
6+
simply update the database connection string in your application to cut over to
7+
your cluster in Atlas.

‎source/includes/migration_pr_compose.rst‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
.. important::
2+
3+
If you have SSL enabled on your Compose deployment, you will need
4+
access to your SSL certificate to complete the Live Migration
5+
process.
6+
7+
In some Compose deployments, you can no longer view your SSL
8+
certificate in the Compose UI. If this is the case for your
9+
deployment, you have two options:
10+
11+
- Contact Compose directly to request your SSL certificate.
12+
- Use :atlas:`MongoMirror </import/mongomirror/>` to migrate
13+
your data to Atlas.
14+
15+
16+
See the `Compose documentation
17+
<https://help.compose.com/docs/lets-encrypt-certificates>`__ for more
18+
information about SSL certificates.
19+
20+
* Your data is currently in a MongoDB database.
21+
22+
This guide focuses on migrating to Atlas from an existing MongoDB deployment
23+
on Compose.
24+
25+
* Your current MongoDB database is running MongoDB 2.6 or higher.
26+
27+
Atlas supports the latest versions of MongoDB: 4.2, 4.4, 5.0, and 6.0.
28+
If you're running MongoDB version 2.6 or greater, the Atlas Live Migration
29+
Service can move your data directly into a newer database version.
30+
Update your :driver:`MongoDB drivers </>`
31+
and make any necessary code changes at the application level to ensure
32+
compatibility. If you're running a version older than 2.6, see
33+
`Upgrade MongoDB to 2.6 <https://mongodb.com/docs/v2.6/release-notes/2.6-upgrade/index.html>`_
34+
for upgrade instructions.
35+
36+
* Your current deployment is a MongoDB replica set or sharded cluster.
37+
38+
If your deployment is currently a standalone instance, you must first
39+
:manual:`convert it to a replica set </tutorial/convert-standalone-to-replica-set/>`.
40+
41+
Live migration of data from sharded clusters is not supported. Your destination
42+
cluster may be sharded, but your source cluster must be an unsharded replica
43+
set.
44+
45+
* (Optional) Enabled authentication on your source deployment.
46+
47+
The migration process requires that authentication is enabled on your
48+
source cluster in AWS. See :manual:`Enable Auth </tutorial/enable-authentication/>`
49+
for instructions on enabling authentication.
50+
You can verify that authentication is enabled on your source cluster
51+
using the ``mongosh`` command:
52+
53+
.. code-block:: sh
54+
55+
mongosh <mongodb-connection-string> -u <mongodb-username> -p --authenticationDatabase admin
56+
57+
* The database user from your source cluster that you will use to perform
58+
the migration has the required MongoDB roles.
59+
60+
- The ``readAnyDatabase`` role.
61+
- The ``clusterMonitor`` role.
62+
- The ``backup`` role.
63+
64+
To verify that the database user that will run the Live Migration
65+
process has these roles, run the :manual:`db.getUser()
66+
</reference/method/db.getUser/>` command on the ``admin`` database.
67+
68+
.. code-block:: javascript
69+
70+
use admin
71+
db.getUser("admin")
72+
{
73+
"_id" : "admin.admin",
74+
"user" : "admin",
75+
"db" : "admin",
76+
"roles" : [
77+
{
78+
"role" : "backup",
79+
"db" : "admin"
80+
},
81+
{
82+
"role" : "clusterMonitor",
83+
"db" : "admin"
84+
}
85+
{
86+
"role" : "readAnyDatabase",
87+
"db" : "admin"
88+
}
89+
]
90+
} ...
91+
92+
In addition, the database user from your source cluster in Compose
93+
must have the role to read the oplog on your ``admin`` database. See
94+
:atlas:`Oplog Access </reference/atlas-oplog/>`. You obtain access to
95+
this role when you add the oplog user in Compose in the following
96+
procedure.
97+
If you can't grant all of these permissions to the database user from
98+
your source cluster in Compose, the Live Migration process will not work.
99+
In this case, use :atlas:`mongodump and mongorestore </import/mongorestore/>`
100+
to migrate your data to Atlas.

0 commit comments

Comments
 (0)