(DOCSP-40116) Adds new FCV functionality. (#1854)

erabil-mdb · jwilliams-mongo · commit 7746ff0fd1f9 · 2025-04-14T17:11:24.000-05:00
* (DOCSP-40116) Adds new FCV functionality. * Revises per copy and tech reviews.
diff --git a/source/includes/facts/fact-fcv-setting.rst b/source/includes/facts/fact-fcv-setting.rst
@@ -0,0 +1,8 @@
+.. note::
+   
+   If you update this value to a later version of MongoDB for your 
+   database resources, the feature compatibility version remains 
+   at the MongoDB version you're upgrading from to give you the option to downgrade if necessary.
+   If you want the feature compatibility version to match the new MongoDB version, you must manually set 
+   :setting:`spec.featureCompatibilityVersion` to the new version or to ``AlwaysMatchVersion``.
+   To learn more, see :setting:`spec.featureCompatibilityVersion`.
diff --git a/source/includes/om-upgrade-master-version.rst b/source/includes/om-upgrade-master-version.rst
@@ -4,9 +4,6 @@ a. Set :opsmgrkube:`spec.version` to the new |onprem| version.
    :opsmgrkube:`spec.applicationDatabase.version` to the compatible MongoDB 
    version. 
 
-c. *(Optional)* If you might need to downgrade, set 
-   :setting:`spec.featureCompatibilityVersion`.
-
 
 .. literalinclude:: /reference/k8s/example-ops-manager.yaml
   :language: yaml
diff --git a/source/includes/setting-k8sRsConf-spec.backup.snapshotSchedule.clusterCheckpointIntervalMin.rst b/source/includes/setting-k8sRsConf-spec.backup.snapshotSchedule.clusterCheckpointIntervalMin.rst
@@ -4,7 +4,7 @@
 
    
    Number of minutes between successive cluster checkpoints. This setting
-   applies only to sharded clusters that run MongoDB with FCV of 4.0 or
+   applies only to sharded clusters that run MongoDB with a feature compatibility version of 4.0 or
    earlier. This number determines the granularity of point-in-time
    restores for sharded clusters. You can set a value of ``15``, ``30``,
    or ``60``.
diff --git a/source/includes/setting-k8sRsConf-spec.version.rst b/source/includes/setting-k8sRsConf-spec.version.rst
@@ -6,12 +6,6 @@
    
    .. include:: /includes/admonitions/ubi-8-min-db-versions.rst
    
-   .. note::
-   
-      If you update this value to a later version of MongoDB for your 
-      database resources, the Feature Compatibility Version (FCV) changes 
-      automatically to this version unless you set :setting:`spec.featureCompatibilityVersion` 
-      to the original version. Consider setting :setting:`spec.featureCompatibilityVersion` 
-      to the original version to give yourself the option to downgrade if necessary.
+   .. include:: /includes/facts/fact-fcv-setting.rst
    
 
diff --git a/source/includes/setting-k8sSaConf-spec.featureCompatibilityVersion.rst b/source/includes/setting-k8sSaConf-spec.featureCompatibilityVersion.rst
@@ -2,10 +2,21 @@
 
    *Type*: string
 
+   *Defaults to the prior major MongoDB version after MongoDB upgrade.*
    
    Limits changes to data that occur with an upgrade to a
-   new major version. This allows you to downgrade to the previous major
-   version. To learn more about feature compatibility, see
-   :dbcommand:`setFeatureCompatibilityVersion` in the MongoDB Manual.
+   new major version. For example, if you upgrade from MongoDB 5.0 to MongoDB 6.0, 
+   the feature compatibility version remains 
+   at 5.0 to give you the option to downgrade if necessary.
+   
+   If you want the feature compatibility version to match the new MongoDB version, you must manually set ``featureCompatibilityVersion``
+   to the new version. 
+   For example, ``featureCompatibilityVersion: 6.0``.
    
+   Alternatively, you can enable the ``AlwaysMatchVersion`` option to automatically 
+   update the feature compatibility version to match the MongoDB version during upgrades. 
+   For example, ``featureCompatibilityVersion: AlwaysMatchVersion``.
 
+   To learn more about feature compatibility, see
+   :dbcommand:`setFeatureCompatibilityVersion` in the MongoDB Manual.
+   
diff --git a/source/includes/setting-k8sSaConf-spec.version.rst b/source/includes/setting-k8sSaConf-spec.version.rst
@@ -6,12 +6,6 @@
    
    .. include:: /includes/admonitions/ubi-8-min-db-versions.rst
    
-   .. note::
-   
-      If you update this value to a later version of MongoDB for your 
-      database resources, the Feature Compatibility Version (FCV) changes 
-      automatically to this version unless you set :setting:`spec.featureCompatibilityVersion` 
-      to the original version. Consider setting :setting:`spec.featureCompatibilityVersion` 
-      to the original version to give yourself the option to downgrade if necessary.
+   .. include:: /includes/facts/fact-fcv-setting.rst
    
 
diff --git a/source/includes/setting-k8sScConf-spec.version.rst b/source/includes/setting-k8sScConf-spec.version.rst
@@ -6,12 +6,6 @@
    
    .. include:: /includes/admonitions/ubi-8-min-db-versions.rst
    
-   .. note::
-   
-      If you update this value to a later version of MongoDB for your 
-      database resources, the Feature Compatibility Version (FCV) changes 
-      automatically to this version unless you set :setting:`spec.featureCompatibilityVersion` 
-      to the original version. Consider setting :setting:`spec.featureCompatibilityVersion` 
-      to the original version to give yourself the option to downgrade if necessary.
+   .. include:: /includes/facts/fact-fcv-setting.rst
    
 
diff --git a/source/includes/steps-upgrade-mdb.yaml b/source/includes/steps-upgrade-mdb.yaml
@@ -5,14 +5,9 @@ inherit:
   file: steps-upgrade-master.yaml
   ref: upgrade-master-version
 replacement:
-  method: "Change the settings in the :ref:`k8s-specification` as shown in the following example:"
+  method: "Set :setting:`spec.version` to the desired MongoDB version."
 content: |
 
-  a. Set :setting:`spec.version` to the desired MongoDB version.
-
-  #. Set :setting:`spec.featureCompatibilityVersion` to the current
-     working MongoDB version:
-
   .. code-block:: yaml
 
      ---
@@ -22,21 +17,12 @@ content: |
       name: my-standalone-downgrade
      spec:
       version: "4.4.18-ent"
-      featureCompatibilityVersion: "4.2"
       type: Standalone
       project: my-project
       credentials: my-credentials
       persistent: false
      ...
 
-  The following example shows the result of this change:
-  
-  .. code-block:: yaml
-
-    spec:
-      version: "4.4.18-ent"
-      featureCompatibilityVersion: "4.2"
-
 ---
 ref: apply
 inherit:
diff --git a/source/reference/k8s-operator-multi-cluster-specification.txt b/source/reference/k8s-operator-multi-cluster-specification.txt
@@ -80,13 +80,6 @@ This section describes settings that you must use for your |mongodb-multi|.
 
   .. include:: /includes/admonitions/ubi-8-min-db-versions.rst
 
-  .. note::
-
-     If you update this value to a later version, consider setting
-     :ref:`spec.featureCompatibilityVersion <multi-spec-fcv>` to give yourself the
-     option to downgrade if necessary.
-
-
 .. _optional-multi-k8s-settings:
 
 Optional ``MongoDBMultiCluster`` Resource Settings
diff --git a/source/reference/k8s-operator-om-specification.txt b/source/reference/k8s-operator-om-specification.txt
@@ -1529,8 +1529,10 @@ configure your |onprem| {+appdb+}.
    .. note::
 
       If you update this value to a later version of MongoDB for the 
-      {+appdb+}, the Feature Compatibility Version (FCV) *does 
-      not change* unless you also specify the 
+      {+appdb+}, the feature compatibility version remains at the MongoDB version 
+      you're upgrading from to give you the option to downgrade if necessary.
+      If you want the feature compatibility version to match the new MongoDB version, 
+      you must manually set the 
       ``featureCompatibilityVersion``
       parameter under :opsmgrkube:`spec.applicationDatabase`.
 
diff --git a/source/tutorial/upgrade-mdb-version.txt b/source/tutorial/upgrade-mdb-version.txt
@@ -1,8 +1,8 @@
 .. _meko-upgrade-mdb-version:
 
-===============================
-Upgrade MongoDB Version and FCV
-===============================
+=======================
+Upgrade MongoDB Version
+=======================
 
 .. default-domain:: mongodb
 
@@ -12,7 +12,7 @@ Upgrade MongoDB Version and FCV
    :depth: 2
    :class: singlecol
 
-You can upgrade the major, minor, or feature compatibility versions of
+You can upgrade the major or minor versions of
 your MongoDB resource. Configure these settings in your :ref:`k8s-specification`.
 
 Overview
@@ -21,32 +21,12 @@ Overview
 To upgrade your resource's major or minor versions, set the
 :setting:`spec.version` setting to the desired MongoDB version.
 
-To modify your resource's
-:manual:`feature compatibility version </reference/command/setFeatureCompatibilityVersion/>`,
-set the :setting:`spec.featureCompatibilityVersion` setting to the desired 
-version.
-
-.. note::
-
-   If you update ``spec.version`` to a later version, consider setting
-   :setting:`spec.featureCompatibilityVersion` to the current working
-   MongoDB version to give yourself the option to downgrade if
-   necessary. To learn more about feature compatibility, see
-   :dbcommand:`setFeatureCompatibilityVersion` in the MongoDB Server
-   Documentation.
+.. include:: /includes/facts/fact-fcv-setting.rst
 
 Procedure
 ---------
 
 To upgrade the standalone deployment's MongoDB version from ``4.2.2-ent``
-to ``4.4.18-ent``, complete the steps in the following syntactic example.
-
-If you update ``spec.version`` to a later version without setting the
-:setting:`spec.featureCompatibilityVersion` to any value, the Feature
-Compatibility Version (FCV) upgrades to the **same version** that you specify
-in ``spec.version``. However, you can explicitly specify a previous
-version for the FCV. The following example illustrates this use case.
-It sets ``spec.version`` to ``4.4.18-ent`` and
-:setting:`spec.featureCompatibilityVersion` to ``4.2``.
+to ``4.4.18-ent``, complete the steps in the following example.
 
 .. include:: /includes/steps/upgrade-mdb.rst
