From 1260e53b9ce9ddd768a2012ff3e33c38c836bf0b Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Wed, 11 Jul 2012 15:39:56 -0400 Subject: [PATCH 1/4] release notes scafolding --- source/release-notes/2.2.txt | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index 81d978292cc..f190e9e1fbf 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -10,11 +10,33 @@ Release Notes for MongoDB Version 2.2 Upgrading --------- - -.. TODO crib from 2.0, with caveat about mongos' before mongod with - auth. -also drivers need to upgrade to -next if using authentication. +Upgrade drivers if using authentication, before upgrading mongod + +Although the major version number has changed, MongoDB 2.0 is a standard, +incremental production release and works as a drop-in replacement for MongoDB +1.8. However, there are a few changes you must be aware of before attempting to +upgrade: + +2.0 processes can talk to 1.8 processes and vice versa, so you can upgrade +various parts of a cluster in any order. + +To upgrade a standalone server. Shutdown the old mongod and then restart with +the new mongod binary. You can download the v2.0 binaries from the MongoDB +Download Page. + +To upgrade a replica set, in the most efficent way possible, while minimizing +the amount of downtime, use the following procedure. Upgrade the secondaries +first one at a time, then s tepDown the primary and upgrade the primary. Using +the stepDown command is better than simply shutting it down since the failover +will happen quicker. To avoid losing the last few updates on failover you can +temporarily halt your application (failover should take less than 10 seconds) +or change your application code to confirm that each update reaches multiple +servers. Note, after upgrading to 2.0 you can use the shutdown command to +shutdown the primary without losing any safe updates. + +To upgrade a shard cluster, if using authentication, you *must* upgrade the +``mongos`` first and then upgrade ``mongod``. Changes ------- From fec084eef18e50b6e9ad58c78e84d9edb7d1658e Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Wed, 11 Jul 2012 16:12:48 -0400 Subject: [PATCH 2/4] incremental canges --- source/release-notes/2.2.txt | 59 ++++++++++++++++++++++-------------- 1 file changed, 36 insertions(+), 23 deletions(-) diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index f190e9e1fbf..8b4d7806a49 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -8,35 +8,48 @@ Release Notes for MongoDB Version 2.2 :backlinks: none :local: -Upgrading ---------- +MongoDB 2.0 is a standard, incremental production release and works as a drop-in replacement for MongoDB. + +Before Upgrading +---------------- -Upgrade drivers if using authentication, before upgrading mongod +If using authentificaton, upgrade drivers before upgrading mongod. See -Although the major version number has changed, MongoDB 2.0 is a standard, -incremental production release and works as a drop-in replacement for MongoDB -1.8. However, there are a few changes you must be aware of before attempting to -upgrade: +Read through these release notes for specific issues you might need to address before upgrading. For example, you might need to change database names, as described in ????? +Upgrading +--------- + 2.0 processes can talk to 1.8 processes and vice versa, so you can upgrade various parts of a cluster in any order. -To upgrade a standalone server. Shutdown the old mongod and then restart with -the new mongod binary. You can download the v2.0 binaries from the MongoDB -Download Page. - -To upgrade a replica set, in the most efficent way possible, while minimizing -the amount of downtime, use the following procedure. Upgrade the secondaries -first one at a time, then s tepDown the primary and upgrade the primary. Using -the stepDown command is better than simply shutting it down since the failover -will happen quicker. To avoid losing the last few updates on failover you can -temporarily halt your application (failover should take less than 10 seconds) -or change your application code to confirm that each update reaches multiple -servers. Note, after upgrading to 2.0 you can use the shutdown command to -shutdown the primary without losing any safe updates. - -To upgrade a shard cluster, if using authentication, you *must* upgrade the -``mongos`` first and then upgrade ``mongod``. +Upgrading a Standalone Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Download the v2.0 binaries from the MongoDB Download Page. + +#. Shutdown the old mongod and then restart with the new mongod binary. + +Upgrading a Replica Set +~~~~~~~~~~~~~~~~~~~~~~~ + +This procedure performs the upgrade in the most efficent way possible, while minimizing +the amount of downtime. + +#. Upgrade the secondaries one at a time. + +#. StepDown the primary and upgrade the primary. Using the stepDown command is better than simply shutting it down since the failover will happen quicker. + + Note, after upgrading to 2.0 you can use the shutdown command to shutdown the primary without losing any updates. + +Upgrading a Shard Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~ + +If using authentificaton: + +- Upgrade drivers before upgrading mongod. See ??? + +- If using authentication, you *must* upgrade the ``mongos`` first and then upgrade ``mongod``. Changes ------- From da273e90c7e87d4b391567ec281788bea414495f Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Thu, 12 Jul 2012 11:50:53 -0400 Subject: [PATCH 3/4] DOCS-290 upgrade procedure for 2.2 --- source/release-notes/2.2.txt | 84 ++++++++++++++++++++++++++---------- 1 file changed, 61 insertions(+), 23 deletions(-) diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index 8b4d7806a49..790cf9f9940 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -8,48 +8,86 @@ Release Notes for MongoDB Version 2.2 :backlinks: none :local: -MongoDB 2.0 is a standard, incremental production release and works as a drop-in replacement for MongoDB. +Upgrading +--------- -Before Upgrading ----------------- - -If using authentificaton, upgrade drivers before upgrading mongod. See +MongoDB 2.2 is a standard, incremental production release and works as +a drop-in replacement for MongoDB 2.0. -Read through these release notes for specific issues you might need to address before upgrading. For example, you might need to change database names, as described in ????? +Preparation +~~~~~~~~~~~ -Upgrading ---------- - -2.0 processes can talk to 1.8 processes and vice versa, so you can upgrade -various parts of a cluster in any order. +If your MongoDB deployment uses authentication, upgrade your drivers +(i.e. client libraries) before upgrading your :program:`mongod` +instances. -Upgrading a Standalone Server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. TODO insert the following line if we eventually have a section on + this change. See the :ref:`driver changes <2.2-driver-changes>` + section for more information. + +Read through all release notes before upgrading, and ensure that no +changes will affect your deployment. -#. Download the v2.0 binaries from the MongoDB Download Page. +2.2 processes can inter-operate with 2.0 and 1.8 tools and processes +in replica sets and shard clusters, if you are not running with +authentication. As a result, you can safely upgrade the +:program:`mongod` and :program:`mongos` components of your deployment +in any order. -#. Shutdown the old mongod and then restart with the new mongod binary. +.. _2.2-upgrade-standalone: + +Upgrading a Standalone ``mongod`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Download the v2.2 binaries from the `MongoDB Download Page`_. + +#. Shutdown your :program:`mongod` instance, replace the existing + binary with the 2.2 :program:`mongod` binary and restart MongoDB. + +.. _`MongoDB Download Page`: http://downloads.mongodb.org/ + +.. _2.2-upgrade-replica-set: Upgrading a Replica Set ~~~~~~~~~~~~~~~~~~~~~~~ -This procedure performs the upgrade in the most efficent way possible, while minimizing -the amount of downtime. +While you may upgrade your replica set in any order, to minimize +downtime, use the following procedure: + +#. Upgrade the :term:`secondary` members of the set one at a time by + shutting down the :program:`mongod` and replacing the binary with + the 2.2 binary. -#. Upgrade the secondaries one at a time. +#. Use the :func:`rs.stepDown()` to step down the primary to allow + normal :ref:`failover ` procedure. -#. StepDown the primary and upgrade the primary. Using the stepDown command is better than simply shutting it down since the failover will happen quicker. + :func:`rs.stepDown()` and :dbcommand:`replSetStepDown` provide for + shorter and more consistent failover procedures than simply + shutting down the primary directly. - Note, after upgrading to 2.0 you can use the shutdown command to shutdown the primary without losing any updates. + When the primary has stepped down, shut the instance down and + upgrade by replacing the :program:`mongod` binary with the 2.2 + binary. Upgrading a Shard Cluster ~~~~~~~~~~~~~~~~~~~~~~~~~ -If using authentificaton: +If your cluster uses authentication, use the following upgrade +procedure: + +- Upgrade all :program:`mongos` instances first, in any order. -- Upgrade drivers before upgrading mongod. See ??? +- Upgrade all other cluster components. Use the :ref:`upgrade + procedure for replica sets <2.2-upgrade-replica-set>` for each of + the shards and the :ref:`stand alone <2.2-upgrade-standalone>` + procedure for each of the config servers. You may upgrade the + components of your cluster in any order. -- If using authentication, you *must* upgrade the ``mongos`` first and then upgrade ``mongod``. +If your cluster *does not* use authentication, you may upgrade the +components of the cluster in any order, using the :ref:`upgrade +procedure for replica sets <2.2-upgrade-replica-set>` for each of the +shards and the :ref:`stand alone <2.2-upgrade-standalone>` procedure +for each of the config servers. Changes ------- From a331d67ed959c175956dd3a8125b5f17e4a5ae80 Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Thu, 12 Jul 2012 13:31:01 -0400 Subject: [PATCH 4/4] DOCS-290 update 2.2 upgrade instructions --- source/release-notes/2.2.txt | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index 790cf9f9940..62b123eb770 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -18,8 +18,8 @@ Preparation ~~~~~~~~~~~ If your MongoDB deployment uses authentication, upgrade your drivers -(i.e. client libraries) before upgrading your :program:`mongod` -instances. +(i.e. client libraries) and and :program:`mongos` instances before +upgrading your :program:`mongod` instances. .. TODO insert the following line if we eventually have a section on this change. See the :ref:`driver changes <2.2-driver-changes>` @@ -29,7 +29,7 @@ Read through all release notes before upgrading, and ensure that no changes will affect your deployment. 2.2 processes can inter-operate with 2.0 and 1.8 tools and processes -in replica sets and shard clusters, if you are not running with +in replica sets and sharded clusters, if you are not running with authentication. As a result, you can safely upgrade the :program:`mongod` and :program:`mongos` components of your deployment in any order. @@ -75,9 +75,14 @@ Upgrading a Shard Cluster If your cluster uses authentication, use the following upgrade procedure: -- Upgrade all :program:`mongos` instances first, in any order. +- Upgrade all :program:`mongos` instances *first*, in any order. -- Upgrade all other cluster components. Use the :ref:`upgrade +- Upgrade all of the :program:`mongod` config server instances *one at + a time*. When you have *less* than *three* config servers active, + the cluster will be read-only which will prevent (and abort) all + chunk migrations and chunk splits. + +- Upgrade all remaining cluster components. Use the :ref:`upgrade procedure for replica sets <2.2-upgrade-replica-set>` for each of the shards and the :ref:`stand alone <2.2-upgrade-standalone>` procedure for each of the config servers. You may upgrade the