(DOCSP-11424): Document SCRAM Auth #196

melissamahoney-mongodb · 2020-09-14T20:37:20Z

This PR:

Breaks the sections that were in the README into separate docs .md files
Rearranges those docs .md files under one /docs directory
Updates the README to point to the /docs directory
Creates a /docs/README to act as a TOC
Creates a new page for Creating Database Users

Staging:

jwilliams-mongo · 2020-09-14T20:42:55Z

README.md

+## Documentation

-### Prerequisites
+See the [`/docs`](/docs) directory to view documentation on how to:


Suggested change

See the [`/docs`](/docs) directory to view documentation on how to:

See the [`documentation`](/docs) to learn how to:

concision

jwilliams-mongo · 2020-09-14T20:44:44Z

README.md

 - Use of any of the available [Docker MongoDB images](https://hub.docker.com/_/mongo/)
 - Clients inside the Kubernetes cluster can connect to the replica set (no external connectivity)
 - TLS support for client-to-server and server-to-server communication
+- Creating users with SCRAM-SHA authentication


your text looks good, but I think we should make these list items parallel. Doesn't have to be in this PR.

Ah good point, I just copy/pasted from below. Updated.

jwilliams-mongo · 2020-09-14T20:53:23Z

docs/users.md

+   ```
+   kubectl apply -f <mongodb-crd>.yaml --namespace <my-namespace>
+   ```
+1. Once the MongoDB resource is running, securely store the user's password and then delete the user secret:


Suggested change

1. Once the MongoDB resource is running, securely store the user's password and then delete the user secret:

1. After the MongoDB resource is running, securely store the user's password and then delete the user secret:

per style guide, use after here.

jwilliams-mongo · 2020-09-14T20:55:21Z

docs/deploy-configure.md

@@ -0,0 +1,85 @@
+# Deploy and Configure a MongoDB Resource #


Consider adding a readme.md in /docs with a TOC to make it easier to find information instead of clicking the individual files.

DIdn't realize I could have multiple readmes, good idea. Added.

jwilliams-mongo · 2020-09-14T20:56:43Z

docs/secure.md

+## Table of Contents
+
+- [Secure MongoDB Resource Connections using TLS](#secure-mongodb-resource-connections-using-tls)
+  - [Prerequisites](#prerequisites-1)


I think the prerequisites and procedure links can change now that there aren't multiple headings with those titles on this page.

jwilliams-mongo · 2020-09-14T20:57:21Z

docs/secure.md

+## Table of Contents
+
+- [Secure MongoDB Resource Connections using TLS](#secure-mongodb-resource-connections-using-tls)
+  - [Prerequisites](#prerequisites-1)


Suggested change

- [Prerequisites](#prerequisites-1)

- [Prerequisites](#prerequisites)

jwilliams-mongo · 2020-09-14T20:57:51Z

docs/secure.md

+
+- [Secure MongoDB Resource Connections using TLS](#secure-mongodb-resource-connections-using-tls)
+  - [Prerequisites](#prerequisites-1)
+  - [Procedure](#procedure-1)


Suggested change

- [Procedure](#procedure-1)

- [Procedure](#procedure)

jwilliams-mongo · 2020-09-14T21:05:40Z

docs/users.md

+       password: <my-plain-text-password> # corresponds to spec.users.passwordSecretRef.key in the MongoDB CRD
+     ...
+     ```
+1. Update `metadata.name` with the name of the secret and `stringData.password` with the user's password.


Offer clearer guidance here that you can provide anything you want for <db-user-secret>. I think users might ask what the name of the secret is without realizing they can provide any value here.

jwilliams-mongo · 2020-09-14T21:06:40Z

docs/users.md

@@ -0,0 +1,86 @@
+# Create a Database User #
+
+You can create a MongoDB database user to authenticate to your MongoDB resource using SCRAM. First, [create a Kubernetes secret](#create-a-user-secret) for the new user's password. Then, [modify and apply the MongoDB CRD](#modify-the-mongodb-crd).


consider linking to the Manual page on SCRAM here.

jwilliams-mongo · 2020-09-14T21:07:23Z

docs/users.md

+# Create a Database User #
+
+You can create a MongoDB database user to authenticate to your MongoDB resource using SCRAM. First, [create a Kubernetes secret](#create-a-user-secret) for the new user's password. Then, [modify and apply the MongoDB CRD](#modify-the-mongodb-crd).
+


Question about behavior here: When you create one SCRAM user, you will no longer be able to perform any actions unauthenticated, correct? I think we can be a little clearer about this here.

There are a handful of commands you can run without being authenticated, like the native commands (like listFiles() ) and a few database commands. I tried db.runCommand({connectionStatus : 1}) and isMaster, which both worked while unauthenticated. But I can't find a definitive list of unauthenticated commands, and I don't think the ones you can use actually do very much. Let me know if you want me to elaborate more in the topic. And maybe @chatton has an opinion :)

I think it should be clear enough to link to the SCRAM docs like we do here, as everything written there will apply, I don't think we need to clarify any more about this, I don't feel too strongly about this though.

jwilliams-mongo

LGTM % one nit

jwilliams-mongo · 2020-09-15T13:08:30Z

docs/README.md

@@ -0,0 +1,10 @@
+# MongoDB Community Kubernetes Operator Documentation #
+
+# Table of Contents


Suggested change

# Table of Contents

## Table of Contents

nit: this should be an H2.

chatton

Great work @melissamahoney-mongodb , I love the structure you added to the docs here.

I had just had one or two small comments!

chatton · 2020-09-15T14:56:59Z

docs/users.md

+   ```
+   kubectl apply -f <mongodb-crd>.yaml --namespace <my-namespace>
+   ```
+1. After the MongoDB resource is running, securely store the user's password and then delete the user secret:


as deleting the secret is not a required step, maybe we could say something more along the lines of "we recommend to delete the secret as it is no longer required by the operator",

Updated. I moved this down under "Next Steps".

chatton · 2020-09-15T15:00:49Z

docs/users.md

+   ```
+   mongo "mongodb://<mongodb-resource-metadata.name>-svc.<my-namespace>.svc.cluster.local:27017/?replicaSet=<replica-set-name>" --username <username> --password <password> --authenticationDatabase <authentication-database>
+   ```
+- To change a user's password, create and apply a new secret with a `metadata.name` that is the same as the name specified in `passwordSecretRef.name` of the MongoDB CRD. The Operator automatically re-generates the SCRAM credentials.


[nit] create a secret already indicates that the kubernetes secret resource is being created, but here you are referring to creating a new resource definition that contains the yaml for the new password.

I think we should phrase this as create and apply a new secret resource definition or just create a new secret as described above

[tiny-nit] The line The Operator automatically re-generates the SCRAM credentials. sounds a little off to me, I think we can just say, The Operator will automatically generate new credentials

Gotcha. Updated.

chatton · 2020-09-15T15:05:09Z

docs/users.md

+# Create a Database User #
+
+You can create a MongoDB database user to authenticate to your MongoDB resource using SCRAM. First, [create a Kubernetes secret](#create-a-user-secret) for the new user's password. Then, [modify and apply the MongoDB CRD](#modify-the-mongodb-crd).
+


I think it should be clear enough to link to the SCRAM docs like we do here, as everything written there will apply, I don't think we need to clarify any more about this, I don't feel too strongly about this though.

melissamahoney-mongodb · 2020-09-16T20:16:20Z

Thanks for the review @chatton ! Ready for another look.

chatton · 2020-09-17T13:38:05Z

docs/users.md

+   kubectl apply -f <db-user-secret>.yaml --namespace <my-namespace>
+   ```
+
+## Modify the MongoDB CRD


@melissamahoney-mongodb Ah! Sorry I think this may have been my fault, in this case CRD refers to a kubernetes CRD which is what we provide, the user will modify a MongoDB resource definition, but not the CRD itself. I think maybe most straight forward way to phrase this is Modify the MongoDB Resource

I think MongoDB resource is a good term to refer to individual instances of the Custom Resource which are described via the Custom Resource Definition (CRD)

Ah, I think I wasn't quite clear on that distinction myself. Thanks for the explanation! Updated.

chatton

LGTM thanks for the great work on this!

melissamahoney-mongodb requested review from chatton and jwilliams-mongo September 14, 2020 20:38

jwilliams-mongo reviewed Sep 14, 2020

View reviewed changes

melissamahoney-mongodb force-pushed the DOCSP-11424 branch from 86e769e to 52efa06 Compare September 14, 2020 21:52

jwilliams-mongo approved these changes Sep 15, 2020

View reviewed changes

chatton reviewed Sep 15, 2020

View reviewed changes

chatton reviewed Sep 17, 2020

View reviewed changes

melissamahoney-mongodb force-pushed the DOCSP-11424 branch from 8265f92 to 10a9a57 Compare September 17, 2020 14:30

chatton approved these changes Sep 17, 2020

View reviewed changes

melissamahoney-mongodb added 7 commits September 17, 2020 12:18

(DOCSP-11424): Document SCRAM Auth

49f88f8

cleanup

19bad35

rearrange

69ebc2a

more cleanup

0e3238c

copy review

0f0213a

tech review

67c66e1

tech review 2

b4f5f4b

melissamahoney-mongodb force-pushed the DOCSP-11424 branch from 10a9a57 to b4f5f4b Compare September 17, 2020 19:21

melissamahoney-mongodb merged commit 8492ec5 into mongodb:master Sep 17, 2020

	See the [`/docs`](/docs) directory to view documentation on how to:
	See the [`documentation`](/docs) to learn how to:

	1. Once the MongoDB resource is running, securely store the user's password and then delete the user secret:
	1. After the MongoDB resource is running, securely store the user's password and then delete the user secret:

	- [Prerequisites](#prerequisites-1)
	- [Prerequisites](#prerequisites)

		@@ -0,0 +1,86 @@
		# Create a Database User #

		You can create a MongoDB database user to authenticate to your MongoDB resource using SCRAM. First, [create a Kubernetes secret](#create-a-user-secret) for the new user's password. Then, [modify and apply the MongoDB CRD](#modify-the-mongodb-crd).

		@@ -0,0 +1,10 @@
		# MongoDB Community Kubernetes Operator Documentation #

		# Table of Contents

(DOCSP-11424): Document SCRAM Auth #196

(DOCSP-11424): Document SCRAM Auth #196

Uh oh!

Conversation

melissamahoney-mongodb commented Sep 14, 2020 • edited 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!

jwilliams-mongo Sep 14, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

melissamahoney-mongodb Sep 14, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jwilliams-mongo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chatton left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

melissamahoney-mongodb Sep 16, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

melissamahoney-mongodb commented Sep 16, 2020

Uh oh!

chatton Sep 17, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chatton left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

melissamahoney-mongodb commented Sep 14, 2020 •

edited

Loading

jwilliams-mongo Sep 14, 2020 •

edited

Loading

melissamahoney-mongodb Sep 14, 2020 •

edited

Loading

melissamahoney-mongodb Sep 16, 2020 •

edited

Loading

chatton Sep 17, 2020 •

edited

Loading