DOCS-2227: New 2.6 Upgrade Doc

Signed-off-by: kay <[email protected]>

source/release-notes/2.6-upgrade.txt

@@ -0,0 +1,251 @@
+======================
+Upgrade MongoDB to 2.6
+======================
+
+.. default-domain:: mongodb
+
+In the general case, the upgrade from MongoDB 2.4 to 2.6 is a
+binary-compatible 'drop-in' upgrade: shut down the :program:`mongod`
+instances and replace them with :program:`mongod` instances running
+2.6. **However**, before you attempt any upgrade please familiarize
+yourself with the content of this document, particularly the procedure
+for :ref:`upgrading sharded clusters <2.6-upgrade-cluster>` and the
+considerations for :ref:`reverting to 2.4 after running 2.6
+<2.6-downgrade>`.
+
+.. contents:: Content
+   :backlinks: none
+   :local:
+   :depth: 1
+
+Upgrade Recommendations and Checklist
+-------------------------------------
+
+When upgrading, consider the following:
+
+- For all deployments using authentication, upgrade
+  drivers (i.e. client libraries), before
+  :program:`mongod` instances.
+
+- Sharded clusters *must* follow the
+  :ref:`meta-data upgrade procedure <2.6-upgrade-cluster>`.
+
+.. XXX AUTH UPGRADE INFORMATION HERE
+
+.. _2.6-upgrade-standalone:
+
+Upgrade Standalone ``mongod`` Instance to MongoDB 2.6
+-----------------------------------------------------
+
+#. Download binaries of the latest release in the 2.6 series from the
+   `MongoDB Download Page`_. See :doc:`/installation` for more
+   information.
+
+#. Shut down your :program:`mongod` instance. Replace the existing
+   binary with the 2.6 :program:`mongod` binary and restart :program:`mongod`.
+
+.. _`MongoDB Download Page`: http://www.mongodb.org/downloads
+
+.. _2.6-upgrade-replica-set:
+
+Upgrade a Replica Set from MongoDB 2.4 to MongoDB 2.6
+-----------------------------------------------------
+
+You can upgrade to 2.6 using a "rolling"
+upgrade to minimize downtime by upgrading the members individually while the
+other members are available:
+
+#. Upgrade the :term:`secondary` members of the set one at a time by
+   shutting down the :program:`mongod` and replacing the 2.4 binary
+   with the 2.6 binary. After upgrading a :program:`mongod` instance,
+   wait for the member to recover to ``SECONDARY`` state
+   before upgrading the next instance.
+   To check the member's state, issue :method:`rs.status()` in the
+   :program:`mongo` shell.
+
+#. Use :method:`rs.stepDown()` in the the :program:`mongo` shell to
+   step down the :term:`primary` and force the normal :ref:`failover
+   <replica-set-failover>` procedure. :method:`rs.stepDown()`
+   expedites the failover procedure and is preferable to shutting down
+   the primary directly.
+
+   When :method:`rs.status()` shows that the primary has stepped down and another member has assumed
+   ``PRIMARY`` state, shut down the previous primary and replace
+   the :program:`mongod` binary with the 2.6 binary and start the new
+   instance.
+
+   .. note:: Replica set failover is not instant but will
+      render the set unavailable to read or accept writes
+      until the failover process completes. Typically this takes
+      10 seconds or more. You may wish to plan the upgrade during
+      a predetermined maintenance window.
+
+.. _2.6-upgrade-cluster:
+
+Upgrade a Sharded Cluster from MongoDB 2.4 to MongoDB 2.6
+---------------------------------------------------------
+
+.. important::
+
+   Only upgrade sharded clusters to 2.6 if **all** members of the
+   cluster are currently running instances of 2.4. The only supported
+   upgrade path for sharded clusters running 2.2 is via 2.4.
+
+Upgrading a :term:`sharded cluster` from MongoDB version 2.4 to 2.6
+(or 2.5) requires that you run a 2.6 :program:`mongos` with the
+:option:`--upgrade <mongos --upgrade>` option, as described in this
+procedure. The upgrade process does not require downtime.
+
+.. warning::
+
+   - .. include:: /includes/fact-upgrade-sharded-cluster-prereq.rst
+
+   - While the upgrade is in progress, you cannot make changes to the
+     collection meta-data. For example, during the upgrade, do **not**
+     do any of the following:
+
+     - :method:`sh.enableSharding()`
+
+     - :method:`sh.shardCollection()`
+
+     - :method:`sh.addShard()`
+
+     - :method:`db.createCollection()`
+
+     - :method:`db.collection.drop()`
+
+     - :method:`db.dropDatabase()`
+
+     - any operation that creates a database
+
+     - any other operation that modifies the cluster meta-data in any
+       way. See :doc:`/reference/sharding` for a complete list
+       of sharding commands. Note, however, that not all commands on
+       the :doc:`/reference/sharding` page modifies the
+       cluster meta-data.
+
+   - After upgrading, **do
+     not** use 2.2 :program:`mongod` and :program:`mongos` instances in
+     your cluster. 2.2 instances may re-introduce old meta-data formats
+     into cluster meta-data. XXX confirm XXX
+
+.. note::
+
+   The upgraded config database will require more storage space than
+   before, to make backup and working copies of the
+   :data:`config.chunks` and :data:`config.collections` collections.
+   As always, if storage requirements increase, the :program:`mongod`
+   might need to pre-allocate additional data files. See
+   :ref:`faq-tools-for-measuring-storage-use` for more information.
+
+Upgrade Sharded Clusters
+------------------------
+
+#. Start a single 2.6 :program:`mongos` instance with
+   :setting:`configdb` pointing to the sharded cluster's :ref:`config
+   servers <sharding-config-server>` and with the :option:`--upgrade
+   <mongos --upgrade>` option.  The upgrade process happens before the
+   instance becomes a daemon (i.e. before
+   :option:`--fork <mongos --fork>`.)
+
+   If you need to avoid
+   reconfiguring a production :program:`mongos` instance, you can upgrade an existing
+   :program:`mongos` instance to 2.6 or start a new `mongos`
+   instance that can reach all config servers.
+
+   Start :program:`mongos` instance:
+
+   .. code-block:: sh
+
+      mongos --configdb <config servers> --upgrade
+
+   Invoking :program:`mongos` without the :option:`--upgrade <mongos
+   --upgrade>` option will fail to start until the 2.6 upgrade process
+   is complete.
+
+   The upgrade will prevent any chunk moves or splits from occurring
+   during the upgrade process. If the data files have many sharded
+   collections or if failed processes hold stale locks,
+   acquiring the locks for all collections can take
+   seconds or minutes. Watch the log for progress updates.
+
+#. When the :program:`mongos` instance starts successfully, the upgrade is
+   complete. If :program:`mongos` fails to start, check the
+   log for more information.
+
+   If the :program:`mongos` instance terminates or loses its connection to the
+   config servers during the upgrade, you may always safely retry the
+   upgrade.
+
+#. Upgrade and restart other :program:`mongos` instances in the
+   sharded cluster, *without* the :option:`--upgrade <mongos --upgrade>`
+   option. See :ref:`2.6-finalize-shard-cluster-upgrade` for more information.
+
+#. :ref:`Re-enable the balancer
+   <sharding-balancing-disable-temporarily>`. You may now perform
+   operations that modify cluster meta-data. XXX confirm meta-data issue XXX
+
+Once you have upgraded, *do not* run version 2.2 MongoDB
+instances in the sharded cluster. Doing so may reintroduce old meta-data
+formats to the config servers. The meta-data change made by this
+upgrade process will help prevent errors caused by cross-version
+incompatibilities in future versions of MongoDB. XXX confirm XXX
+
+.. _2.6-finalize-shard-cluster-upgrade:
+
+Complete Sharded Cluster Upgrade
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After you have successfully completed the XXX sharded cluster upgrade procedure
+and the :program:`mongos` instance starts, you can upgrade the other instances
+in your MongoDB deployment.
+
+.. warning::
+
+   Do not upgrade :program:`mongod` instances until after you have
+   upgraded *all* :program:`mongos` instances.
+
+While the balancer is still disabled, upgrade the components of your
+sharded cluster in the following order:
+
+- Upgrade all :program:`mongos` instances in the cluster, in any
+  order.
+
+- Upgrade all 3 :program:`mongod` config server instances, leaving
+  the *first* system in the :option:`mongos --configdb` argument to upgrade
+  *last*.
+
+- Upgrade each shard, one at a time, upgrading the :program:`mongod`
+  secondaries before running :dbcommand:`replSetStepDown` and
+  upgrading the primary of each shard.
+
+When this process is complete, :ref:`re-enable the
+balancer <sharding-balancing-disable-temporarily>`.
+
+Upgrade and Downgrade Procedures
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Basic Downgrade and Upgrade
+```````````````````````````
+
+**Except** as described below, moving between 2.4 and 2.6 is a drop-in
+replacement:
+
+- stop the existing :program:`mongod`, using the :option:`--shutdown
+  <mongod --shutdown>` option as follows:
+
+  .. code-block:: sh
+
+     mongod --dbpath /var/mongod/data --shutdown
+
+  Replace ``/var/mongod/data`` with your MongoDB :setting:`dbpath`.
+
+- start the new :program:`mongod` instances with the same
+  :setting:`dbpath` setting, for example:
+
+  .. code-block:: sh
+
+     mongod --dbpath /var/mongod/data
+
+  Replace ``/var/mongod/data`` with your MongoDB :setting:`dbpath`.
+