Merge pull request #207 from jdestefano-mongo/DOCSP-25359-snooty

Docsp 25359 snooty

Author: terakilobyte

snooty.toml

@@ -21,4 +21,5 @@ intersphinx = [
     "https://www.mongodb.com/docs/drivers/node/master/objects.inv",
     "https://www.mongodb.com/docs/drivers/go/master/objects.inv",
     "https://www.mongodb.com/docs/drivers/java/sync/master/objects.inv",
+    "https://www.mongodb.com/docs/mongodb-shell/objects.inv",
 ]

source/cloud/migrate-from-aws-to-atlas.txt

@@ -0,0 +1,268 @@
+:orphan:
+:template: guide
+
+==============================================================
+Migrate a MongoDB Replica Set from AWS to MongoDB Atlas on AWS
+==============================================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+The MongoDB Atlas Live Migration Service helps you migrate MongoDB databases to
+our fully managed cloud database, MongoDB Atlas, running on AWS quickly and
+securely. It works by connecting to your existing MongoDB database and synchronizing
+it with a cluster running in Atlas all while your application continues to function
+normally. Once the data between the two clusters has been synchronized, you can
+simply update the database connection string in your application to cut over to
+your cluster in Atlas.
+
+.. time:: 20
+
+What You'll Need
+----------------
+
+* Your data is currently in a MongoDB database.
+
+  This guide focuses on migrating to MongoDB Atlas on AWS from an existing self-managed MongoDB
+  deployment on AWS. If you have data in other database systems, such as MySQL, PostgreSQL, or
+  DynamoDB, please `contact us <https://mongodb.com/contact>`_
+  for help with your migration.
+
+* Update your `MongoDB drivers <https://mongodb.com/docs/drivers/>`_
+  and make any necessary code changes at the application level to ensure
+  compatibility.
+
+* Your current deployment is a MongoDB replica set or sharded cluster.
+
+  If your deployment is currently a standalone instance, you must first
+  :manual:`convert it to a replica set </tutorial/convert-standalone-to-replica-set/>`.
+
+* If you're migrating a replica set, it is running MongoDB 2.6 or
+  higher.
+
+  The Atlas Live Migration Service can move your data directly into a
+  newer database version. For more information about the supported
+  upgrade paths, see the :atlas:`Atlas documentation
+  </import/live-import/#upgrade-path>`.
+
+  If you're running a version older than 2.6, see
+  `Upgrade MongoDB to 2.6
+  <https://mongodb.com/docs/v2.6/release-notes/2.6-upgrade/index.html>`_
+  for upgrade instructions.
+
+* If you're migrating a sharded cluster, it is running MongoDB 4.0 or
+  higher.
+
+  The Atlas Live Migration Service can move your data directly the same database version. For more information about the supported
+  upgrade paths, see the :atlas:`Atlas documentation
+  </import/live-import-sharded/#migration-path>`.
+
+  If you're running a version older than 4.0, see
+  `Upgrade MongoDB to 4.0
+  <https://mongodb.com/docs/v4.0/release-notes/4.0-upgrade-sharded-cluster/>`_
+  for upgrade instructions.
+
+* (Optional) Enabled authentication on your source deployment.
+
+  The migration process requires that authentication is enabled on your
+  source cluster in AWS. See :manual:`Enable Auth </tutorial/enable-authentication/>`
+  for instructions on enabling authentication.
+  You can verify that authentication is enabled on your source cluster
+  using the :binary:`~bin.mongosh` command:
+
+  .. code-block:: sh
+
+     mongosh <mongodb-connection-string> -u <mongodb-username> -p --authenticationDatabase admin
+
+* The database user from your source cluster on AWS that you will use to perform the migration has the required MongoDB roles.
+
+  The user must have the ``clusterMonitor`` and ``backup`` roles. To verify
+  that the database user that you intend to use for migration has the appropriate
+  roles, run the :manual:`db.getUser() </reference/method/db.getUser/>` command against the admin database.
+
+  .. code-block:: javascript
+
+     use admin
+     db.getUser("admin")
+     {
+       "_id" : "admin.admin",
+       "user" : "admin",
+       "db" : "admin",
+       "roles" : [
+         {
+           "role" : "backup",
+           "db" : "admin"
+         },
+         {
+           "role" : "clusterMonitor",
+           "db" : "admin"
+         }
+       ]
+     } ...
+
+Procedure
+---------
+
+.. procedure::
+   :style: normal
+
+   .. step:: Launch your target replica set in MongoDB Atlas running on AWS.
+
+      See :doc:`Create a MongoDB Account </atlas/account>` and 
+      `Create a New Cluster 
+      <https://docs.atlas.mongodb.com/tutorial/create-new-cluster/>`__
+      for instructions.
+   
+      .. note::
+         Your target cluster must use ``M10`` or larger instance nodes.
+         For development or staging environments, deploy a cluster
+         with ``M10`` or ``M20`` instance nodes. For production workloads,
+         select ``M30`` or larger instance nodes.
+
+   .. step:: Open Atlas Live Migration Service.
+
+      .. procedure::
+         :style: connected
+
+         .. step:: Navigate to your Atlas cluster. Click the ellipsis (:guilabel:`...`) button and select
+            :guilabel:`Migrate Data to this Cluster`.
+
+            .. figure:: /images/atlas-deployment.png
+               :figwidth: 700px
+               :alt: This image highlights the Migrate Data to this Cluster
+                     option on a cluster card in Atlas. 
+
+         .. step:: Click :guilabel:`General Live Migration`.
+   
+   .. step:: Click :guilabel:`I'm ready to migrate`.
+
+   .. step:: Add the IP address for the Atlas Live Migration Service on your AWS source cluster.
+
+      At the top of the :guilabel:`Migrate Data to Cluster` modal, Atlas displays
+      the IP address ranges that must be accessible from your source cluster.
+      The address ranges displayed depend on the location of your target
+      cluster and can change, so verify that you enter the address ranges
+      as displayed in the modal.
+
+      AWS EC2 servers are protected from unauthorized network access using
+      `Security Groups <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-group-rules-reference.html>`_.
+      To add new IP address ranges to the IP access list, either create a 
+      new Security Group, or modify your existing Security Group to permit 
+      inbound network access from the displayed IP address ranges. 
+
+      Here is an example security group that grants access to Atlas Live Migration Service.
+
+      .. figure:: /images/aws-inbound-rules.png
+         :figwidth: 760
+         :alt: Image shows editing and adding inbound rules.
+
+      If you create a new Security Group, you must associate it with
+      the EC2 instances running your source cluster. In the AWS EC2 console,
+      click the :guilabel:`Actions` dropdown and select :guilabel:`Change
+      Security Group`.
+
+      .. figure:: /images/aws-change-security-group.gif
+         :figwidth: 760
+         :alt: GIF demonstrating changing a security group.
+
+      For additional information on creating or modifying Security Groups, see `Adding Rules to a Security Group
+      <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#adding-security-group-rule>`_
+      in the AWS EC2 documentation.
+
+   .. step:: Validate your AWS credentials with Atlas Live Migration Service.
+
+      .. procedure::
+         :style: connected
+
+         .. step:: On the :guilabel:`Migrate Data to Cluster` modal, enter the hostname
+            and port number of the primary node in your source AWS source cluster
+            that Atlas will use to perform the data migration.
+
+            .. note::
+            
+               The address must be resolvable over the public internet, so do not use
+               the private IP address of the node.
+
+         .. step:: Enter the MongoDB username and password from the AWS source cluster
+            in :guilabel:`Username/Password`.
+
+         .. step:: If TLS/SSL is enabled on the source cluster, toggle the :guilabel:`Is TLS/SSL enabled`
+            to :guilabel:`Yes` and upload the CA file that your source AWS cluster
+            uses.
+
+         .. step:: Click :guilabel:`Validate`.
+
+   .. step:: Click :guilabel:`Start Migration`.
+
+      A countdown timer in a progress bar indicates how much time remains
+      before your target cluster is ready to migrate data from your source
+      cluster. Wait until the countdown timer and the :guilabel:`Prepare to Cutover`
+      button are green before proceeding to the next step.
+
+   .. step:: Click :guilabel:`Prepare to Cutover`.
+
+   .. step:: Perform the cutover.
+
+      When Atlas detects that the source and destination clusters are nearly
+      in sync, it starts an extendable 72 hour timer to begin the cutover
+      procedure. If the 72 hour period passes, Atlas stops synchronizing with
+      the source cluster. You can extend the time remaining by 24 hours by
+      clicking the :guilabel:`Extend time` hyperlink below the :guilabel:`<time>
+      left to cut over` timer.
+
+
+      .. procedure::
+         :style: connected
+
+         .. step:: Once you are prepared to cut your applications over to the
+            destination Atlas cluster, click :guilabel:`Prepare to Cutover`.
+
+         .. step:: Atlas displays a walk-through screen with instructions
+            on how to proceed with the cutover. These steps are also outlined
+            below:
+
+            1. 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
+               provided in step 3 of the Live Migrate cutover UI.
+       
+               .. step:: Once you are prepared to cut your applications over to the
+                  destination Atlas cluster, click :guilabel:`Prepare to Cutover`.
+
+         .. step:: Once you have completed the cutover procedure and confirmed
+            your applications are working normally with the Atlas cluster,
+            click :guilabel:`Cut Over` to complete the migration procedure.
+            This allows Atlas to:
+       
+            - Mark the migration plan as complete.
+            - Remove the Application Server subnets from the destination
+              cluster IP access list.
+            - Remove the MongoDB user that Live Migrate used to import data
+              to the destination cluster.
+
+Migration Support
+-----------------
+
+If you have any questions regarding migration beyond what is covered
+in this documentation, or if you encounter an error during migration, please
+see the Atlas documentation on
+`requesting support <https://docs.atlas.mongodb.com/support/#request-support>`__.
+
+Summary
+-------
+
+You created an Atlas cluster, migrated data from your previous AWS
+MongoDB cluster, and updated your applications to use the new
+MongoDB Atlas cluster running on AWS. For more information on the
+data migration process, see `Live Migrate Your Replica Set to Atlas 
+<https://docs.atlas.mongodb.com/import/live-import/>`_ and
+`mongomirror <https://docs.atlas.mongodb.com/reference/mongomirror/index.html>`_.