Skip to content

Commit 89b1f06

Browse files
jeff-allen-mongojeff-allen-mongo
authored
DOCSP-35373: Restore patch release upgrade page (#5810)
* WIP * add upgrade revision page to toc * fix replacements * edits * edits * edits * add learn more
1 parent 1c00d26 commit 89b1f06

File tree

5 files changed

+238
-7
lines changed

5 files changed

+238
-7
lines changed

‎config/redirects

-3
Original file line numberDiff line numberDiff line change
@@ -2532,9 +2532,6 @@ raw: ${prefix}/${version}/applications/drivers -> ${base}/drivers/
25322532
[v4.2-*]: ${prefix}/${version}support/ -> ${base}/${version}/support
25332533
[v4.2-*]: ${prefix}/${version}tutorial/resync-replica-set-member/ -> ${base}/${version}/tutorial/resync-replica-set-member/
25342534

2535-
# DOCSP-32198 Redirect removed page
2536-
[v7.0-*]: ${prefix}/${version}/tutorial/upgrade-revision -> ${base}/${version}/release-notes/
2537-
25382535
# DOCSP-31908 Removing free monitoring pages after decomission
25392536
[*]: ${prefix}/${version}/reference/method/db.enableFreeMonitoring -> ${base}/${version}/administration/free-monitoring/
25402537
[*]: ${prefix}/${version}/reference/method/db.disableFreeMonitoring -> ${base}/${version}/administration/free-monitoring/

‎source/administration/configuration-and-maintenance.txt

+5
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,10 @@ updating your MongoDB deployment's configuration.
1313
Outlines common MongoDB configurations and examples of
1414
best-practice configurations for common use cases.
1515

16+
:ref:`upgrade-to-latest-revision`
17+
Upgrade a MongoDB deployment to a different patch release
18+
within the same major release series.
19+
1620
:doc:`/tutorial/manage-mongodb-processes`
1721
Start, configure, and manage running :binary:`~bin.mongod`
1822
process.
@@ -30,6 +34,7 @@ updating your MongoDB deployment's configuration.
3034
:hidden:
3135

3236
/administration/configuration
37+
/tutorial/upgrade-revision
3338
/tutorial/manage-mongodb-processes
3439
/tutorial/terminate-running-operations
3540
/tutorial/rotate-log-files

‎source/includes/upgrade-intro.rst

+7-4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
Use this tutorial to upgrade from a previous major release or upgrade
2-
to the latest patch release of your current release series. Familiarize
3-
yourself with the content of this document, including thoroughly reviewing the
4-
prerequisites, prior to upgrading to MongoDB |newversion|.
1+
Use this tutorial to upgrade from MongoDB |oldversion| to MongoDB
2+
|newversion|. To upgrade to a new patch release within the same release
3+
series, see :ref:`upgrade-to-latest-revision`.
4+
5+
Familiarize yourself with the content of this document, including
6+
thoroughly reviewing the prerequisites, prior to upgrading to MongoDB
7+
|newversion|.

‎source/release-notes.txt

+2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
.. start-include-here
22

3+
.. _server-release-notes-landing:
4+
35
Release Notes
46
-------------
57

‎source/tutorial/upgrade-revision.txt

+224
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
.. _upgrade-to-latest-revision:
2+
3+
==============================================
4+
Upgrade to the Latest Patch Release of MongoDB
5+
==============================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
MongoDB version numbers have the form ``X.Y.Z`` where ``Z`` refers to
16+
the patch release number. Patch releases provide security patches, bug
17+
fixes, and new or changed features that generally do not contain any
18+
backward breaking changes. Always upgrade to the latest patch release in
19+
your release series.
20+
21+
For more information on versioning, see :ref:`release-version-numbers`.
22+
23+
About this Task
24+
---------------
25+
26+
This page describes upgrade procedures for the MongoDB
27+
{+latest-lts-version+} release series. To upgrade a different release
28+
series, refer to the corresponding version of the manual.
29+
30+
.. _upgrade-options:
31+
32+
Before You Begin
33+
----------------
34+
35+
Review the following sections to ensure that your deployment is ready to
36+
be upgraded.
37+
38+
Backup
39+
~~~~~~
40+
41+
Ensure you have an up-to-date backup of your data set. See
42+
:ref:`backup-methods`.
43+
44+
Compatibility Considerations
45+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46+
47+
Consult the following documents for any special considerations or
48+
compatibility issues specific to your MongoDB release:
49+
50+
- :ref:`Release notes <server-release-notes-landing>`
51+
52+
- :driver:`Driver documentation </>`
53+
54+
Maintenance Window
55+
~~~~~~~~~~~~~~~~~~
56+
57+
If your installation includes :term:`replica sets <replica set>`, set
58+
the upgrade to occur during a predefined maintenance window.
59+
60+
Staging Environment Check
61+
~~~~~~~~~~~~~~~~~~~~~~~~~~
62+
63+
Before you upgrade a production environment, use the procedures in this
64+
document to upgrade a *staging* environment that reproduces your
65+
production environment. Ensure that your production configuration is
66+
compatible with all changes before upgrading.
67+
68+
.. _upgrade-procedure:
69+
70+
Steps
71+
-----
72+
73+
Upgrade each :binary:`~bin.mongod` and :binary:`~bin.mongos` binary
74+
separately. Follow this upgrade procedure:
75+
76+
#. For deployments that use authentication, first upgrade all of your
77+
MongoDB Drivers. To upgrade, see the
78+
:driver:`documentation for your driver </>`.
79+
80+
#. Upgrade any standalone instances. See
81+
:ref:`upgrade-mongodb-instance`.
82+
83+
#. Upgrade any replica sets that are not part of a sharded cluster, as
84+
described in :ref:`upgrade-replica-set`.
85+
86+
#. Upgrade sharded clusters, as described in
87+
:ref:`upgrade-sharded-cluster`.
88+
89+
.. _upgrade-mongodb-instance:
90+
91+
Upgrade a MongoDB Instance
92+
~~~~~~~~~~~~~~~~~~~~~~~~~~
93+
94+
To upgrade a {+latest-lts-version+} :binary:`~bin.mongod` or
95+
:binary:`~bin.mongos` instance, use one of these approaches:
96+
97+
- Upgrade the instance using the operating system's package management
98+
tool and the official MongoDB packages. This is the preferred
99+
approach. See :doc:`/installation`.
100+
101+
- Upgrade the instance by replacing the existing binaries with new
102+
binaries. See :ref:`upgrade-replace-binaries`.
103+
104+
.. _upgrade-replace-binaries:
105+
106+
Replace the Existing Binaries
107+
`````````````````````````````
108+
109+
This section describes how to upgrade MongoDB by replacing the existing
110+
binaries. The preferred approach to an upgrade is to use the operating
111+
system's package management tool and the official MongoDB packages, as
112+
described in :doc:`/installation`.
113+
114+
To upgrade a :binary:`~bin.mongod` or :binary:`~bin.mongos` instance by
115+
replacing the existing binaries:
116+
117+
1. Download the binaries for the latest MongoDB patch release from the
118+
`MongoDB Download Page`_ and store the binaries in a temporary
119+
location. The binaries download as compressed files that uncompress
120+
to the directory structure used by the MongoDB installation.
121+
122+
#. Shutdown the instance.
123+
124+
#. Replace the existing MongoDB binaries with the downloaded binaries.
125+
126+
#. Make any required configuration file changes.
127+
128+
#. Restart the instance.
129+
130+
.. _`MongoDB Download Page`: https://www.mongodb.com/try/download/community?tck=docs_server
131+
132+
.. _upgrade-replica-set:
133+
134+
Upgrade Replica Sets
135+
~~~~~~~~~~~~~~~~~~~~
136+
137+
To upgrade a {+latest-lts-version+} replica set, upgrade each member
138+
individually, starting with the :term:`secondaries <secondary>` and
139+
finishing with the :term:`primary`. Plan the upgrade during a predefined
140+
maintenance window.
141+
142+
.. include:: /includes/upgrade-downgrade-replica-set.rst
143+
144+
Upgrade Secondaries
145+
```````````````````
146+
147+
Upgrade each secondary separately as follows:
148+
149+
1. Upgrade the secondary's :binary:`~bin.mongod` binary by following the
150+
instructions in :ref:`upgrade-mongodb-instance`.
151+
152+
#. After upgrading a secondary, wait for the secondary to recover to
153+
the ``SECONDARY`` state before upgrading the next instance. To
154+
check the member's state, issue :method:`rs.status()` in
155+
:binary:`~bin.mongosh`.
156+
157+
The secondary may briefly go into ``STARTUP2`` or ``RECOVERING``.
158+
This is normal. Make sure to wait for the secondary to fully recover
159+
to ``SECONDARY`` before you continue the upgrade.
160+
161+
Upgrade the Primary
162+
```````````````````
163+
164+
1. Step down the primary to initiate the normal :ref:`failover
165+
<replica-set-failover>` procedure. Using one of the following:
166+
167+
- The :method:`rs.stepDown()` helper in :binary:`~bin.mongosh`.
168+
169+
- The :dbcommand:`replSetStepDown` database command.
170+
171+
During failover, the set cannot accept writes. Typically this takes
172+
10-20 seconds. Plan the upgrade during a predefined maintenance
173+
window.
174+
175+
.. note:: Stepping down the primary is preferable to directly
176+
*shutting down* the primary. Stepping down expedites the
177+
failover procedure.
178+
179+
#. Once the primary has stepped down, call the :method:`rs.status()`
180+
method from :binary:`~bin.mongosh` until you see that another
181+
member has assumed the ``PRIMARY`` state.
182+
183+
#. Shut down the original primary and upgrade its instance by
184+
following the instructions in :ref:`upgrade-mongodb-instance`.
185+
186+
.. _upgrade-sharded-cluster:
187+
188+
Upgrade Sharded Clusters
189+
~~~~~~~~~~~~~~~~~~~~~~~~
190+
191+
To upgrade a {+latest-lts-version+} sharded cluster:
192+
193+
1. Disable the cluster's balancer as described in
194+
:ref:`sharding-balancing-disable-temporarily`.
195+
196+
#. Upgrade the :ref:`config servers <sharding-config-server>`.
197+
198+
To upgrade the config server replica set, use the procedures in
199+
:ref:`upgrade-replica-set`.
200+
201+
#. Upgrade each shard.
202+
203+
- If a shard is a replica set, upgrade the shard using the
204+
procedure titled :ref:`upgrade-replica-set`.
205+
206+
- If a shard is a standalone instance, upgrade the shard using the
207+
procedure titled
208+
:ref:`upgrade-mongodb-instance`.
209+
210+
#. Once the config servers and the shards have been upgraded, upgrade
211+
each :binary:`~bin.mongos` instance by following the instructions in
212+
:ref:`upgrade-mongodb-instance`. You can upgrade the
213+
:binary:`~bin.mongos` instances in any order.
214+
215+
#. Re-enable the balancer, as described in :ref:`sharding-balancing-re-enable`.
216+
217+
Learn More
218+
----------
219+
220+
- :ref:`production-notes`
221+
222+
- :ref:`sharding-manage-shards`
223+
224+
- :ref:`replica-set-sync`

0 commit comments

Comments
 (0)