DOCSP-966: 3.6 downgrade

Author: kay-kim

source/includes/3.6-downgrade-fcv.rst

@@ -0,0 +1,11 @@
+Downgrade the ``featureCompatibilityVersion`` to ``"3.4"``.
+
+.. code-block:: javascript
+
+   db.adminCommand({setFeatureCompatibilityVersion: "3.4"})
+
+This command must perform writes to an internal system collection.
+If for any reason the command does not complete successfully, you
+can safely retry the command on the |target| as the operation is
+idempotent.
+

source/includes/3.6-downgrade-path.rst

@@ -1 +1 @@
-Once upgraded to |newversion|, you can only |downgrade| to .
+Once upgraded to |newversion|, we recommend |downgrading| to the latest patch release of 3.4

source/includes/list-table-featureCompatibilityVersion-defaults.rst

@@ -2,13 +2,21 @@
    :header-rows: 1
    :widths: 30 70
 
-   * - 3.6 Deployments
+   * - Deployments
      - ``featureCompatibilityVersion``
 
-   * - For new deployments
+   * - For new 3.6 deployments
      - ``"3.6"``
 
    * - For deployments :ref:`upgraded from 3.4 <3.6-upgrade>`
 
      - ``"3.4"`` until you :dbcommand:`setFeatureCompatibilityVersion`
        to ``"3.6"``.
+
+   * - For new 3.4 deployments
+     - ``"3.4"``
+
+   * - For deployments :ref:`upgraded from 3.2 <3.4-upgrade>`
+   
+     - ``"3.2"`` until you :dbcommand:`setFeatureCompatibilityVersion`
+       to ``"3.4"``.

source/includes/steps-3.6-downgrade-mongod.yaml

@@ -0,0 +1,19 @@
+title: "Download the latest |oldversion| binaries."
+level: 4
+ref: 3.6-downgrade-binaries-mongod
+content: |
+  
+  Using either a package manager or a manual download, get the latest
+  release in the |oldversion| series. If using a package manager, add a new
+  repository for the |oldversion| binaries, then perform the actual downgrade
+  process.
+
+  .. include:: /includes/3.6-downgrade-path.rst
+---
+title: "Restart with the latest |oldversion| ``mongod`` instance."
+level: 4
+ref: 3.6-downgrade-restart-instance
+content: |
+  Shut down your :program:`mongod` instance. Replace the existing
+  binary with the downloaded :program:`mongod` binary and restart.
+...

source/includes/steps-3.6-downgrade-replica-set.yaml

@@ -0,0 +1,52 @@
+title: "Download the latest |oldversion| binaries."
+level: 4
+ref: 3.6-downgrade-binaries-rs
+content: |
+  Using either a package manager or a manual download, get the latest
+  release in the |oldversion| series. If using a package manager, add a new
+  repository for the |oldversion| binaries, then perform the actual downgrade
+  process.
+
+  .. include:: /includes/3.6-downgrade-path.rst
+---
+title: "Downgrade secondary members of the replica set."
+level: 4
+ref: downgrade-secondaries
+content: |
+
+  Downgrade each :term:`secondary` member of the replica set, one at a
+  time:
+
+  a. Shut down the :program:`mongod`. See :ref:`terminate-mongod-processes` for instructions on safely terminating :program:`mongod` processes.
+
+  #. Replace the |newversion| binary with the |oldversion| binary and restart.
+
+  #. Wait for the member to recover to ``SECONDARY`` state
+     before downgrading the next secondary. To check the member's state,
+     use the :method:`rs.status()` method in the :program:`mongo` shell.
+
+---
+title: Step down the primary.
+level: 4
+ref: step-down-primary
+pre: |
+  Use :method:`rs.stepDown()` in the :program:`mongo` shell to
+  step down the :term:`primary` and force the normal :ref:`failover
+  <replica-set-failover>` procedure.
+action:
+  language: javascript
+  code:
+    rs.stepDown()
+post: |
+  :method:`rs.stepDown()` expedites the failover procedure and is
+  preferable to shutting down the primary directly.
+---
+title: "Replace and restart former primary ``mongod``."
+level: 4
+ref: downgrade-primary
+content: |
+  When :method:`rs.status()` shows that the primary has stepped down
+  and another member has assumed ``PRIMARY`` state, shut down the
+  previous primary and replace the :program:`mongod` binary with
+  the |oldversion| binary and start the new instance.
+...

source/includes/steps-3.6-downgrade-sharded-cluster.yaml

@@ -0,0 +1,209 @@
+title: "Download the latest |oldversion| binaries."
+level: 4
+ref: 3.6-downgrade-binaries-sharded-cluster
+content: |
+  Using either a package manager or a manual download, get the latest
+  release in the |oldversion| series. If using a package manager, add a new
+  repository for the |oldversion| binaries, then perform the actual downgrade
+  process.
+
+  .. include:: /includes/3.6-downgrade-path.rst
+---
+title: Disable the Balancer.
+level: 4
+ref: disable-balancer
+content: |
+  Turn off the balancer as described in
+  :ref:`sharding-balancing-disable-temporarily`.
+---
+title: "Downgrade the ``mongos`` instances."
+level: 4
+ref: downgrade-mongos
+content: |
+   Downgrade the binaries and restart.
+---
+title: Downgrade each shard, one at a time.
+level: 4
+ref: 3.6-downgrade-shard
+content: |
+
+   Downgrade the shards one at a time. If the shards are replica sets, for each shard:
+
+   1. Downgrade the :ref:`secondary <replica-set-secondary-members>`
+      members of the replica set one at a time:
+
+      a. Shut down the :program:`mongod` instance and replace the |newversion|
+         binary with the |oldversion| binary.
+
+      #. Start the |oldversion| binary with the ``--shardsvr`` and
+         ``--port`` command line options. Include any other
+         configuration as appropriate for your deployment, e.g.
+         ``--bind_ip``.
+ 
+         .. code-block:: sh
+
+            mongod --shardsvr --port <port> --dbpath <path> --bind_ip localhost,<ip address>
+
+         Or if using a :doc:`configuration file
+         </reference/configuration-options>`, update the file to
+         include :setting:`sharding.clusterRole: shardsvr
+         <sharding.clusterRole>`, :setting:`net.port`, and any other
+         configuration as appropriate for your deployment, e.g.
+         :setting:`net.bindIp`, and start:
+
+         .. code-block:: yaml
+
+            sharding:
+               clusterRole: shardsvr
+            net:
+               port: <port>
+               bindIp: localhost,<ip address>
+            storage:
+               dbpath: <path>
+
+
+      #. Wait for the member to recover to ``SECONDARY`` state before
+         downgrading the next secondary member. To check the member's
+         state, you can issue :method:`rs.status()` in the
+         :program:`mongo` shell.
+
+         Repeat for each secondary member.
+
+   #. Step down the replica set primary.
+
+      Connect a :program:`mongo` shell to the primary and use
+      :method:`rs.stepDown()` to step down the primary and force an
+      election of a new primary:
+
+      .. code-block:: javascript
+
+         rs.stepDown()
+
+   #. When :method:`rs.status()`
+      shows that the primary has stepped down and another member
+      has assumed ``PRIMARY`` state, downgrade the stepped-down primary: 
+
+      1. Shut down the stepped-down primary and replace the
+         :program:`mongod` binary with the |oldversion| binary.
+
+      #. Start the |oldversion| binary with the ``--shardsvr`` and
+         ``--port`` command line options. Include any other
+         configuration as appropriate for your deployment, e.g.
+         ``--bind_ip``.
+ 
+         .. code-block:: sh
+
+            mongod --shardsvr --port <port> --dbpath <path>  --bind_ip localhost,<ip address>
+
+         Or if using a :doc:`configuration file
+         </reference/configuration-options>`, update the file to
+         include :setting:`sharding.clusterRole: shardsvr
+         <sharding.clusterRole>`, :setting:`net.port`, and any other
+         configuration as appropriate for your deployment, e.g.
+         :setting:`net.bindIp`, and start the |oldversion| binary:
+
+         .. code-block:: yaml
+
+            sharding:
+               clusterRole: shardsvr
+            net:
+               port: <port>
+               bindIp: localhost,<ip address>
+            storage:
+               dbpath: <path>
+---
+title: "Downgrade the config servers."
+level: 4
+ref: 3.6-downgrade-config-servers
+content: |-
+   If the config servers are replica sets:
+      
+   1. Downgrade the :ref:`secondary <replica-set-secondary-members>`
+      members of the replica set one at a time:
+
+      a. Shut down the secondary :program:`mongod` instance and replace
+         the |newversion| binary with the |oldversion| binary.
+
+      #. Start the |oldversion| binary with both the ``--configsvr`` and
+         ``--port`` options. Include any other
+         configuration as appropriate for your deployment, e.g.
+         ``--bind_ip``.
+
+         .. code-block:: sh
+
+            mongod --configsvr --port <port> --dbpath <path>  --bind_ip localhost,<ip address>
+
+         If using a :doc:`configuration file
+         </reference/configuration-options>`, update the file to
+         specify :setting:`sharding.clusterRole: configsvr
+         <sharding.clusterRole>`, :setting:`net.port`, and any other
+         configuration as appropriate for your deployment, e.g.
+         :setting:`net.bindIp`, and start the |oldversion| binary:
+
+         .. code-block:: yaml
+
+            sharding:
+               clusterRole: configsvr
+            net:
+               port: <port>
+               bindIp: localhost,<ip address>
+            storage:
+               dbpath: <path>
+
+         Include any other configuration as appropriate for your deployment.
+
+      #. Wait for the member to recover to ``SECONDARY`` state before
+         downgrading the next secondary member. To check the member's state,
+         issue :method:`rs.status()` in the :program:`mongo` shell.
+
+         Repeat for each secondary member.
+
+   #. Step down the replica set primary.
+
+      a. Connect a :program:`mongo` shell to the primary and use
+         :method:`rs.stepDown()` to step down the primary and force an
+         election of a new primary:
+
+         .. code-block:: javascript
+
+            rs.stepDown()
+
+      #. When :method:`rs.status()` shows that the primary has stepped
+         down and another member has assumed ``PRIMARY`` state, shut down
+         the stepped-down primary and replace the :program:`mongod` binary
+         with the |oldversion| binary.
+
+      #. Start the |oldversion| binary with both the ``--configsvr`` and
+         ``--port`` options. Include any other
+         configuration as appropriate for your deployment, e.g.
+         ``--bind_ip``.
+
+         .. code-block:: sh
+
+            mongod --configsvr --port <port> --dbpath <path> --bind_ip localhost,<ip address>
+
+         If using a :doc:`configuration file
+         </reference/configuration-options>`, update the file to
+         specify :setting:`sharding.clusterRole: configsvr
+         <sharding.clusterRole>`, :setting:`net.port`, and any other
+         configuration as appropriate for your deployment, e.g.
+         :setting:`net.bindIp`, and start the |oldversion| binary:
+
+         .. code-block:: yaml
+
+            sharding:
+               clusterRole: configsvr
+            net:
+               port: <port>
+               bindIp: localhost,<ip address>
+            storage:
+               dbpath: <path>
+
+---
+title: "Re-enable the balancer."
+level: 4
+ref: reenable-balancer
+content: |
+  Once the downgrade of sharded cluster components is
+  complete, :ref:`re-enable the balancer <sharding-balancing-enable>`.
+...