-
Notifications
You must be signed in to change notification settings - Fork 1.7k
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
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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" | ||
} | ||
] | ||
} | ||
) | ||
... |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,63 @@ | ||
stepnum: 1 | ||
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 | ||
... |
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" | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
|
@@ -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() | ||
|
@@ -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 | ||
|
@@ -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>`. | ||
... |
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. | ||
... |
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 | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. create and configure keyfile procedure should go here. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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, This follows the approach used in /includes/steps/enable-authentication-in-sharded-cluster.rst. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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). There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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.) There was a problem hiding this comment. Choose a reason for hiding this commentThe 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`. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.)
There was a problem hiding this comment.
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.