DOCS-8616: no-downtime security sharded cluster #2834

ravindk89 · 2017-02-03T21:09:19Z

Staged: https://docs-mongodbcom-staging.corp.mongodb.com/rkumar/DOCS-8616/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.html

This change is

kay-kim · 2017-02-03T21:15:12Z

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

+post: |
+
+  At the end of this section, the config server replica set should be up and
+  running fully enforcing authentication.


Not sure how to parse this. Is this:

.. should be up and running, fully enforcing authentication (which describes a state)

or -

running fully enforcing authentication (where authentication is the direct object of running).

The former, I think. Done.

kay-kim · 2017-02-03T21:16:12Z

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

+
+     db.getSiblingDB("admin").shutdownServer()
+
+  You can then start the :program:`mongos` specifying the updated


sentence seems to have gotten garbled.

kay-kim · 2017-02-03T21:20:08Z

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

+  configuration file, specifying the path to the config file using
+  :option:`--config`.. This configuration file no longer contains the
+  :setting:`security.transitionToAuth` setting, but retains the
+  :setting:`security.keyFile` setting.


This sentence strikes me as odd since in step one, you made me remove it. and then in step two, you mention the state of the file.

I wasn't sure if users might get confused as to the state of the file. I've no problem removing it, and addressing if users do get confused.

kay-kim · 2017-02-03T21:20:39Z

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

+  .. note::
+
+     MongoDB deployments running on :abbr:`Windows (Microsoft Windows)` use
+     the ``.cfg`` file extension instead of ``.conf``.


If we're going all Windows, why not also state that mongos is mongos.exe

kay-kim · 2017-02-03T21:26:23Z

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

+pre: |
+
+  Copy the existing {{program}} configuration file and name the copy to
+  distinguish it, for example, by adding ``-secure`` to the filename. You will


This sentence could be tightened.

kay-kim · 2017-02-03T21:31:23Z

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

+       - Path to the keyfile.
+
+         If using a different internal authentication mechanism, specify that
+         mechanism instead of :setting:`security.keyFile`.


Should it be specify the settings appropriate for the mechanism ?

That does sound better. Done.

kay-kim · 2017-02-03T21:44:12Z

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

+
+  .. example::
+
+     The following operation creates the user ``joe`` on the ``analytics``


This operation doesn't do that at all.

Ah, yes I modified the example but missed the description. Thanks

kay-kim · 2017-02-03T21:45:56Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

@@ -0,0 +1,297 @@
+==========================================================================
+Enable mandatory user authentication in a sharded cluster without downtime
+==========================================================================


We tend to use title capitalization for pages.

Also, How is mandatory user authentication different from just user authentication

This was a suggestion from Andy - I'm guessing that 'mandatory' is a stronger implication. I don't object in removing it, but I don't think it takes away from anything either.

kay-kim · 2017-02-03T21:47:21Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

+authentication <inter-process-auth>` among the sharded cluster
+:program:`mongod` and :program:`mongos` components.
+
+This tutorial describes a correct procedure for using


rm "correct"

kay-kim · 2017-02-03T21:50:50Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

+
+Perform these steps for each :program:`mongod` in the config server replica
+set, one member at a time. Work on the :term:`secondary` or
+:term:`arbiter` members *first*, and the :term:`primary` *last*.


config server rs cannot have arbiters.

kay-kim · 2017-02-03T21:51:56Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

+
+Perform these steps on one shard replica set at a time, and one member in the
+shard replica set at a time. Work on the :term:`secondary` or :term:`arbiter`
+members *first*, and the :term:`primary` *last*.


Unless explicitly requested to mention the arbiters, I might remove the arbiter members.
It sounds like you can have multiple arbiters.

ravindk89 · 2017-02-10T19:52:24Z

@kay-kim back to you!

kay-kim · 2017-02-14T23:51:24Z

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

-  :option:`--config`.. This configuration file no longer contains the
-  :setting:`security.transitionToAuth` setting, but retains the
-  :setting:`security.keyFile` setting.
+  You can then restart the :program:`mongos specifying the path to the updated


missing a backtick after the mongos

kay-kim · 2017-02-15T00:00:42Z

source/includes/extracts-keyfile-info.yaml

+   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.


Double checking that this recommendation of storage.dbPath has been vetted by someone.

Ah, I can't say that for certain.

I'll check with spencer

@spencerjackson Can you chime in?

remove ", such as the file path ... "

kay-kim · 2017-02-15T00:03:52Z

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

+  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()`


lines 58-60 repeat lines 50-52

kay-kim · 2017-02-15T00:05:10Z

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

-  You can then start the :program:`mongos` with the new configuration
-  file, specifying the path to the config file using :option:`--config`.
+  Restart :program:`mongos` with the new configuration file, specifying the
+  path to the config file using :option:`--config`.


Why is the following code block in an example block whereas the shutdown isn't?

My logic was to use example blocks for when I want to set up a scenario or context for a code example, as opposed to the code block here which needs no context (IMHO).

I agree that's a nice distinction, but unfortunately, I don't think we're doing that consistently. Take a look at https://docs-mongodbcom-staging.corp.mongodb.com/rkumar/DOCS-8616/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.html#create-the-adminstrator-user vs https://docs-mongodbcom-staging.corp.mongodb.com/rkumar/DOCS-8616/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.html#optional-create-users-for-client-applications-to-authenticate-with

Other than naming the user in the example sentences, how is the user "admin" that much different than user "joe"?

Even in here, how is it in context if we're specifying the conf file name but not the path? It's a bit general and specific all jumbled up.

kay-kim · 2017-02-15T00:10:47Z

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

@@ -59,15 +60,15 @@ pre: |
  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, you can then shut it down using the
+  Once you step down the primary, you shut it down using the


Because of the way they're organized, lines 58 - 61 seems to go with the code-block at line 54 while this paragraph would be post stepDown.
Instead, you might want to forestall someone accidentally shutting down the primary at lines 58-61 by prefacing with something like:

If upgrading the secondary, ...

If upgrading the primary,

kay-kim · 2017-02-15T00:16:04Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

@@ -269,7 +269,7 @@ sharded cluster without the :setting:`security.transitionToAuth` setting.
 Repeat these steps for each shard replica set in the sharded cluster.

 Perform these steps on one shard replica set at a time, and one member in the
-shard replica set at a time. Work on the :term:`secondary` or :term:`arbiter`
+shard replica set at a time. Work on the :term:`secondary`


Work on -> Start with

kay-kim · 2017-02-15T00:16:37Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

@@ -244,8 +244,8 @@ sharded cluster, you must restart each :program:`mongod` instance without
 the :setting:`security.transitionToAuth` setting.

 Perform these steps for each :program:`mongod` in the config server replica
-set, one member at a time. Work on the :term:`secondary` or
-:term:`arbiter` members *first*, and the :term:`primary` *last*.
+set, one member at a time. Work on the :term:`secondary` or members *first*,


Work on -> Start with

remove 'or members' to I think just the 'members'.

ravindk89 · 2017-02-16T20:57:36Z

@kay-kim back to you!

kay-kim

I kind of ran out of steam/time at the end. But let's see what you can do for the last sections that I didn't review.

kay-kim · 2017-03-08T04:07:09Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

+
+.. important::
+
+   MongoDB 3.2 and earlier do not support a no-downtime upgrade to enforce


Can we tighten this important note and start with a positive? Something like (spitballing -- you can polish)

The following procedure applies to sharded clusters using MongoDB 3.4 or later.

Earlier versions of MongoDB do not support no-downtime upgrade. For sharded clusters using earlier versions of MongoDB, see :doc:/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster.

kay-kim · 2017-03-08T04:12:49Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

+   tutorial for a procedure for enforcing access control in a sharded cluster
+   running MongoDB 3.2 or prior.
+
+To secure against unauthorized access, enforce :ref:`authentication


Since this tutorial is already 20 pages long, let's be economical with some of these. Something like (feel free to play with)

To secure against unauthorized access, enforce authentication. A sharded cluster can enforce user authentication as well as internal authentication of its components. The following tutorial describes a procedure to transition an existing sharded cluster to enforce authentication.

kay-kim · 2017-03-08T04:13:38Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

+contents of this document.
+
+Considerations
+~~~~~~~~~~~~~~


This should use the ______ underscore instead of ~~~~~

kay-kim · 2017-03-08T04:17:39Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

+Minimum number of ``mongos`` instances
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This tutorial requires restarting each :program:`mongos` in the cluster. If


Not sure, and feel free to ignore, but I wonder if we should start with the thing we want people to pay attention to:

Ensure your sharded cluster has at least two mongos instances available. This tutorial requires restarting each mongos in the cluster. If your cluster has only one mongos instance, this results in downtime ....

kay-kim · 2017-03-08T04:19:53Z

source/includes/extracts-keyfile-info.yaml

-   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


With keyfile internal authentication, each ...

(only because people might not be familiar with keyfile authentication. each because your {{components}} is mongod or mongos.

kay-kim · 2017-03-08T05:25:03Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

+
+.. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-uac.rst
+
+Restart Each ``mongos`` Instance with ``transitionToAuth`` set to ``true``


Transition mongos to use auth (clearly not those words) but something like it.

kay-kim · 2017-03-08T05:25:24Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

+cluster are running with :setting:`security.transitionToAuth` and
+:setting:`security.keyFile` internal authentication.
+
+Restart Each Config Server Replica Set Member with ``transitionToAuth`` set to ``true``


Transition the config server replica set to auth (just with better words)

kay-kim · 2017-03-08T05:25:46Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

+server replica set is running with :setting:`security.transitionToAuth` and
+:setting:`security.keyFile` internal authentication.
+
+Restart Each Member of Each Shard Replica Set with ``transitionToAuth`` set to ``true``


Trnasition Each shard replica set to auth (reword)

kay-kim · 2017-03-08T05:26:51Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

+  performing queries or cluster-level maintenance operations.
+
+Procedure
+++++++++


If I see Procedure, I could skip over all the words above to just get to the procedure that has steps.
If we change this section title, then this subheading could be the
Restart shards with auth (or whatever)

kay-kim · 2017-03-08T05:27:39Z

source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt

+.. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-transition-shards.rst
+
+At this point in the tutorial, every component of the sharded cluster is
+running with :option:`--transitionToAuth` and :setting:`security.keyFile`


well, they're all running with :setting:security.transitionToAuth since in all our steps we updated the config file.

…2834) * DOCS-15890 Add Log Redaction to Log Messages + Security Page * DC feedback

ravindk89 added the RFM label Feb 3, 2017

ravindk89 requested a review from kay-kim February 3, 2017 21:09

kay-kim reviewed Feb 3, 2017

View reviewed changes

kay-kim suggested changes Feb 3, 2017

View reviewed changes

ravindk89 force-pushed the DOCS-8616 branch from 75f1665 to 888b093 Compare February 10, 2017 19:52

kay-kim suggested changes Feb 15, 2017

View reviewed changes

ravindk89 added 3 commits February 16, 2017 15:47

DOCS-8616: no-downtime security sharded cluster

ac1e8fd

DOCS-8616: Kay CR

b9bfc45

DOCS-8616: More CR Changes

e8f16ff

ravindk89 force-pushed the DOCS-8616 branch from 888b093 to e8f16ff Compare February 16, 2017 20:56

kay-kim suggested changes Mar 8, 2017

View reviewed changes

ravindk89 closed this Jun 23, 2017

ravindk89 deleted the DOCS-8616 branch June 23, 2017 18:00

mongo-cr-bot pushed a commit that referenced this pull request Mar 29, 2023

DOCS-15890 Add Log Redaction to Log Messages + Security Page (#2737) (#…

aa7a1a6

…2834) * DOCS-15890 Add Log Redaction to Log Messages + Security Page * DC feedback


		db.getSiblingDB("admin").shutdownServer()

		You can then start the :program:`mongos` specifying the updated


		.. example::

		The following operation creates the user ``joe`` on the ``analytics``


		.. important::

		MongoDB 3.2 and earlier do not support a no-downtime upgrade to enforce


		.. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-uac.rst

		Restart Each ``mongos`` Instance with ``transitionToAuth`` set to ``true``

DOCS-8616: no-downtime security sharded cluster #2834

DOCS-8616: no-downtime security sharded cluster #2834

Uh oh!

Conversation

ravindk89 commented Feb 3, 2017 • edited by atsansone Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ravindk89 commented Feb 10, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

ravindk89 commented Feb 3, 2017 •

edited by atsansone

Loading