Skip to content

Commit 72c83b7

Browse files
kennethdyerkennethdyer
authored
DOCS-13029 Backport to 4.4 (#1131)
1 parent 696f4f6 commit 72c83b7

10 files changed

+487
-0
lines changed

‎source/core/replica-set-arbiter.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,13 @@ Replica Set Protocol Version and Arbiter
7171

7272
.. include:: /includes/extracts/arbiters-and-pvs-with-reference.rst
7373

74+
For more information, see the :dbcommand:`setFeatureCompatibilityVersion` command.
75+
76+
Feature Compatibility Version
77+
-----------------------------
78+
79+
.. include:: /includes/arbiter-fcv.rst
80+
7481
.. _rollbacks-multi-arbiters:
7582

7683
Don't Deploy Multiple Arbiters

‎source/includes/arbiter-fcv-version.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
2+
For example, an arbiter in a MongoDB |newversion| cluster, has an FCV
3+
value of |oldversion|.

‎source/includes/arbiter-fcv.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
2+
Arbiters do not replicate the :data:`admin.system.version` collection.
3+
Because of this, arbiters always have a Feature Compatibility Version equal
4+
to the downgrade version of the binary, regardless of the FCV value of the
5+
replica set.

‎source/reference/command/setFeatureCompatibilityVersion.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,14 @@ This command must perform writes to an internal system collection. If
160160
for any reason the command does not complete successfully, you can
161161
safely retry the command as the operation is idempotent.
162162

163+
Feature Compatibility in Arbiters
164+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
165+
166+
.. include:: /includes/arbiter-fcv.rst
167+
168+
For example, an arbiter in a MongoDB 5.0 cluster, has an FCV
169+
value of 4.4.
170+
163171
Examples
164172
--------
165173

‎source/release-notes/4.2-downgrade-replica-set.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,13 @@ To downgrade the ``featureCompatibilityVersion`` of your replica set:
9090
If any member returns a ``featureCompatibilityVersion`` of ``"4.2"``,
9191
wait for the member to reflect version ``"4.0"`` before proceeding.
9292

93+
.. note::
94+
95+
.. include:: /includes/arbiter-fcv.rst
96+
97+
.. include:: /includes/arbiter-fcv-version.rst
98+
99+
93100
For more information on the returned ``featureCompatibilityVersion``
94101
value, see :ref:`view-fcv`.
95102

‎source/release-notes/4.2-downgrade-sharded-cluster.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,13 @@ cluster:
8686
If any member returns a ``featureCompatibilityVersion`` of ``"4.2"``,
8787
wait for the member to reflect version ``"4.0"`` before proceeding.
8888

89+
.. note::
90+
91+
.. include:: /includes/arbiter-fcv.rst
92+
93+
.. include:: /includes/arbiter-fcv-version.rst
94+
95+
8996
For more information on the returned ``featureCompatibilityVersion``
9097
value, see :ref:`view-fcv`.
9198

‎source/release-notes/4.4-downgrade-replica-set.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,13 @@ To downgrade the ``featureCompatibilityVersion`` of your replica set:
136136
For more information on the returned ``featureCompatibilityVersion``
137137
value, see :ref:`view-fcv`.
138138

139+
.. note::
140+
141+
.. include:: /includes/arbiter-fcv.rst
142+
143+
.. include:: /includes/arbiter-fcv-version.rst
144+
145+
139146
3. Remove FCV |newversion| Persisted Features
140147
`````````````````````````````````````````````
141148

‎source/release-notes/4.4-downgrade-sharded-cluster.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,13 @@ cluster:
144144
If any member returns a ``featureCompatibilityVersion`` of |newfcv|,
145145
wait for the member to reflect version |oldfcv| before proceeding.
146146

147+
.. note::
148+
149+
.. include:: /includes/arbiter-fcv.rst
150+
151+
.. include:: /includes/arbiter-fcv-version.rst
152+
153+
147154
For more information on the returned ``featureCompatibilityVersion``
148155
value, see :ref:`view-fcv`.
149156

‎source/release-notes/5.0-downgrade-replica-set.txt‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
==================================================
2+
Downgrade |newversion| Replica Set to |oldversion|
3+
==================================================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. include:: /includes/5.0-upgrade-replacements.rst
14+
15+
Before you attempt any downgrade, familiarize yourself with the content
16+
of this document.
17+
18+
.. |downgrading| replace:: downgrading
19+
20+
Downgrade Path
21+
--------------
22+
23+
.. include:: /includes/downgrade-path.rst
24+
25+
Create Backup
26+
-------------
27+
28+
*Optional but Recommended.* Create a backup of your database.
29+
30+
Access Control
31+
--------------
32+
33+
If your replica set has access control enabled, your downgrade user
34+
privileges must include privileges to list and manage indexes across
35+
databases. A user with :authrole:`root` role has the required
36+
privileges.
37+
38+
Prerequisites
39+
-------------
40+
41+
To downgrade from |newversion| to |oldversion|, you must remove
42+
incompatible features that are persisted and/or update incompatible
43+
configuration settings. These include:
44+
45+
1. Cluster Default Read and Write Concerns
46+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47+
48+
MongoDB 5.0 changed the default value for cluster-wide read and write
49+
concerns, and downgrading to MongoDB 4.4 might change those defaults
50+
back. Consider manually configuring your cluster's default read and
51+
write concern before downgrading:
52+
53+
- To manually configure a default value for a cluster's read or write
54+
concern, use the :dbcommand:`setDefaultRWConcern` command.
55+
56+
- If your cluster includes an :doc:`arbiter
57+
</core/replica-set-arbiter>`, and you had previously disabled
58+
``"Majority"`` read concern to prevent cache pressure in certain
59+
situations, you may want to configure
60+
:option:`--enableMajorityReadConcern false
61+
<mongod --enableMajorityReadConcern>` or
62+
:setting:`replication.enableMajorityReadConcern: false
63+
<replication.enableMajorityReadConcern>` once you downgrade.
64+
65+
2. Document Fields with ``.`` or ``$`` Characters
66+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
67+
68+
MongoDB 5.0 adds support for including the ``.`` or ``$`` characters in
69+
document field names. You must delete any documents containing field
70+
names that include the ``.`` or ``$`` characters before downgrading
71+
to MongoDB 4.4.
72+
73+
3. Slim-format Timezone Data Files
74+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75+
76+
MongoDB 5.0 enables support for slim-format timezone data files. If
77+
using slim-format timezone data files in your deployment, as provided
78+
to MongoDB with the :option:`--timeZoneInfo <mongod --timeZoneInfo>`
79+
command line option or :setting:`processManagement.timeZoneInfo`
80+
configuration file setting, you must downgrade to MongoDB 4.4.7 or
81+
later, or else revert your timezone data files to use the previous
82+
non-slim-format data files.
83+
84+
.. |target| replace:: primary
85+
86+
.. _5.0-downgrade-feature-compatibility-rs:
87+
88+
4. Downgrade Feature Compatibility Version (fCV)
89+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
90+
91+
First, verify the following:
92+
93+
- Ensure that no initial sync is in progress. Running
94+
:dbcommand:`setFeatureCompatibilityVersion` command while an
95+
initial sync is in progress will cause the initial sync to restart.
96+
97+
- Ensure that no nodes have a ``newlyAdded`` field in their
98+
:doc:`replica set configuration </reference/replica-configuration>`.
99+
Run the following command on each node in your replica set to
100+
verify this:
101+
102+
.. code-block:: javascript
103+
104+
use local
105+
db.system.replset.find( { "members.newlyAdded" : { $exists : true } } );
106+
107+
The ``newlyAdded`` field only appears in a node's replica set
108+
configuration document during and shortly after an initial sync.
109+
110+
- Ensure that no replica set member is in :replstate:`ROLLBACK` or
111+
:replstate:`RECOVERING` state.
112+
113+
Next, to downgrade the ``featureCompatibilityVersion`` of your replica
114+
set:
115+
116+
#. Connect a :binary:`~bin.mongo` shell to the |target|.
117+
118+
#. .. include:: /includes/5.0-downgrade-fcv.rst
119+
120+
#. To ensure that all members of the replica set reflect the updated
121+
``featureCompatibilityVersion``, connect to each replica set member and
122+
check the ``featureCompatibilityVersion``:
123+
124+
.. code-block:: javascript
125+
126+
db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
127+
128+
All members should return a result that includes:
129+
130+
.. code-block:: javascript
131+
132+
"featureCompatibilityVersion" : { "version" : "4.4" }
133+
134+
If any member returns a ``featureCompatibilityVersion`` of |newfcv|,
135+
wait for the member to reflect version |oldfcv| before proceeding.
136+
137+
.. note::
138+
139+
.. include:: /includes/arbiter-fcv.rst
140+
141+
.. include:: /includes/arbiter-fcv-version.rst
142+
143+
For more information on the returned ``featureCompatibilityVersion``
144+
value, see :ref:`view-fcv`.
145+
146+
5. Remove fCV |newversion| Persisted Features
147+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
148+
149+
The following steps are necessary only if fCV has ever been set to
150+
|newfcv|.
151+
152+
Remove all persisted |newversion| |features| that are incompatible with
153+
|oldversion|. These include:
154+
155+
Time-series Collections
156+
Remove all :ref:`time series collections
157+
<manual-timeseries-collection>`.
158+
159+
Runtime Audit Filter Management
160+
161+
- Reset the defaults on the :term:`primary` server in the group with
162+
``db.admin.runCommand``. The primary should be the last
163+
configuration server in the group to be updated.
164+
165+
.. code-block:: javascript
166+
167+
db.admin.runCommand(
168+
{
169+
setAuditConfig: 1,
170+
filter: {},
171+
auditAuthorizationSuccess: false
172+
}
173+
)
174+
175+
The configuration document can also be removed after downgrade:
176+
177+
.. code-block:: javascript
178+
179+
config.settings.remove({_id: 'audit'});
180+
181+
- Disable Runtime Audit Filter Management on each node by setting
182+
``auditLog.runtimeConfiguration`` to ``false`` in the node's
183+
configuration file.
184+
185+
- Update the audit filters for this instance in the local
186+
configuration file.
187+
188+
.. |binary| replace:: any replica set member
189+
190+
6. Remove |newversion| Features
191+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
192+
193+
Remove all persisted features that use |newversion| features. These
194+
include but are not limited to:
195+
196+
- If any view definitions include 5.0 operators, such as
197+
:expression:`$dateAdd` or :expression:`$sampleRate`, they must be
198+
removed. See :ref:`5.0-rel-notes-new-agg-operators` for the full list.
199+
200+
Procedure
201+
---------
202+
203+
.. warning::
204+
205+
Before proceeding with the downgrade procedure, ensure that all
206+
replica set members, including delayed replica set members, reflect
207+
the prerequisite changes. That is, check the
208+
``featureCompatibilityVersion`` and the removal of incompatible
209+
features for each node before downgrading.
210+
211+
.. include:: /includes/steps/5.0-downgrade-replica-set.rst
212+
213+

0 commit comments

Comments
 (0)