DOCSP-17295 document fCV downgrade considerations

andf-mongodb · andf-mongodb · commit 05bceebc894a · 2021-07-12T17:08:15.000-04:00
diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt
@@ -358,4 +358,11 @@ Some features in 5.0 require not just the 5.0 binaries but the
 features include:
 
 - Creation of :ref:`time series collections
-  <manual-timeseries-collection>`.
+  <manual-timeseries-collection>` requires fCV set to 5.0+.
+
+- Configuring Runtime Audit Filter Management requires fCV set to 5.0+.
+
+- Usage of ``.`` and ``$`` in field names requires fCV set to 5.0+.
+
+- :ref:`Resharding a collection <sharding-resharding>` requires fCV set
+  to 5.0+.
diff --git a/source/release-notes/5.0-downgrade-replica-set.txt b/source/release-notes/5.0-downgrade-replica-set.txt
@@ -40,25 +40,71 @@ Prerequisites
 
 To downgrade from |newversion| to |oldversion|, you must remove
 incompatible features that are persisted and/or update incompatible
-configuration settings.
+configuration settings. These include:
+
+1. Cluster Default Read and Write Concerns
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB 5.0 changed the default value for cluster-wide read and write
+concerns, and downgrading to MongoDB 4.4 might change those defaults
+back. Consider manually configuring your cluster's default read and
+write concern before downgrading:
+
+- To manually configure a default value for a cluster's read or write
+  concern, use the :dbcommand:`setDefaultRWConcern` command.
+
+- If your cluster includes an :doc:`arbiter
+  </core/replica-set-arbiter>`, and you had previously disabled
+  ``"Majority"`` read concern to prevent cache pressure in certain
+  situations, you may want to configure
+  :option:`--enableMajorityReadConcern false
+  <mongod --enableMajorityReadConcern>` or
+  :setting:`replication.enableMajorityReadConcern: false
+  <replication.enableMajorityReadConcern>` once you downgrade.
+
+2. Document Fields with ``.`` or ``$`` Characters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB 5.0 adds support for including the ``.`` or ``$`` characters in
+document field names. You must delete any documents containing field
+names that include the ``.`` or ``$`` characters before downgrading
+to MongoDB 4.4.
+
+3. Slim-format Timezone Data Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB 5.0 enables support for slim-format timezone data files. If
+using slim-format timezone data files in your deployment, as provided
+to MongoDB with the :option:`--timeZoneInfo <mongod --timeZoneInfo>`
+command line option or :setting:`processManagement.timeZoneInfo`
+configuration file setting, you must downgrade to MongoDB 4.4.7 or
+later, or else revert your timezone data files to use the previous
+non-slim-format data files.
 
 .. |target| replace:: primary
 
 .. _5.0-downgrade-feature-compatibility-rs:
 
-1. Downgrade Feature Compatibility Version (fCV)
+4. Downgrade Feature Compatibility Version (fCV)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. tip::
+First, verify the following:
 
-   - Ensure that no initial sync is in progress. Running
-     :dbcommand:`setFeatureCompatibilityVersion` command while an
-     initial sync is in progress will cause the initial sync to restart.
+- Ensure that no initial sync is in progress. Running
+  :dbcommand:`setFeatureCompatibilityVersion` command while an
+  initial sync is in progress will cause the initial sync to restart.
 
-   - Ensure that no replica set member is in :replstate:`ROLLBACK` or
-     :replstate:`RECOVERING` state.
+- Ensure that no nodes have a ``newlyAdded`` field in their
+  :doc:`replica set configuration </reference/replica-configuration>`.
+  Use the :method:`rs.conf()` method on each node in your replica set to
+  verify this. The ``newlyAdded`` only appears in a node's replica set
+  configuration document during and shortly after an initial sync.
 
-To downgrade the ``featureCompatibilityVersion`` of your replica set:
+- Ensure that no replica set member is in :replstate:`ROLLBACK` or
+  :replstate:`RECOVERING` state.
+
+Next, to downgrade the ``featureCompatibilityVersion`` of your replica
+set:
 
 #. Connect a :binary:`~bin.mongo` shell to the |target|.
 
@@ -84,7 +130,7 @@ To downgrade the ``featureCompatibilityVersion`` of your replica set:
 For more information on the returned ``featureCompatibilityVersion``
 value, see :ref:`view-fcv`.
 
-2. Remove fCV |newversion| Persisted Features
+5. Remove fCV |newversion| Persisted Features
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following steps are necessary only if fCV has ever been set to
@@ -93,17 +139,26 @@ The following steps are necessary only if fCV has ever been set to
 Remove all persisted |newversion| |features| that are incompatible with
 |oldversion|. These include:
 
-- This list is forthcoming.
+Time-series Collections
+  Remove all :ref:`time series collections
+  <manual-timeseries-collection>`.
+
+Runtime Audit Filter Management
+  Disable runtime audit filter management by setting the 
+  ``auditLog.runtimeConfiguration`` configuration file setting to
+  ``false``.
 
 .. |binary| replace:: any replica set member
 
-3. Remove |newversion| Features
+6. Remove |newversion| Features
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Remove all persisted features that use |newversion| features. These
 include but are not limited to:
 
-- This list is forthcoming.
+- If any view definitions include 5.0 operators, such as
+  :expression:`$dateAdd` or :expression:`$sampleRate`, they must be
+  removed. See :ref:`5.0-rel-notes-new-agg-operators` for the full list.
 
 Procedure
 ---------
diff --git a/source/release-notes/5.0-downgrade-sharded-cluster.txt b/source/release-notes/5.0-downgrade-sharded-cluster.txt
@@ -34,29 +34,84 @@ Prerequisites
 
 To downgrade from |newversion| to |oldversion|, you must remove
 incompatible features that are persisted and/or update incompatible
-configuration settings.
+configuration settings. These include:
+
+1. Cluster Default Read and Write Concerns
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB 5.0 changed the default value for cluster-wide read and write
+concerns, and downgrading to MongoDB 4.4 might change those defaults
+back. Consider manually configuring your cluster's default read and
+write concern before downgrading:
+
+- To manually configure a default value for a cluster's read or write
+  concern, use the :dbcommand:`setDefaultRWConcern` command.
+
+- If your cluster includes an :doc:`arbiter
+  </core/replica-set-arbiter>`, and you had previously disabled
+  ``"Majority"`` read concern to prevent cache pressure in certain
+  situations, you may want to configure
+  :option:`--enableMajorityReadConcern false
+  <mongod --enableMajorityReadConcern>` or
+  :setting:`replication.enableMajorityReadConcern: false
+  <replication.enableMajorityReadConcern>` once you downgrade.
+
+2. Document Fields with ``.`` or ``$`` Characters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB 5.0 adds support for including the ``.`` or ``$`` characters in
+document field names. You must delete any documents containing field
+names that include the ``.`` or ``$`` characters before downgrading
+to MongoDB 4.4.
+
+3. Slim-format Timezone Data Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB 5.0 enables support for slim-format timezone data files. If
+using slim-format timezone data files in your deployment, as provided
+to MongoDB with the :option:`--timeZoneInfo <mongod --timeZoneInfo>`
+command line option or :setting:`processManagement.timeZoneInfo`
+configuration file setting, you must downgrade to MongoDB 4.4.7 or
+later, or else revert your timezone data files to use the previous
+non-slim-format data files.
+
+4. Resharding
+~~~~~~~~~~~~~
+
+Ensure that any :ref:`resharding operations <sharding-resharding>` have
+successfully completed before attempting any downgrade procedure. If a
+recent resharding operation has failed due to a primary failover, you
+must first run the :dbcommand:`cleanupReshardCollection` command before
+downgrading the ``featureCompatibilityVersion`` of your sharded cluster.
+
+If a resharding operation is still running while you downgrade the
+``featureCompatibilityVersion`` of your sharded cluster, the resharding
+operation will abort.
 
-.. note::
+.. |target| replace:: :binary:`~bin.mongos` instance
 
-   If you ran a :ref:`resharding operation <sharding-resharding>` and a
-   primary failover occurred during the resharding operation, you must
-   run :dbcommand:`cleanupReshardCollection` before downgrading the
-   ``featureCompatibilityVersion`` of your sharded cluster.
+.. _5.0-downgrade-feature-compatibility-sharded-cluster:
 
-   If you started a :ref:`resharding operation <sharding-resharding>`,
-   and it is still running while you downgrade the
-   ``featureCompatibilityVersion`` of your sharded cluster, the
-   resharding operation will abort.
+5. Downgrade Feature Compatibility Version (fCV)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+First, verify the following:
 
-.. |target| replace:: :binary:`~bin.mongos` instance
+- Ensure that no initial sync is in progress. Running
+  :dbcommand:`setFeatureCompatibilityVersion` command while an
+  initial sync is in progress will cause the initial sync to restart.
 
-.. _5.0-downgrade-feature-compatibility-sharded-cluster:
+- Ensure that no nodes have a ``newlyAdded`` field in their
+  :doc:`replica set configuration </reference/replica-configuration>`.
+  Use the :method:`rs.conf()` method on each node in your sharded
+  cluster to verify this. The ``newlyAdded`` only appears in a node's
+  replica set configuration document during and shortly after an initial
+  sync.
 
-1. Downgrade Feature Compatibility Version (fCV)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- Ensure that no replica set member is in :replstate:`ROLLBACK` or
+  :replstate:`RECOVERING` state.
 
-To downgrade the ``featureCompatibilityVersion`` of your sharded
+Next, to downgrade the ``featureCompatibilityVersion`` of your sharded
 cluster:
 
 #. Connect a :binary:`~bin.mongo` shell to the |target|.
@@ -65,9 +120,16 @@ cluster:
 
    .. note:: 
 
-      While :dbcommand:`setFeatureCompatibilityVersion` is running on
-      the sharded cluster, chunk migrations, splits, and merges
-      can fail with ``ConflictingOperationInProgress``.
+      - While :dbcommand:`setFeatureCompatibilityVersion` is running on
+        the sharded cluster, chunk migrations, splits, and merges can
+        fail with ``ConflictingOperationInProgress``.
+
+      - If :dbcommand:`setFeatureCompatibilityVersion` fails with a
+        ``ManualInterventionRequired`` error, and the cluster has
+        recently undergone a resharding operation that had failed due to
+        an election, you must run the ``cleanupReshardCollection``
+        command before attempting
+        :dbcommand:`setFeatureCompatibilityVersion` again.
 
 #. To ensure that all members of the sharded cluster reflect the
    updated ``featureCompatibilityVersion``, connect to each shard replica
@@ -97,7 +159,7 @@ cluster:
 For more information on the returned ``featureCompatibilityVersion``
 value, see :ref:`view-fcv`.
 
-2. Remove fCV |newversion| Persisted Features
+6. Remove fCV |newversion| Persisted Features
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following steps are necessary only if fCV has ever been set to
@@ -106,15 +168,24 @@ The following steps are necessary only if fCV has ever been set to
 Remove all persisted |newversion| |features| that are incompatible with
 |oldversion|. These include:
 
-- This list is forthcoming.
+Time-series Collections
+  Remove all :ref:`time series collections
+  <manual-timeseries-collection>`.
+
+Runtime Audit Filter Management
+  Disable runtime audit filter management by setting the 
+  ``auditLog.runtimeConfiguration`` configuration file setting to
+  ``false``.
 
-3. Remove |newversion| Features
+7. Remove |newversion| Features
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Remove all persisted features that use |newversion| features. These
 include but are not limited to:
 
-- This list is forthcoming.
+- If any view definitions include 5.0 operators, such as
+  :expression:`$dateAdd` or :expression:`$sampleRate`, they must be
+  removed. See :ref:`5.0-rel-notes-new-agg-operators` for the full list.
 
 .. |binary| replace:: any :binary:`~bin.mongod`/:binary:`~bin.mongos` instance
 
diff --git a/source/release-notes/5.0-downgrade-standalone.txt b/source/release-notes/5.0-downgrade-standalone.txt
@@ -41,11 +41,50 @@ To downgrade from |newversion| to |oldversion|, you must remove
 incompatible features that are persisted and/or update incompatible
 configuration settings. These include:
 
+1. Cluster Default Read and Write Concerns
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB 5.0 changed the default value for cluster-wide read and write
+concerns, and downgrading to MongoDB 4.4 might change those defaults
+back. Consider manually configuring your cluster's default read and
+write concern before downgrading:
+
+- To manually configure a default value for a cluster's read or write
+  concern, use the :dbcommand:`setDefaultRWConcern` command.
+
+- If your cluster includes an :doc:`arbiter
+  </core/replica-set-arbiter>`, and you had previously disabled
+  ``"Majority"`` read concern to prevent cache pressure in certain
+  situations, you may want to configure
+  :option:`--enableMajorityReadConcern false
+  <mongod --enableMajorityReadConcern>` or
+  :setting:`replication.enableMajorityReadConcern: false
+  <replication.enableMajorityReadConcern>` once you downgrade.
+
+2. Document Fields with ``.`` or ``$`` Characters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB 5.0 adds support for including the ``.`` or ``$`` characters in
+document field names. You must delete any documents containing field
+names that include the ``.`` or ``$`` characters before downgrading
+to MongoDB 4.4.
+
+3. Slim-format Timezone Data Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB 5.0 enables support for slim-format timezone data files. If
+using slim-format timezone data files in your deployment, as provided
+to MongoDB with the :option:`--timeZoneInfo <mongod --timeZoneInfo>`
+command line option or :setting:`processManagement.timeZoneInfo`
+configuration file setting, you must downgrade to MongoDB 4.4.7 or
+later, or else revert your timezone data files to use the previous
+non-slim-format data files.
+
 .. |target| replace:: :binary:`~bin.mongod` instance
 
 .. _5.0-downgrade-feature-compatibility-standalone:
 
-1. Downgrade Feature Compatibility Version (fCV)
+4. Downgrade Feature Compatibility Version (fCV)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To downgrade the ``featureCompatibilityVersion`` of your standalone:
@@ -54,7 +93,7 @@ To downgrade the ``featureCompatibilityVersion`` of your standalone:
 
 #. .. include:: /includes/5.0-downgrade-fcv.rst
 
-2. Remove fCV |newversion| Persisted Features
+5. Remove fCV |newversion| Persisted Features
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following steps are necessary only if fCV has ever been set to
@@ -63,17 +102,26 @@ The following steps are necessary only if fCV has ever been set to
 Remove all persisted |newversion| |features| that are incompatible with
 |oldversion|. These include:
 
-- This list is forthcoming.
+Time-series Collections
+  Remove all :ref:`time series collections
+  <manual-timeseries-collection>`.
+
+Runtime Audit Filter Management
+  Disable runtime audit filter management by setting the 
+  ``auditLog.runtimeConfiguration`` configuration file setting to
+  ``false``.
 
 .. |binary| replace:: the :binary:`~bin.mongod` instance
 
-3. Remove |newversion| Features
+6. Remove |newversion| Features
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Remove all persisted features that use |newversion| features. These
 include but are not limited to:
 
-- This list is forthcoming.
+- If any view definitions include 5.0 operators, such as
+  :expression:`$dateAdd` or :expression:`$sampleRate`, they must be
+  removed. See :ref:`5.0-rel-notes-new-agg-operators` for the full list.
 
 Procedure
 ---------
diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt
@@ -26,6 +26,8 @@ usage for your data and indexes.
 Aggregation
 -----------
 
+.. _5.0-rel-notes-new-agg-operators:
+
 New Aggregation Operators
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
