-
Notifications
You must be signed in to change notification settings - Fork 1.7k
/
Copy pathupgrade-revision.txt
272 lines (184 loc) · 8.97 KB
/
upgrade-revision.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
=========================================
Upgrade to the Latest Revision of MongoDB
=========================================
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
.. include:: /includes/rapid-release.rst
:ref:`MongoDB versioning <release-version-numbers>` have the form
``X.Y.Z`` where ``Z`` refers to the revision/patch number.
Revisions provide security patches, bug fixes, and new or changed
features that generally do not contain any backward breaking changes.
Always upgrade to the latest revision in your release series.
For more information on versioning, see :ref:`release-version-numbers`.
.. _upgrade-options:
Before Upgrading
----------------
Backup
~~~~~~
Ensure you have an up-to-date backup of your data set. See
:doc:`/core/backups`.
Compatibility Considerations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Consult the following documents for any special considerations or
compatibility issues specific to your MongoDB release:
- The release notes, located at :doc:`/release-notes`.
- The :driver:`documentation for your driver </>`.
.. important::
- Starting in MongoDB 4.2, MongoDB removes support for Ubuntu 16.04
PPCLE.
- Starting in MongoDB 3.6.13, MongoDB 3.6-series removes support for
Ubuntu 16.04 PPCLE.
- Starting in MongoDB 3.4.21, MongoDB 3.4-series removes support for
Ubuntu 16.04 PPCLE.
Maintenance Window
~~~~~~~~~~~~~~~~~~
If your installation includes :term:`replica sets <replica set>`, plan
the upgrade during a predefined maintenance window.
Change Streams
~~~~~~~~~~~~~~
Starting in MongoDB 4.0.7, change streams use version 1 ``v1`` resume
tokens. MongoDB versions earlier than 4.0.7 use ``v0`` resume tokens.
When upgrading from MongoDB 4.0.6 or earlier to MongoDB 4.0.7 or later,
a client may try to resume change streams using the new ``v1`` resume
token when connected to a member that has not been updated (i.e. only
accepts ``v0`` or BinData token) and fail. In such cases, the client
must wait for the upgrade to complete before resuming change streams.
Staging Environment Check
~~~~~~~~~~~~~~~~~~~~~~~~~~
Before you upgrade a production environment, use the procedures in this
document to upgrade a *staging* environment that reproduces your
production environment, to ensure that your production configuration is
compatible with all changes.
.. _upgrade-procedure:
Upgrade Procedure
-----------------
.. important:: Always backup all of your data before upgrading MongoDB.
Upgrade each :binary:`~bin.mongod` and :binary:`~bin.mongos` binary
separately, using the procedure described here. When upgrading a binary,
use the procedure :ref:`upgrade-mongodb-instance`.
Follow this upgrade procedure:
1. For deployments that use authentication, first upgrade all of your
MongoDB Drivers. To upgrade, see the
:driver:`documentation for your driver </>`.
#. Upgrade sharded clusters, as described in
:ref:`upgrade-sharded-cluster`.
#. Upgrade any standalone instances. See
:ref:`upgrade-mongodb-instance`.
#. Upgrade any replica sets that are not part of a sharded cluster, as
described in :ref:`upgrade-replica-set`.
.. _upgrade-mongodb-instance:
Upgrade a MongoDB Instance
--------------------------
To upgrade a :binary:`~bin.mongod` or :binary:`~bin.mongos` instance,
use one of these approaches:
- Upgrade the instance using the operating system's package management
tool and the official MongoDB packages. This is the preferred
approach. See :doc:`/installation`.
- Upgrade the instance by replacing the existing binaries with new
binaries. See :ref:`upgrade-replace-binaries`.
- Make any required configuration file changes before restarting the
instance.
.. _upgrade-replace-binaries:
Replace the Existing Binaries
-----------------------------
.. important:: Always backup all of your data before upgrading MongoDB.
This section describes how to upgrade MongoDB by replacing the existing
binaries. The preferred approach to an upgrade is to use the operating
system's package management tool and the official MongoDB packages, as
described in :doc:`/installation`.
To upgrade a :binary:`~bin.mongod` or :binary:`~bin.mongos` instance by
replacing the existing binaries:
1. Download the binaries for the latest MongoDB revision from the
`MongoDB Download Page`_ and store the binaries in a temporary
location. The binaries download as compressed files that uncompress
to the directory structure used by the MongoDB installation.
#. Shutdown the instance.
#. Replace the existing MongoDB binaries with the downloaded binaries.
#. Make any required configuration file changes.
#. Restart the instance.
.. _`MongoDB Download Page`: https://www.mongodb.com/try/download/community?tck=docs_server
.. _upgrade-replica-set:
Upgrade Replica Sets
--------------------
To upgrade a replica set, upgrade each member individually, starting with
the :term:`secondaries <secondary>` and finishing with the
:term:`primary`. Plan the upgrade during a predefined maintenance window.
.. include:: /includes/upgrade-downgrade-replica-set.rst
.. note::
Starting in MongoDB 4.0.7, change streams use version 1 ``v1``
:ref:`resume tokens <change-stream-resume-token>`. MongoDB versions
earlier than 4.0.7 use ``v0`` resume tokens or BinData resume tokens.
When upgrading from MongoDB 4.0.0-4.0.6 to MongoDB 4.0.7 or later,
a client may try to resume change streams using the new ``v1``
resume token when connected to a member that has not been updated
(i.e. only accepts ``v0`` token or BinData) and fail. In such cases, the
client must wait for the upgrade to complete before resuming change
streams.
Upgrade Secondaries
~~~~~~~~~~~~~~~~~~~
Upgrade each secondary separately as follows:
1. Upgrade the secondary's :binary:`~bin.mongod` binary by following the
instructions in :ref:`upgrade-mongodb-instance`.
#. After upgrading a secondary, wait for the secondary to recover to
the ``SECONDARY`` state before upgrading the next instance. To
check the member's state, issue :method:`rs.status()` in
:binary:`~bin.mongosh`.
The secondary may briefly go into ``STARTUP2`` or ``RECOVERING``.
This is normal. Make sure to wait for the secondary to fully recover
to ``SECONDARY`` before you continue the upgrade.
Upgrade the Primary
~~~~~~~~~~~~~~~~~~~
1. Step down the primary to initiate the normal :ref:`failover
<replica-set-failover>` procedure. Using one of the following:
- The :method:`rs.stepDown()` helper in :binary:`~bin.mongosh`.
- The :dbcommand:`replSetStepDown` database command.
During failover, the set cannot accept writes. Typically this takes
10-20 seconds. Plan the upgrade during a predefined maintenance
window.
.. note:: Stepping down the primary is preferable to directly
*shutting down* the primary. Stepping down expedites the
failover procedure.
#. Once the primary has stepped down, call the :method:`rs.status()`
method from :binary:`~bin.mongosh` until you see that another
member has assumed the ``PRIMARY`` state.
#. Shut down the original primary and upgrade its instance by
following the instructions in :ref:`upgrade-mongodb-instance`.
.. _upgrade-sharded-cluster:
Upgrade Sharded Clusters
------------------------
.. versionchanged:: 3.4
The procedure applies to {+latest-lts-version+}. To make revision
upgrades for other versions of MongoDB sharded clusters, refer to
the appropriate version of the manual.
.. note::
Starting in MongoDB 4.0.7, change streams use a version 1 ``v1``
:ref:`resume tokens <change-stream-resume-token>`. MongoDB versions
earlier than 4.0.7 use ``v0`` resume tokens or BinData resume tokens.
When upgrading from MongoDB 4.0.6 or earlier to 4.0.7 or later, the
members of the sharded clusters will continue to produce ``v0`` or
BinData resume tokens until the :binary:`~bin.mongos` instance(s)
are updated. Upgraded :binary:`~bin.mongos` instances will begin
producing ``v1`` change stream resume tokens. These tokens cannot be
used to resume a stream on a :binary:`~bin.mongos` that has not yet
been upgraded to 4.0.7 or later.
To upgrade a {+latest-lts-version+} sharded cluster:
1. Disable the cluster's balancer as described in
:ref:`sharding-balancing-disable-temporarily`.
#. Upgrade the :ref:`config servers <sharding-config-server>`.
To upgrade the config server replica set, use the procedures in
:ref:`upgrade-replica-set`.
#. Upgrade each shard.
- If a shard is a replica set, upgrade the shard using the
procedure titled :ref:`upgrade-replica-set`.
- If a shard is a standalone instance, upgrade the shard using the
procedure titled
:ref:`upgrade-mongodb-instance`.
#. Once the config servers and the shards have been upgraded, upgrade
each :binary:`~bin.mongos` instance by following the instructions in
:ref:`upgrade-mongodb-instance`. You can upgrade the
:binary:`~bin.mongos` instances in any order.
#. Re-enable the balancer, as described in :ref:`sharding-balancing-re-enable`.