Skip to content

Commit 233bf09

Browse files
erabil-mdberabil-mdb
authored
Adds first draft of Migrations doc. (#19)
* Adds first draft of Migrations doc. * Adds more live migration considerations and other migration tools. * Revises per copy review.
1 parent 4b89a0e commit 233bf09

File tree

4 files changed

+163
-2
lines changed

4 files changed

+163
-2
lines changed

‎source/includes/cloud-docs/shared-migration-cutover-description.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
When a migration reaches the "Ready for Cutover" status,
2+
click :guilabel:`Cutover on target cluster`
3+
followed by the :guilabel:`Prepare to Cutover` on the {+cluster+} card to initiate
4+
the cutover process.
5+
Upon successful completion of the cutover, reconfigure your application to point
6+
to the new destination {+cluster+}.

‎source/includes/cloud-docs/shared-migration-monitoring-description.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
To review both ongoing and past migrations, navigate to the :guilabel:`Migration Home`
2+
page in |service|.
3+
4+
You can click each migration process for more detailed information, including
5+
the initial data copy time estimate and comprehensive progress reports.
6+
Use the {+cluster+} card to create, cutover, or cancel a migration.

‎source/includes/cloud-docs/shared-migration-tools-table.rst‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
.. list-table::
2+
:header-rows: 1
3+
:widths: 35 65
4+
5+
* - Tool
6+
- Description
7+
8+
* - |mongosync|
9+
10+
- The |mongosync| binary is the primary process used in |service| live migration.
11+
Use ``mongosync`` to migrate data from one {+cluster+} to a
12+
{+cluster+} in |service|. |service| syncs data from the source to
13+
the destination {+cluster+} until you cut your applications over
14+
to the destination |service| {+cluster+}.
15+
16+
* - :atlas:`mongomirror </import/mongomirror/>`
17+
18+
- Migrate from a MongoDB *replica set* into an |service| cluster
19+
without shutting down your existing replica set or applications.
20+
:atlas:`mongomirror </import/mongomirror/>` does not import
21+
user/role data or copy the ``config`` database.
22+
23+
* - :atlas:`mongorestore </import/mongorestore/>`
24+
25+
- Seed an |service| cluster with a ``BSON`` data backup dump of an
26+
existing MongoDB deployment. :atlas:`mongorestore </import/mongorestore/>`
27+
does not restore ``system.profile`` collection data.
28+
29+
* - :atlas:`mongoimport </import/mongoimport/>`
30+
31+
- Load data from a ``JSON`` or a ``CSV`` file into an |service|
32+
cluster. :binary:`mongoimport` uses
33+
:manual:`strict mode representation for certain BSON types </reference/mongodb-extended-json>`.
34+
35+
* - :compass:`MongoDB Compass </import-export/>`
36+
37+
- Use a :abbr:`GUI (Graphical User Interface)` to load data
38+
from a ``JSON`` or a ``CSV`` file into an |service| cluster.
39+
40+
You can also restore from an |service| cluster backup data to another
41+
|service| cluster. For information, see :ref:`restore-overview`.

‎source/migration.txt‎

Lines changed: 110 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,120 @@ Migration
66

77
.. default-domain:: mongodb
88

9+
.. facet::
10+
:name: genre
11+
:values: reference
12+
13+
.. meta::
14+
:keywords: atlas architecture center
15+
:description: Learn about live migrating data into Atlas from on-premises MongoDB databases using several automated processes.
16+
917
.. contents:: On this page
1018
:local:
1119
:backlinks: none
1220
:depth: 1
1321
:class: onecol
1422

15-
Intro statement
23+
You can migrate data from your on-premises MongoDB deployments to |service| using one of
24+
a variety of methods designed to transfer your data securely, accurately, and
25+
efficiently, with minimal cutover time. We recommend using |service| live migration
26+
when possible because it automates the most tasks with the least downtime, but you can use
27+
more :ref:`manual methods <arch-center-manual-migration>`
28+
that accommodate the variety and complexity inherent to database migration.
29+
30+
Live Migration Overview
31+
-----------------------
32+
33+
|service| live migration automates moving data from on-premises MongoDB databases to |service|.
34+
You can pull data from an on-premises MongoDB database or push data using |com|,
35+
but with either method, |service| live migration includes the following features:
36+
37+
- The migration host always encrypts traffic to the |service| {+cluster+}. To encrypt
38+
data end-to-end, :manual:`enable TLS on your source {+cluster+} </tutorial/upgrade-cluster-to-ssl/>`. Only users with specific
39+
Role-Based Access Control (RBAC) :ref:`roles <authorization>`
40+
(such as :authrole:`backup`, :authrole:`readAnyDatabase`, or :authrole:`clusterMonitor`)
41+
can initiate live migration. Users authenticate to {+clusters+} using
42+
:manual:`SCRAM-SHA-1 or SCRAM-SHA-256 </core/security-scram/>`.
43+
44+
- Live migration automates most tasks. You specify the resource requirements
45+
and scalable options to prevent over-provisioning.
46+
47+
- Detailed instructions help you provision migration hosts and scale destination {+clusters+}
48+
to control costs. Recommendations include appropriate {+cluster+} sizing
49+
and temporary scaling, followed by resizing to optimal levels post-migration.
50+
51+
- Live migration uses |mongosync| to facilitate fast cutover through parallel data copying.
52+
Processes manage temporary network interruptions and {+cluster+} elections, using continuous
53+
data synchronization and a final cutover phase to achieve minimal downtime. Retry
54+
mechanisms and pre-migration validations enhance resilience against interruptions.
55+
56+
- Monitor migrations with real-time status updates and notifications.
57+
58+
Live Migration Methods
59+
----------------------
60+
61+
You can use |com| to push data into |service| or use a live migration server
62+
to pull data into |service|.
63+
64+
Ensure you allocate adequate |cpu| and network resources for the migration host.
65+
While you can run multiple concurrent migrations, each deployment must have a
66+
dedicated migration host.
67+
68+
Both live migration methods require that the source and destination databases run
69+
MongoDB 6.0.13+ or MongoDB 7.0.8+. To migrate data from databases using prior
70+
versions of MongoDB, see `Legacy Migration <https://www.mongodb.com/docs/atlas/legacy-migration/>`__ or :ref:`arch-center-manual-migration`.
71+
72+
* **Pull data into Atlas.** |service| pulls data from the source MongoDB deployment
73+
and requires access to the source deployment through the deployment's firewall. When the
74+
{+clusters+} are nearly synced, you must stop write operations on the source,
75+
redirect applications to the |service| {+cluster+} and restart them. The following
76+
considerations apply:
77+
78+
- Best for deployments not monitored by |com|.
79+
- The source database must be publicly accessible to allow inbound access from the live migration server.
80+
- Doesn't support :ref:`VPC peering <vpc-peering>` or :ref:`private endpoints <private-endpoint>`
81+
for either the source or destination {+cluster+}.
82+
- Source and destination {+cluster+} topologies must match. For example, both
83+
must be replica sets or sharded clusters with the same number of shards.
84+
- Plan for minimal downtime to stop writes and restart applications with a new connection string.
85+
86+
For full migration recommendations and instructions, see :ref:`c2c-pull-live-migration`.
87+
88+
* **Push data into Atlas.** |com| push data to |service| using a secure :term:`link-token`
89+
without requiring access to the source {+cluster+} through the {+cluster+}'s firewall.
90+
During migration, |service| continuously syncs real-time data between the source
91+
and destination {+clusters+} until cutover. The following
92+
considerations apply:
93+
94+
- Data is synchronized in one direction only: changes made to the destination won't
95+
reflect back on the source.
96+
- Supports :ref:`VPC peering <vpc-peering>` and :ref:`private endpoints <private-endpoint>`.
97+
- Source and destination {+cluster+} topologies must match. For example, both
98+
must be replica sets or sharded clusters with the same number of shards.
99+
100+
For full migration recommendations and instructions, see :ref:`c2c-push-live-migration`.
101+
102+
.. _arch-center-manual-migration:
103+
104+
Manual Migration Methods
105+
------------------------
106+
107+
If |service| live migration can't satisfy the constraints of your migration requirements,
108+
you can bring data from existing MongoDB deployments, ``JSON``, or ``CSV`` files
109+
into |service| using one of the following tools that you run outside of |service|.
110+
111+
.. include:: /includes/cloud-docs/shared-migration-tools-table.rst
112+
113+
Monitoring Migrations
114+
---------------------
115+
116+
.. include:: /includes/cloud-docs/shared-migration-monitoring-description.rst
117+
118+
To learn more, see :ref:`monitor-migrations`.
119+
120+
Cutover
121+
-------
122+
123+
.. include:: /includes/cloud-docs/shared-migration-cutover-description.rst
16124

17-
Content here
125+
To learn more, see :ref:`monitor-migrations`.

0 commit comments

Comments
 (0)