Skip to content

DOCS-2671 macro tutorial: deploy replica set with auth #1643

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions source/includes/steps-add-user-administrator-for-replica-set.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
stepnum: 1
source:
file: steps-change-user-privileges.yaml
ref: connect-with-appropriate-privileges
pre: |
Connect to the replica set :term:`primary` as a user with the
privileges required in the :ref:`add-user-admin-prereq` section.
---
stepnum: 2
source:
file: steps-change-user-privileges.yaml
ref: verify-privileges
---
title: Create the user administrator.
stepnum: 3
ref: create-user-admin
pre: |
Add the user and assign the :authrole:`userAdmin` role or
:authrole:`userAdminAnyDatabase` role, and only that role.
action:
pre: |
The following example creates the user ``recordsUserAdmin`` on the
``records`` database:
language: javascript
code: |
db.createUser(
{
user: "recordsUserAdmin",
pwd: "password",
roles:
[
{
role: "userAdmin",
db: "records"
}
]
}
)
...
63 changes: 63 additions & 0 deletions source/includes/steps-deploy-replica-set-with-auth.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
stepnum: 1
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure why we need to have this file, if the output appears to be mostly the same as the file it's drawing from.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't quite understand this question. Where's the duplication?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the source for every item in this file is "steps-deploy-replica-set.yaml", the order is the same, and we're not overriding anything.

is the only reason we have this file to avoid errors because of ref collisions? (this seems unideal, but its mostly my fault.)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is. My first draft didn't create the second file, but just reused the first, and I got all those ref collisions.

source:
file: steps-generate-key-file.yaml
ref: generate
---
title: Copy the key file to each member of the replica set.
stepnum: 2
ref: copy-key-file
---
title: Start each member of the replica set with the appropriate options.
stepnum: 3
ref: start-mongod
pre: |
For each member, start a :program:`mongod` and specify the key file and
the name of the replica set. Also specify other parameters as needed for
your deployment. For replication-specific parameters, see
:ref:`cli-mongod-replica-set` required by your deployment.
pre: |
.. include:: /includes/important-unique-replica-set-names.rst
action:
- pre: |
The following example specifies parameters through the :option:`--keyFile`
and :option:`--replSet` command-line options:
language: javascript
code: |
mongod --keyFile /mysecretdirectory/keyfile --replSet "rs0"
- pre: |
The following example specifies parameters through a configuration file:
language: javascript
code: |
mongod --config /etc/mongodb.conf
post: |
In production deployments, you can configure a :term:`control script` to
manage this process. Control scripts are beyond the scope of this document.
---
title: Connect to one of the replica set members.
stepnum: 4
port: |
Connect through the :ref:`localhost exception <localhost-exception>`.
source:
file: steps-deploy-replica-set.yaml
ref: open-shell
---
stepnum: 5
source:
file: steps-deploy-replica-set.yaml
ref: initiate-rs
---
stepnum: 6
source:
file: steps-deploy-replica-set.yaml
ref: display-rsconf
---
stepnum: 7
source:
file: steps-deploy-replica-set.yaml
ref: add-remaining-members
---
stepnum: 8
source:
file: steps-deploy-replica-set.yaml
ref: check-status
...
59 changes: 29 additions & 30 deletions source/includes/steps-deploy-replica-set.yaml
Original file line number Diff line number Diff line change
@@ -1,38 +1,36 @@
title: Start a :program:`mongod` on each system to be part of the replica set.
title: Start each member of the replica set with the appropriate options.
stepnum: 1
ref: start-mongod
pre: |
Specify the same replica set name on each instance.
For each member, start a :program:`mongod` and specify the replica set
name through the :setting:`replSet` option. Specify any other parameters
specific to your deployment. For replication-specific parameters, see
:ref:`cli-mongod-replica-set` required by your deployment.
pre: |
.. include:: /includes/important-unique-replica-set-names.rst
action:
- pre: |
.. include:: /includes/important-unique-replica-set-names.rst
- pre: |
To specify the replica set name from the command-line, start a
:program:`mongod` instance with the :option:`--replSet` option. For
additional replica-set options, see :ref:`cli-mongod-replica-set`.
The following example specifies a replica set named ``rs0``:
The following example specifies the replica set name through the
:option:`--replSet` command-line option:
language: javascript
code: |
mongod --dbpath /srv/mongodb/ --port 27017 --replSet "rs0"
mongod --replSet "rs0"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer to not allow the dbpath to be implicitly set (also people need to create the directory, which we've glossed over in this tutorial. We should probably add text to clarify this setting.

- pre: |
To instead use a configuration file, start each
:program:`mongod` instance with a command that resembles the
following. Change ``/etc/mongodb.conf`` to the location of your
configuration file:
The following example specifies the name through a configuration file:
language: javascript
code: |
mongod --config /etc/mongodb.conf
post: |
In production deployments, you can configure a :term:`control script` to
manage this process. Control scripts are beyond the scope of this document.
---
title: Open a :program:`mongo` shell and connect to one of the hosts.
title: Open a :program:`mongo` shell and connect to one of the replica set members.
stepnum: 2
ref: open-shell
action:
pre: |
For example, to connect to the :program:`mongod` running on the default
port ``27017`` on the localhost, simply issue:
For example, to connect to a :program:`mongod` running on localhost on
the default port of ``27017``, simply issue:
language: javascript
code: |
mongo
Expand All @@ -42,18 +40,21 @@ stepnum: 3
ref: initiate-rs
action:
pre: |
Use :method:`rs.initiate()` to initiate a replica set that consists of
the current member and that uses the default configuration:
Use :method:`rs.initiate()`:
language: javascript
code: |
rs.initiate()
post: |
MongoDB initiates a set that consists of the current member and that
uses the default replica set configuration.
---
title: Display the current replica set configuration.
title: Verify the initial replica set configuration.
stepnum: 4
ref: display-rsconf
ref: verify-rsconf
action:
- pre: |
To display the :doc:`replica configuration </reference/replica-configuration>`, issue:
Use :method:`rs.conf()` to display the :doc:`replica set configuration
object </reference/replica-configuration>`:
language: javascript
code: |
rs.conf()
Expand All @@ -71,22 +72,24 @@ action:
}
]
}
post: |

---
title: Add the remaining members to the replica set.
stepnum: 5
ref: add-remaining-members
pre: |
Add the remaining members with the :method:`rs.add()` method.
action:
pre: |
In the :program:`mongo` shell connected to the :term:`primary`, add
the remaining members with the :method:`rs.add()` method. The
commands should resemble the following:
The following example adds two members:
language: javascript
code: |
rs.add("mongodb1.example.net")
rs.add("mongodb2.example.net")
post: |
When complete, you should have a fully functional replica set.
The new replica set will elect a :term:`primary`.
When complete, you have a fully functional replica set. The new replica
set will elect a :term:`primary`.
---
title: Check the status of the replica set.
stepnum: 6
Expand All @@ -97,8 +100,4 @@ action:
language: javascript
code: |
rs.status()
post: |
For a detailed explanation of read and write semantics in MongoDB, refer
to :doc:`Replica Set Read and Write Semantics
</applications/replication>`.
...
13 changes: 8 additions & 5 deletions source/includes/steps-generate-key-file.yaml
Original file line number Diff line number Diff line change
@@ -1,19 +1,22 @@
title: Generate a key file to store authentication information.
title: Create a key file.
stepnum: 1
ref: generate
pre: |
Create the key file your deployment will use to authenticate
servers to each other.
action:
pre: |
Use the following ``openssl`` command at the system shell to generate
a key file with pseudo-random content:
For example, issue the ``openssl`` command to generate pseudo-random
content and save it as a new key file:
language: sh
code: |
openssl rand -base64 741
openssl rand -base64 741 > /mysecretdirectory/keyfile
---
title: Specify the key file when starting a MongoDB instance.
stepnum: 2
ref: specify
action:
pre: |
When starting your MongoDB instance, specify the key file using the
When starting a MongoDB instance, specify the key file through the
:setting:`keyFile` option.
...
4 changes: 4 additions & 0 deletions source/includes/toc-replica-set-deployment.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@ description: |
Configure a three-member replica set for either a
production system.
---
file: /tutorial/deploy-replica-set-with-auth
description: |
Configure a replica set that has authentication enabled.
---
file: /tutorial/deploy-replica-set-for-testing
description: |
Configure a three-member replica set for either a
Expand Down
2 changes: 2 additions & 0 deletions source/includes/toc-spec-replica-set-tutorials-landing.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ files:
level: 1
- file: /tutorial/deploy-replica-set
level: 2
- file: /tutorial/deploy-replica-set-with-auth
level: 2
- file: /tutorial/convert-standalone-to-replica-set
level: 2
- file: /tutorial/expand-replica-set
Expand Down
1 change: 1 addition & 0 deletions source/tutorial.txt
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ Replica Sets
~~~~~~~~~~~~

- :doc:`/tutorial/deploy-replica-set`
- :doc:`/tutorial/deploy-replica-set-with-auth`
- :doc:`/tutorial/convert-standalone-to-replica-set`
- :doc:`/tutorial/expand-replica-set`
- :doc:`/tutorial/remove-replica-set-member`
Expand Down
65 changes: 65 additions & 0 deletions source/tutorial/deploy-replica-set-with-auth.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
=================================================================
Deploy Replica Set and Configure Authentication and Authorization
=================================================================

.. default-domain:: mongodb

Overview
--------

When a :doc:`replica set </core/replication-introduction>` uses
:doc:`authentication </core/authentication>` and :doc:`authorization
</core/authorization>`, clients must provide credentials to access the
replica set's data. A client's privileges define the client's level of
access.

Replication keeps your data available in the event of a hardware or other
failure. Deploying a replica set involves setting up a :term:`primary`
MongoDB instance and two or more additional instances that replicate the
primary's data. All members in a replica set hold the same data.

Enabling authentication requires an authentication mechanism. This
tutorial uses a challenge-response mechanism, which uses a key file.

.. Authorization ...

.. When you complete the tutorial ...

Considerations
--------------

Authentication requires an authentication mechanism and in many cases a
:setting:`key file <keyFile>`.

Prerequisites
-------------

.. todo

Procedures
----------

Use following procedures in sequence.

Deploy the Replica Set and Enable Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This procedure deploys all members of the set, each with a copy of the
same key file.


.. include:: /includes/steps/deploy-replica-set-with-auth.rst

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

create and configure keyfile procedure should go here.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's step 1 in /includes/steps/enable-authentication-in-replica-set.rst,
as borrowed from /includes/steps/generate-key-file.rst.

This follows the approach used in /includes/steps/enable-authentication-in-sharded-cluster.rst.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A second, important thought. Now that we're sharing content (a very good thing), we should make it almost automatic to ourselves that we look at the published copy when review commenting. That would make each comment more efficient. For example, with the above comment on keyfile generation, the comment is clear but it's unclear if you mean it (i.e., if you know the whole story of the published page).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess I was sort of looking at the logical flow of the tutorial based on my understanding of the procedure and the headings. So in some ways the answer is "yep, its there." As I read these steps again, I think it might make sense to merge the "enable auth" procedure into the "deploy a replica set" procedure so that they don't have to reboot all of the nodes here.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which makes the case for one long procedure, or at least fewer procedure with a main long one (per your comment below). I'll draft that.

Create a User Administrator
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Running with authentication requires that a user administrator exists who
can create any type of user with any level of access required by your
deployment.

.. include:: /includes/steps/add-user-administrator-for-replica-set.rst

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we want to have a bunch of step 1 through 4 (on average) tutorials here, or a 10 step procedure that covers everything? Or at least have some of the later procedures start at 5 (that might not work given the current implementation, but we could make it work.)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good questions. We should discuss.

Create Additional Users
~~~~~~~~~~~~~~~~~~~~~~~

To add a user to a database, see :doc:`/tutorial/add-user-to-database`.