DOCS-1639: adding docs of process to convert master-slave to replica set

source/core/master-slave.txt

@@ -10,13 +10,16 @@ Master Slave Replication
    all new production deployments This documentation remains to
    support legacy deployments and for archival purposes, *only*.
 
-Replica sets provide functional super-set of master-slave and are more
-robust for production use. Master-slave replication preceded replica
+In addition to providing all the functionality of master-slave
+deployments, replica sets are also more robust for production use.
+Master-slave replication preceded replica
 and makes it possible have a large number of non-master (i.e. slave)
 and to *only* replicate operations for a single database; however,
 master-slave replication provides less redundancy, and does not
 automate failover. See :ref:`replica-set-equivalent` for a replica set
-configuration that is equivalent to master-slave replication.
+configuration that is equivalent to master-slave replication.  If you
+wish to upgrade an existing master-slave deployment to a replica set,
+see :ref:`upgrade-master-slave-to-replica-set`.
 
 Fundamental Operations
 ----------------------
@@ -248,6 +251,72 @@ replica set configurations.
    :data:`~local.system.replset.members[n].host` field must hold a resolvable
    hostname.
 
+.. _upgrade-master-slave-to-replica-set:
+
+Upgrade a Master-Slave Deployment to a Replica Set
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The best way to upgrade a Master-Slave deployment to a replica set is
+to simply restart the current master as a one-member replica set,
+and then add any slaves as new secondaries after wiping
+their data directories.
+
+1. To find the master in a replica set, run:
+
+   .. code-block:: sh
+
+      db.isMaster()
+
+   This should return a document that resembles the following:
+
+   .. code-block:: sh
+
+      {
+              "ismaster" : true,
+              "maxBsonObjectSize" : 16777216,
+              "maxMessageSizeBytes" : 48000000,
+              "localTime" : ISODate("2013-07-08T20:15:13.664Z"),
+              "ok" : 1
+      }
+
+#. Once you've located the master, shut down the :program:`mongod`
+   processes on the master and slave(s), using the following command
+   while connected to each instance:
+
+   .. code-block:: sh
+
+      db.adminCommand({shutdown : 1, force : true})
+
+#. Back up your ``/data/db`` directories, in case
+   you need to revert to the master-slave deployment.
+
+#. Start the master with the :option:`--replSet <replSet>` option, as
+   in the following:
+
+   .. code-block:: sh
+
+      mongod --replSet mysetname
+
+#. Connect to the :program:`mongod` instance's :program:`mongo` shell,
+   and initiate the replica set with the following command:
+
+   .. code-block:: sh
+
+      rs.initiate()
+
+   When the command returns, you will have successfully deployed a
+   one-member replica set. You can check the status of your replica set
+   at any time by running the following command:
+
+   .. code-block:: sh
+
+      rs.status()
+
+You can now follow the :doc:`convert a standalone to a
+replica set </tutorial/convert-standalone-to-replica-set>` tutorial to
+deploy your replica set, picking up from the
+:ref:`Expand the Replica Set <expand-the-replica-set>` section.
+
 Failing over to a Slave (Promotion)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/tutorial/convert-standalone-to-replica-set.txt

@@ -51,6 +51,8 @@ Procedure
    To view the replica set configuration, use :method:`rs.conf()`. To
    check the status of the replica set, use :method:`rs.status()`.
 
+.. _expand-the-replica-set:
+
 Expand the Replica Set
 ~~~~~~~~~~~~~~~~~~~~~~