DOCS-8616: no-downtime security sharded cluster

source/core/security-internal-authentication.txt

@@ -95,6 +95,7 @@ see :doc:`/tutorial/upgrade-keyfile-to-x509`.
       /tutorial/enforce-keyfile-access-control-in-existing-replica-set-without-downtime
       /tutorial/deploy-replica-set-with-keyfile-access-control
       /tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster
-      /tutorial/deploy-sharded-cluster-with-keyfile-access-control
+      /tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime
+      /tutorial/deploy-sharded-cluster-with-keyfile-access-control      
       /tutorial/configure-x509-member-authentication
       /tutorial/upgrade-keyfile-to-x509

source/includes/extracts-keyfile-info.yaml

@@ -1,9 +1,12 @@
 ref: _keyfile-intro
 content: |
 
-   The contents of the :ref:`keyfile <internal-auth-keyfile>` serves as
-   the shared password for the members of the {{deployment}}. The
-   content of the keyfile must be the same for all members of the
+   With :ref:`keyfile <internal-auth-keyfile>` authentication, the
+   {{components}} in the {{deployment}} use the contents of the keyfile as the
+   shared password for authenticating other members in the deployment. Only
+   {{components}} with the correct keyfile can join the {{deployment}}.
+
+   The content of the keyfile must be the same for all members of the
    {{deployment}}.
 
    You can generate a keyfile using any method you choose. The contents
@@ -24,22 +27,30 @@ source:
    ref: _keyfile-intro
 replacement:
    deployment: replica set
+   components: :program:`mongod` instances
 ---
 ref: keyfile-intro-sharded-cluster
 source:
    file: extracts-keyfile-info.yaml
    ref: _keyfile-intro
 replacement:
    deployment: sharded cluster
+   components: :program:`mongod` or :program:`mongos` instances
 ---
 ref: _keyfile-distribution
 content: |
-   Copy the keyfile to each server hosting the {{deployment}} members. Use a
-   consistent location for each server.
+
+   Copy the keyfile to each server hosting the {{deployment}} members. For
+   simplicity in configuration and maintenance, save the keyfile to a
+   consistent location for each server, such as the file path specified in
+   the {{programs}} :setting:`storage.dbPath` setting.
 
    .. important::
-      Do not use shared network locations or storage mediums such as USB
-      drives for storing the keyfile.
+
+      If the {{programs}} cannot access the keyfile, they cannot communicate
+      with the {{deployment}}. Avoid storing the keyfile on storage mediums
+      that can be easily disconnected from the hardware hosting the
+      {{programs}}, such as a USB drive or a network attached storage device.
 
    Ensure that the user running the {{programs}} can access the keyfile.
 ---

source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-config.yaml

@@ -0,0 +1,31 @@
+stepnum: 1
+level: 4
+title: "Remove ``transitionToAuth`` from the ``mongod`` configuration file."
+ref: modify-config-files
+pre: |
+
+  Remove the :setting:`security.transitionToAuth` key and its value from the
+  configuration file created during this tutorial.
+
+  .. code-block:: yaml
+
+     security:
+        keyFile: <path-to-keyfile>
+---
+stepnum: 2
+level: 4
+ref: restart-mongod
+title: "Restart the ``mongod`` with the updated configuration file."
+source:
+  file: steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml
+  ref: restart-mongod
+post: |
+
+  At the end of this section the config server replica set should be up and
+  running, fully enforcing authentication.
+
+  Users and client applications *must* specify authentiation credentials when
+  connecting to the config server replica set.
+replacement:
+  status: "updated"
+...

source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-mongos.yaml

@@ -0,0 +1,53 @@
+stepnum: 1
+level: 4
+title: "Remove ``transitionToAuth`` from the ``mongos`` configuration file"
+ref: modify-config-files
+pre: |
+
+  Remove the :setting:`security.transitionToAuth` key and its value from the
+  configuration file created during this tutorial.
+
+  .. code-block:: yaml
+
+     security:
+        keyFile: <path-to-keyfile>
+
+---
+stepnum: 2
+level: 4
+ref: restart-mongos
+title: "Restart the ``mongos`` with the updated configuration file."
+pre: |
+
+  Connect to the :program:`mongos` and use the :method:`db.shutdownServer()`
+  method against the ``admin`` database to safely shut down the
+  :program:`mongos`.
+
+  Restart one :program:`mongos` at a time to ensure that clients
+  can connect to the sharded cluster. If your cluster has only one
+  :program:`mongos`, this step results in downtime while the :program:`mongos`
+  is offline.
+
+  .. code-block:: javascript
+
+     db.getSiblingDB("admin").shutdownServer()
+
+  You can then restart the :program:`mongos` specifying the path to the updated
+  config file using :option:`--config`.
+
+  .. example::
+
+     The following operation restarts the :program:`mongos` specifying
+     the updated configuration file, here named ``mongos-secure.conf``.
+     The ``<path>`` represents the system path to the folder containing
+     the configuration file.
+
+     .. code-block:: shell
+
+        mongos --config <path>/mongos-secure.conf
+
+  .. note::
+
+     MongoDB deployments running on :abbr:`Windows (Microsoft Windows)` use
+     the ``.cfg`` file extension instead of ``.conf``, and
+     :program:`mongos.exe` instead of :program:`mongos`.

source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-shard.yaml

@@ -0,0 +1,24 @@
+stepnum: 1
+level: 4
+title: "Remove ``transitionToAuth`` from the ``mongod`` configuration file"
+ref: modify-configuration
+source:
+  file: steps-enable-authentication-in-shardcluster-nodowntime-auth-config.yaml
+  ref: modify-config-files
+---
+stepnum: 2
+level: 4
+title: "Restart the ``mongod`` with the new configuration file."
+ref: restart-mongod
+source:
+  file: steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml
+  ref: restart-mongod
+post: |
+
+  At the end of this section, the shard replica set should be up and
+  running fully enforcing authentication.
+
+  Users and client applications *must* specify authentiation credentials when
+  connecting to the shard replica set.
+replacement:
+  status: "updated"

source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml

@@ -0,0 +1,95 @@
+stepnum: 1
+level: 4
+title: "Add ``transitionToAuth: true`` to the ``mongod`` configuration file."
+ref: modify-config-files
+pre: |
+
+  Copy the existing {{program}} configuration file, giving it a distinct
+  name such as ``<filename>-secure``.
+
+  You will use this new configuration file to transition the {{program}} to
+  enforce authentication in the sharded cluster. Retain the original
+  configuration file for backup purposes.
+
+  Add the following settings to the new configuration file.
+
+  .. list-table::
+     :header-rows: 1
+     :widths: 30 70
+
+     * - Setting
+       - Value
+
+     * - :setting:`security.transitionToAuth`
+       - ``true``
+
+     * - :setting:`security.keyFile`
+       - Path to the keyfile.
+
+         If using a different internal authentication mechanism, specify
+         settings appropriate for the mechanism.
+
+  The new configuration file should contain all of the configuration settings
+  previously used by the {{program}}, as well as the new security
+  settings.
+
+  .. code-block:: yaml
+
+     security:
+        transitionToAuth: true
+        keyFile: <path-to-keyfile>
+replacement:
+  program: :program:`mongod`
+---
+stepnum: 2
+level: 4
+ref: restart-mongod
+title: "Restart the ``mongod`` with the new configuration file."
+pre: |
+
+  If upgrading the a :term:`secondary`, connect to the :program:`mongod` and
+  use the :method:`db.shutdownServer()` method against the ``admin`` database
+  to safely shut down the :program:`mongod`.
+
+  .. code-block:: javascript
+
+     db.getSiblingDB("admin").shutdownServer()
+
+  If upgrading the :term:`primary`, connect to the :program:`mongod` and use
+  the :method:`rs.stepDown()` method against the ``admin`` database to step
+  down the primary and trigger an election. You can use the
+  :method:`rs.status()` method to ensure the replica set elected a new primary.
+
+  Once you step down the primary, shut it down using the
+  :method:`db.shutdownServer()` method against the ``admin`` database.
+
+  .. code-block:: javascript
+
+     db.getSiblingDB("admin").rs.stepDown()
+     db.getSiblingDB("admin").shutdownServer()
+
+  Restart the :program:`mongod` with the {{status}} configuration
+  file, specifying the path to the config file using :option:`--config`.
+
+  .. example::
+
+     The following operation starts the replica set member specifying
+     the {{status}} configuration file, here named ``mongod-secure.conf``.
+     The ``<path>`` represents the system path to the folder containing
+     the configuration file.
+
+     .. code-block:: shell
+
+        mongod --config <path>/mongod-secure.conf
+
+  .. note::
+
+     MongoDB deployments running on :abbr:`Windows (Microsoft Windows)` use
+     the ``.cfg`` file extension instead of ``.conf``.
+replacement:
+  status: "new"
+post: |
+
+  Include additional settings as appropriate to your deployment. Refer to
+  the :ref:`configuration-options` documentation for a complete list of
+  configuration file options.

source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-mongos.yaml

@@ -0,0 +1,79 @@
+stepnum: 1
+level: 4
+title: "Add ``transitionToAuth: true`` to the ``mongos`` configuration file"
+ref: modify-config-files
+pre: |
+
+  Copy the existing {{program}} configuration file, giving it a distinct
+  name such as ``<filename>-secure``.
+
+  You will use this new configuration file to transition the {{program}} to
+  enforce authentication in the sharded cluster. Retain the original
+  configuration file for backup purposes.
+
+  Add the following settings to the new configuration file.
+
+  .. list-table::
+     :header-rows: 1
+     :widths: 30 70
+
+     * - Setting
+       - Value
+
+     * - :setting:`security.transitionToAuth`
+       - ``true``
+
+     * - :setting:`security.keyFile`
+       - Path to the keyfile.
+
+         If using a different internal authentication mechanism, specify
+         settings appropriate for the mechanism.
+
+  The new configuration file should contain all of the configuration settings
+  previously used by the {{program}}, as well as the new security
+  settings.
+
+  .. code-block:: yaml
+
+     security:
+        transitionToAuth: true
+        keyFile: <path-to-keyfile>
+replacement:
+  program: :program:`mongos`
+---
+stepnum: 2
+level: 4
+ref: restart-mongos
+title: "Restart the ``mongos`` with the new configuration file."
+pre: |
+
+  Restart one :program:`mongos` at a time to ensure that clients can connect
+  to the sharded cluster. If your cluster has only one :program:`mongos`, this
+  step results in downtime while the :program:`mongos` is offline.
+
+  Connect to the :program:`mongos` and use the :method:`db.shutdownServer()`
+  method against the ``admin`` database to safely shut down the
+  :program:`mongos`.
+
+  .. code-block:: javascript
+
+     db.getSiblingDB("admin").shutdownServer()
+
+  Restart :program:`mongos` with the new configuration file, specifying the
+  path to the config file using :option:`--config`.
+
+  .. example::
+
+     The following operation starts the :program:`mongos` specifying
+     the updated configuration file, here named ``mongos-secure.conf``.
+     The ``<path>`` represents the system path to the folder containing
+     the configuration file.
+
+     .. code-block:: shell
+
+        mongos --config <path>/mongos-secure.conf
+
+  .. note::
+
+     MongoDB deployments running on :abbr:`Windows (Microsoft Windows)` use
+     the ``.cfg`` file extension instead of ``.conf``.

source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-shards.yaml

@@ -0,0 +1,18 @@
+stepnum: 1
+level: 4
+title: "Add ``transitionToAuth: true`` to the ``mongod`` configuration file."
+ref: modify-configuration
+source:
+  file: steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml
+  ref: modify-config-files
+---
+stepnum: 2
+level: 4
+title: "Restart the ``mongod`` with the new configuration file."
+ref: restart-mongod
+source:
+  file: steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml
+  ref: restart-mongod
+replacement:
+  status: "new"
+...