From 49f88f870b243bbd901413e20c0709935efa9b15 Mon Sep 17 00:00:00 2001 From: Melissa Mahoney Date: Mon, 14 Sep 2020 12:26:12 -0700 Subject: [PATCH 1/7] (DOCSP-11424): Document SCRAM Auth --- README.md | 251 +------------------- architecture.md => pkg/docs/architecture.md | 0 contributing.md => pkg/docs/contributing.md | 0 pkg/docs/deploy-configure.md | 85 +++++++ pkg/docs/install-upgrade.md | 60 +++++ pkg/docs/secure.md | 106 +++++++++ pkg/docs/users.md | 87 +++++++ 7 files changed, 348 insertions(+), 241 deletions(-) rename architecture.md => pkg/docs/architecture.md (100%) rename contributing.md => pkg/docs/contributing.md (100%) create mode 100644 pkg/docs/deploy-configure.md create mode 100644 pkg/docs/install-upgrade.md create mode 100644 pkg/docs/secure.md create mode 100644 pkg/docs/users.md diff --git a/README.md b/README.md index 0c7ce85a0..63b2cce24 100644 --- a/README.md +++ b/README.md @@ -8,250 +8,19 @@ If you are a MongoDB Enterprise customer, or need Enterprise features such as Ba ## Table of Contents -- [Install the Operator](#install-the-operator) - - [Prerequisites](#prerequisites) - - [Procedure](#procedure) -- [Upgrade the Operator](#upgrade-the-operator) -- [Deploy & Configure MongoDB Resources](#deploy-and-configure-a-mongodb-resource) - - [Deploy a Replica Set](#deploy-a-replica-set) - - [Upgrade MongoDB Version & FCV](#upgrade-your-mongodb-resource-version-and-feature-compatibility-version) -- [Secure MongoDB Resource Connections using TLS](#secure-mongodb-resource-connections-using-tls) - - [Prerequisites](#prerequisites-1) - - [Procedure](#procedure-1) +- [Documentation](#documentation) - [Supported Features](#supported-features) - [Contribute](#contribute) - [License](#license) -## Install the Operator +## Documentation -### Prerequisites +See the [`/docs`](docs) directory to view documentation on how to: -Before you install the MongoDB Community Kubernetes Operator, you must: - -1. Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). -2. Have a Kubernetes solution available to use. - If you need a Kubernetes solution, see the [Kubernetes documentation on picking the right solution](https://kubernetes.io/docs/setup). For testing, MongoDB recommends [Kind](https://kind.sigs.k8s.io/). -3. Clone this repository. - ``` - git clone https://github.com/mongodb/mongodb-kubernetes-operator.git - ``` - -### Procedure - -The MongoDB Community Kubernetes Operator is a [Custom Resource Definition](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and a controller. - -To install the MongoDB Community Kubernetes Operator: - -1. Change to the directory in which you cloned the repository. -2. Install the [Custom Resource Definitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). - - a. Invoke the following `kubectl` command: - ``` - kubectl create -f deploy/crds/mongodb.com_mongodb_crd.yaml - ``` - b. Verify that the Custom Resource Definitions installed successfully: - ``` - kubectl get crd/mongodb.mongodb.com - ``` -3. Install the Operator. - - a. Invoke the following `kubectl` command to install the Operator in the specified namespace: - ``` - kubectl create -f deploy/ --namespace - ``` - b. Verify that the Operator installed successsfully: - ``` - kubectl get pods --namespace - ``` - -## Upgrade the Operator - -To upgrade the MongoDB Community Kubernetes Operator: - -1. Change to the directory in which you cloned the repository. -2. Invoke the following `kubectl` command to upgrade the [Custom Resource Definitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). - ``` - kubectl apply -f deploy/crds/mongodb.com_mongodb_crd.yaml - ``` - -## Deploy and Configure a MongoDB Resource - -The [`/deploy/crds`](deploy/crds) directory contains example MongoDB resources that you can modify and deploy. - -### Deploy a Replica Set - -To deploy your first replica set: - -1. Invoke the following `kubectl` command: - ``` - kubectl apply -f deploy/crds/mongodb.com_v1_mongodb_cr.yaml --namespace - ``` -2. Verify that the MongoDB resource deployed: - ``` - kubectl get mongodb --namespace - ``` -3. connect clients to MongoDB replica set: - ``` - mongodb://-svc..svc.cluster.local:27017/?replicaSet= - ``` - -### Upgrade your MongoDB Resource Version and Feature Compatibility Version - -You can upgrade the major, minor, and/or feature compatibility versions of your MongoDB resource. These settings are configured in your resource definition YAML file. - -- To upgrade your resource's major and/or minor versions, set the `spec.version` setting to the desired MongoDB version. - -- To modify your resource's [feature compatibility version](https://docs.mongodb.com/manual/reference/command/setFeatureCompatibilityVersion/), set the `spec.featureCompatibilityVersion` setting to the desired version. - -If you update `spec.version` to a later version, consider setting `spec.featureCompatibilityVersion` to the current working MongoDB version to give yourself the option to downgrade if necessary. To learn more about feature compatibility, see [`setFeatureCompatibilityVersion`](https://docs.mongodb.com/manual/reference/command/setFeatureCompatibilityVersion/) in the MongoDB Manual. - -### Deploying on OpenShift - -If you want to deploy the operator on OpenShift you will have to provide the environment variable `MANAGED_SECURITY_CONTEXT` set to `true` for both the mongodb and mongodb agent containers, as well as the operator deployment. - -See [here](deploy/crds/mongodb.com_v1_mongodb_openshift_cr.yaml) for an example of how to provide the required configuration for a MongoDB ReplicaSet. - -See [here](deploy/openshift/operator_openshift.yaml) for an example of how to configure the Operator deployment. - -#### Example - -Consider the following example MongoDB resource definition: - -```yaml -apiVersion: mongodb.com/v1 -kind: MongoDB -metadata: - name: example-mongodb -spec: - members: 3 - type: ReplicaSet - version: "4.0.6" -``` -To upgrade this resource from `4.0.6` to `4.2.7`: - -1. Edit the resource definition. - - a. Update `spec.version` to `4.2.7`. - - b. Update `spec.featureCompatibilityVersion` to `4.0`. - - ```yaml - apiVersion: mongodb.com/v1 - kind: MongoDB - metadata: - name: example-mongodb - spec: - members: 3 - type: ReplicaSet - version: "4.2.7" - featureCompatibilityVersion: "4.0" - ``` - - **NOTE:** Setting `featureCompatibilityVersion` to `4.0` disables [4.2 features incompatible with MongoDB 4.0](https://docs.mongodb.com/manual/release-notes/4.2-compatibility/#compatibility-enabled). - -2. Reapply the configuration to Kubernetes: - ``` - kubectl apply -f .yaml --namespace - ``` - -## Secure MongoDB Resource Connections using TLS - -You can configure the MongoDB Community Kubernetes Operator to use TLS certificates to encrypt traffic between: - -- MongoDB hosts in a replica set, and -- Client applications and MongoDB deployments. - -### Prerequisites - -Before you secure MongoDB resource connections using TLS, you must: - -1. Create a PEM-encoded TLS certificate for the servers in the MongoDB resource using your own Certificate Authority (CA). The certificate must have one of the following: - - - A wildcard `Common Name` that matches the domain name of all of the replica set members: - - ``` - *.-svc..svc.cluster.local - ``` - - The domain name for each of the replica set members as `Subject Alternative Names` (SAN): - - ``` - -0.-svc..svc.cluster.local - -1.-svc..svc.cluster.local - -2.-svc..svc.cluster.local - ``` - -1. Create a Kubernetes ConfigMap that contains the certificate for the CA that signed your server certificate. The key in the ConfigMap that references the certificate must be named `ca.crt`. Kubernetes configures this automatically if the certificate file is named `ca.crt`: - ``` - kubectl create configmap --from-file=ca.crt --namespace - ``` - - For a certificate file with any other name, you must define the `ca.crt` key manually: - ``` - kubectl create configmap --from-file=ca.crt=.crt --namespace - ``` - -1. Create a Kubernetes secret that contains the server certificate and key for the members of your replica set. For a server certificate named `server.crt` and key named `server.key`: - ``` - kubectl create secret tls --cert=server.crt --key=server.key --namespace - ``` - -### Procedure - -To secure connections to MongoDB resources using TLS: - -1. Add the following fields to the MongoDB resource definition: - - - `spec.security.tls.enabled`: Encrypts communications using TLS certificates between MongoDB hosts in a replica set and client applications and MongoDB deployments. Set to `true`. - - `spec.security.tls.optional`: (**Optional**) Enables the members of the replica set to accept both TLS and non-TLS client connections. Equivalent to setting the MongoDB[`net.tls.mode`](https://docs.mongodb.com/manual/reference/configuration-options/#net.tls.mode) setting to `preferSSL`. If omitted, defaults to `false`. - - --- - **NOTE** - - When you enable TLS on an existing replica set deployment: - - a. Set `spec.security.tls.optional` to `true`. - - b. Apply the configuration to Kubernetes. - - c. Upgrade your existing clients to use TLS. - - d. Remove the `spec.security.tls.optional` field. - - e. Complete the remaining steps in the procedure. - - --- - - `spec.security.tls.certificateKeySecretRef.name`: Name of the Kubernetes secret that contains the server certificate and key that you created in the [prerequisites](#prerequisites-1). - - `spec.security.tls.caConfigMapRef.name`: Name of the Kubernetes ConfigMap that contains the Certificate Authority certificate used to sign the server certificate that you created in the [prerequisites](#prerequisites-1). - - ```yaml - apiVersion: mongodb.com/v1 - kind: MongoDB - metadata: - name: example-mongodb - spec: - members: 3 - type: ReplicaSet - version: "4.2.7" - security: - tls: - enabled: true - certificateKeySecretRef: - name: - caConfigMapRef: - name: - ``` - -1. Apply the configuration to Kubernetes: - ``` - kubectl apply -f .yaml --namespace - ``` -1. From within the Kubernetes cluster, connect to the MongoDB resource. - - If `spec.security.tls.optional` is omitted or `false`: clients must - establish TLS connections to the MongoDB servers in the replica set. - - If `spec.security.tls.optional` is true, clients can establish TLS or - non-TLS connections to the MongoDB servers in the replica set. - - See the documentation for your connection method to learn how to establish a TLS connection to a MongoDB server. +1. [Install or upgrade](docs/install-upgrade.md) the Operator. +1. [Deploy and configure](docs/deploy-configure.md) MongoDB resources. +1. [Create a database user] with SCRAM-SHA authentication. +1. [Secure](docs/secure.md) MongoDB resources. ## Supported Features @@ -265,17 +34,17 @@ The MongoDB Community Kubernetes Operator supports the following features: - 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 ### Planned Features - Server internal authentication via keyfile -- Creating users with SCRAM-SHA authentication ## Contribute Before you contribute to the MongoDB Community Kubernetes Operator, please read: -- [MongoDB Community Kubernetes Operator Architecture](architecture.md) -- [Contributing to MongoDB Community Kubernetes Operator](contributing.md) +- [MongoDB Community Kubernetes Operator Architecture](docs/architecture.md) +- [Contributing to MongoDB Community Kubernetes Operator](docs/contributing.md) Please file issues before filing PRs. For PRs to be accepted, contributors must sign our [CLA](https://www.mongodb.com/legal/contributor-agreement). diff --git a/architecture.md b/pkg/docs/architecture.md similarity index 100% rename from architecture.md rename to pkg/docs/architecture.md diff --git a/contributing.md b/pkg/docs/contributing.md similarity index 100% rename from contributing.md rename to pkg/docs/contributing.md diff --git a/pkg/docs/deploy-configure.md b/pkg/docs/deploy-configure.md new file mode 100644 index 000000000..59447cf14 --- /dev/null +++ b/pkg/docs/deploy-configure.md @@ -0,0 +1,85 @@ +# Deploy and Configure a MongoDB Resource # + +The [`/deploy/crds`](deploy/crds) directory contains example MongoDB resources that you can modify and deploy. + +## Table of Contents + +- [Deploy a Replica Set](#deploy-a-replica-set) +- [Upgrade MongoDB Version & FCV](#upgrade-your-mongodb-resource-version-and-feature-compatibility-version) +- [Deploying on Openshift](#deploying-on-openshift) + +## Deploy a Replica Set + +To deploy your first replica set: + +1. Invoke the following `kubectl` command: + ``` + kubectl apply -f deploy/crds/mongodb.com_v1_mongodb_cr.yaml --namespace + ``` +2. Verify that the MongoDB resource deployed: + ``` + kubectl get mongodb --namespace + ``` +3. Connect clients to the MongoDB replica set: + ``` + mongodb://-svc..svc.cluster.local:27017/?replicaSet= + ``` + +## Upgrade your MongoDB Resource Version and Feature Compatibility Version + +You can upgrade the major, minor, and/or feature compatibility versions of your MongoDB resource. These settings are configured in your resource definition YAML file. + +- To upgrade your resource's major and/or minor versions, set the `spec.version` setting to the desired MongoDB version. + +- To modify your resource's [feature compatibility version](https://docs.mongodb.com/manual/reference/command/setFeatureCompatibilityVersion/), set the `spec.featureCompatibilityVersion` setting to the desired version. + +If you update `spec.version` to a later version, consider setting `spec.featureCompatibilityVersion` to the current working MongoDB version to give yourself the option to downgrade if necessary. To learn more about feature compatibility, see [`setFeatureCompatibilityVersion`](https://docs.mongodb.com/manual/reference/command/setFeatureCompatibilityVersion/) in the MongoDB Manual. + +## Deploying on OpenShift + +If you want to deploy the operator on OpenShift you will have to provide the environment variable `MANAGED_SECURITY_CONTEXT` set to `true` for both the mongodb and mongodb agent containers, as well as the operator deployment. + +See [here](deploy/crds/mongodb.com_v1_mongodb_openshift_cr.yaml) for an example of how to provide the required configuration for a MongoDB ReplicaSet. + +See [here](deploy/operator_openshift.yaml) for an example of how to configure the Operator deployment. + +### Example + +Consider the following example MongoDB resource definition: + +```yaml +apiVersion: mongodb.com/v1 +kind: MongoDB +metadata: + name: example-mongodb +spec: + members: 3 + type: ReplicaSet + version: "4.0.6" +``` +To upgrade this resource from `4.0.6` to `4.2.7`: + +1. Edit the resource definition. + + a. Update `spec.version` to `4.2.7`. + + b. Update `spec.featureCompatibilityVersion` to `4.0`. + + ```yaml + apiVersion: mongodb.com/v1 + kind: MongoDB + metadata: + name: example-mongodb + spec: + members: 3 + type: ReplicaSet + version: "4.2.7" + featureCompatibilityVersion: "4.0" + ``` + + **NOTE:** Setting `featureCompatibilityVersion` to `4.0` disables [4.2 features incompatible with MongoDB 4.0](https://docs.mongodb.com/manual/release-notes/4.2-compatibility/#compatibility-enabled). + +2. Reapply the configuration to Kubernetes: + ``` + kubectl apply -f .yaml --namespace + ``` diff --git a/pkg/docs/install-upgrade.md b/pkg/docs/install-upgrade.md new file mode 100644 index 000000000..e58aee70c --- /dev/null +++ b/pkg/docs/install-upgrade.md @@ -0,0 +1,60 @@ +# Install and Upgrade the Community Kubernetes Operator # + +## Table of Contents + +- [Install the Operator](#install-the-operator) + - [Prerequisites](#prerequisites) + - [Procedure](#procedure) +- [Upgrade the Operator](#upgrade-the-operator) + +## Install the Operator + +### Prerequisites + +Before you install the MongoDB Community Kubernetes Operator, you must: + +1. Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). +2. Have a Kubernetes solution available to use. + If you need a Kubernetes solution, see the [Kubernetes documentation on picking the right solution](https://kubernetes.io/docs/setup). For testing, MongoDB recommends [Kind](https://kind.sigs.k8s.io/). +3. Clone this repository. + ``` + git clone https://github.com/mongodb/mongodb-kubernetes-operator.git + ``` + +### Procedure + +The MongoDB Community Kubernetes Operator is a [Custom Resource Definition](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and a controller. + +To install the MongoDB Community Kubernetes Operator: + +1. Change to the directory in which you cloned the repository. +2. Install the [Custom Resource Definitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). + + a. Invoke the following `kubectl` command: + ``` + kubectl create -f deploy/crds/mongodb.com_mongodb_crd.yaml + ``` + b. Verify that the Custom Resource Definitions installed successfully: + ``` + kubectl get crd/mongodb.mongodb.com + ``` +3. Install the Operator. + + a. Invoke the following `kubectl` command to install the Operator in the specified namespace: + ``` + kubectl create -f deploy/ --namespace + ``` + b. Verify that the Operator installed successsfully: + ``` + kubectl get pods --namespace + ``` + +## Upgrade the Operator + +To upgrade the MongoDB Community Kubernetes Operator: + +1. Change to the directory in which you cloned the repository. +2. Invoke the following `kubectl` command to upgrade the [Custom Resource Definitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). + ``` + kubectl apply -f deploy/crds/mongodb.com_mongodb_crd.yaml + ``` diff --git a/pkg/docs/secure.md b/pkg/docs/secure.md new file mode 100644 index 000000000..ae419246b --- /dev/null +++ b/pkg/docs/secure.md @@ -0,0 +1,106 @@ +# Secure MongoDB Resources # + +## Table of Contents + +- [Secure MongoDB Resource Connections using TLS](#secure-mongodb-resource-connections-using-tls) + - [Prerequisites](#prerequisites-1) + - [Procedure](#procedure-1) + +## Secure MongoDB Resource Connections using TLS + +You can configure the MongoDB Community Kubernetes Operator to use TLS certificates to encrypt traffic between: + +- MongoDB hosts in a replica set, and +- Client applications and MongoDB deployments. + +### Prerequisites + +Before you secure MongoDB resource connections using TLS, you must: + +1. Create a PEM-encoded TLS certificate for the servers in the MongoDB resource using your own Certificate Authority (CA). The certificate must have one of the following: + + - A wildcard `Common Name` that matches the domain name of all of the replica set members: + + ``` + *.-svc..svc.cluster.local + ``` + - The domain name for each of the replica set members as `Subject Alternative Names` (SAN): + + ``` + -0.-svc..svc.cluster.local + -1.-svc..svc.cluster.local + -2.-svc..svc.cluster.local + ``` + +1. Create a Kubernetes ConfigMap that contains the certificate for the CA that signed your server certificate. The key in the ConfigMap that references the certificate must be named `ca.crt`. Kubernetes configures this automatically if the certificate file is named `ca.crt`: + ``` + kubectl create configmap --from-file=ca.crt --namespace + ``` + + For a certificate file with any other name, you must define the `ca.crt` key manually: + ``` + kubectl create configmap --from-file=ca.crt=.crt --namespace + ``` + +1. Create a Kubernetes secret that contains the server certificate and key for the members of your replica set. For a server certificate named `server.crt` and key named `server.key`: + ``` + kubectl create secret tls --cert=server.crt --key=server.key --namespace + ``` + +### Procedure + +To secure connections to MongoDB resources using TLS: + +1. Add the following fields to the MongoDB resource definition: + + - `spec.security.tls.enabled`: Encrypts communications using TLS certificates between MongoDB hosts in a replica set and client applications and MongoDB deployments. Set to `true`. + - `spec.security.tls.optional`: (**Optional**) Enables the members of the replica set to accept both TLS and non-TLS client connections. Equivalent to setting the MongoDB[`net.tls.mode`](https://docs.mongodb.com/manual/reference/configuration-options/#net.tls.mode) setting to `preferSSL`. If omitted, defaults to `false`. + + --- + **NOTE** + + When you enable TLS on an existing replica set deployment: + + a. Set `spec.security.tls.optional` to `true`. + + b. Apply the configuration to Kubernetes. + + c. Upgrade your existing clients to use TLS. + + d. Remove the `spec.security.tls.optional` field. + + e. Complete the remaining steps in the procedure. + + --- + - `spec.security.tls.certificateKeySecretRef.name`: Name of the Kubernetes secret that contains the server certificate and key that you created in the [prerequisites](#prerequisites-1). + - `spec.security.tls.caConfigMapRef.name`: Name of the Kubernetes ConfigMap that contains the Certificate Authority certificate used to sign the server certificate that you created in the [prerequisites](#prerequisites-1). + + ```yaml + apiVersion: mongodb.com/v1 + kind: MongoDB + metadata: + name: example-mongodb + spec: + members: 3 + type: ReplicaSet + version: "4.2.7" + security: + tls: + enabled: true + certificateKeySecretRef: + name: + caConfigMapRef: + name: + ``` + +1. Apply the configuration to Kubernetes: + ``` + kubectl apply -f .yaml --namespace + ``` +1. From within the Kubernetes cluster, connect to the MongoDB resource. + - If `spec.security.tls.optional` is omitted or `false`: clients must + establish TLS connections to the MongoDB servers in the replica set. + - If `spec.security.tls.optional` is true, clients can establish TLS or + non-TLS connections to the MongoDB servers in the replica set. + + See the documentation for your connection method to learn how to establish a TLS connection to a MongoDB server. diff --git a/pkg/docs/users.md b/pkg/docs/users.md new file mode 100644 index 000000000..3155a71be --- /dev/null +++ b/pkg/docs/users.md @@ -0,0 +1,87 @@ +# Create a Database User # + +You can create database users through the [MongoDB CRD](deploy/crds/mongodb.com_v1_mongodb_scram_cr.yaml). + +SCRAM authentication is always enabled. + +## Table of Contents + +- [Create a Database User with SCRAM Authentication](#create-a-database-user-with-scram-authentication) + - [Create a User Secret](#create-a-user-secret) + - [Modify the MongoDB CRD](#modify-the-mongodb-crd) + +## Create a Database User with SCRAM Authentication + +### Create a User Secret + +1. Copy the following example secret. + + ``` + --- + apiVersion: v1 + kind: Secret + metadata: + name: # corresponds to spec.users.passwordSecretRef.name + type: Opaque + stringData: + password: # corresponds to spec.users.passwordSecretRef.key + ... + ``` +1. Update `metadata.name` with the name of the secret and `stringData.password` with the user's password. +1. Save the secret with a `.yaml` file extension. +1. Apply the secret in Kubernetes: + ``` + kubectl apply -f .yaml + ``` + +### Modify the MongoDB CRD + +1. Add the following fields to the MongoDB resource definition: + + | *Key* | *Type* | *Description* | *Required?* | + |----|----|----|----| + | spec.users | array of objects | Configures database users for this deployment. | Yes | + | spec.users.name | string | Username of the database user. | Yes | + | spec.users.db | string | Database that the user authenticates against. Defaults to `admin`. | No | + | spec.users.passwordSecretRef.name | string | Name of the secret that contains the user's plain text password. | |Yes| + | spec.users.passwordSecretRef.key | string| Key in the secret that corresponds to the value of the user's password. Defaults to `password`. | No | + | spec.users.roles | array of objects | Configures roles assigned to the user. | Yes | + | spec.users.roles.role.name | string | Name of the role. Valid values are [built-in roles](https://docs.mongodb.com/manual/reference/built-in-roles/#built-in-roles). | Yes | + | spec.users.roles.role.db | string | Database that the role applies to. | Yes | + + ``` + --- + apiVersion: mongodb.com/v1 + kind: MongoDB + metadata: + name: example-scram-mongodb + spec: + members: 3 + type: ReplicaSet + version: "4.2.6" + security: + authentication: + modes: ["SCRAM"] + users: + - name: + db: + passwordSecretRef: + name: + roles: + - name: + db: + - name: + db: + ... + ``` +1. Save the file. +1. Apply the updated MongoDB resource definition: + + ``` + kubectl apply -f .yaml --namespace + ``` + The Operator generates SCRAM credentials for the new user from the password secret. +1. Once the resource is running, delete the password secret. + ``` + kubectl delete secret --namespace + ``` From 19bad354b4deb47870693b420f1b4fa3beb4e068 Mon Sep 17 00:00:00 2001 From: Melissa Mahoney Date: Mon, 14 Sep 2020 12:29:45 -0700 Subject: [PATCH 2/7] cleanup --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 63b2cce24..cc0989dab 100644 --- a/README.md +++ b/README.md @@ -15,12 +15,12 @@ If you are a MongoDB Enterprise customer, or need Enterprise features such as Ba ## Documentation -See the [`/docs`](docs) directory to view documentation on how to: +See the [`/docs`](/docs) directory to view documentation on how to: -1. [Install or upgrade](docs/install-upgrade.md) the Operator. -1. [Deploy and configure](docs/deploy-configure.md) MongoDB resources. -1. [Create a database user] with SCRAM-SHA authentication. -1. [Secure](docs/secure.md) MongoDB resources. +1. [Install or upgrade](/docs/install-upgrade.md) the Operator. +1. [Deploy and configure](/docs/deploy-configure.md) MongoDB resources. +1. [Create a database user](/docs/users.md) with SCRAM-SHA authentication. +1. [Secure](/docs/secure.md) MongoDB resources. ## Supported Features From 69ebc2ae450fdc94c82e16e9f0c83eb61a0e39db Mon Sep 17 00:00:00 2001 From: Melissa Mahoney Date: Mon, 14 Sep 2020 12:32:47 -0700 Subject: [PATCH 3/7] rearrange --- {pkg/docs => docs}/architecture.md | 0 {pkg/docs => docs}/contributing.md | 0 {pkg/docs => docs}/deploy-configure.md | 0 {pkg/docs => docs}/install-upgrade.md | 0 {pkg/docs => docs}/secure.md | 0 {pkg/docs => docs}/users.md | 0 6 files changed, 0 insertions(+), 0 deletions(-) rename {pkg/docs => docs}/architecture.md (100%) rename {pkg/docs => docs}/contributing.md (100%) rename {pkg/docs => docs}/deploy-configure.md (100%) rename {pkg/docs => docs}/install-upgrade.md (100%) rename {pkg/docs => docs}/secure.md (100%) rename {pkg/docs => docs}/users.md (100%) diff --git a/pkg/docs/architecture.md b/docs/architecture.md similarity index 100% rename from pkg/docs/architecture.md rename to docs/architecture.md diff --git a/pkg/docs/contributing.md b/docs/contributing.md similarity index 100% rename from pkg/docs/contributing.md rename to docs/contributing.md diff --git a/pkg/docs/deploy-configure.md b/docs/deploy-configure.md similarity index 100% rename from pkg/docs/deploy-configure.md rename to docs/deploy-configure.md diff --git a/pkg/docs/install-upgrade.md b/docs/install-upgrade.md similarity index 100% rename from pkg/docs/install-upgrade.md rename to docs/install-upgrade.md diff --git a/pkg/docs/secure.md b/docs/secure.md similarity index 100% rename from pkg/docs/secure.md rename to docs/secure.md diff --git a/pkg/docs/users.md b/docs/users.md similarity index 100% rename from pkg/docs/users.md rename to docs/users.md From 0e3238cae3a0bc1c346e7737d45d9f2622ccc172 Mon Sep 17 00:00:00 2001 From: Melissa Mahoney Date: Mon, 14 Sep 2020 13:23:04 -0700 Subject: [PATCH 4/7] more cleanup --- README.md | 4 ++-- docs/users.md | 53 +++++++++++++++++++++++++-------------------------- 2 files changed, 28 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index cc0989dab..acb36b076 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,8 @@ See the [`/docs`](/docs) directory to view documentation on how to: 1. [Install or upgrade](/docs/install-upgrade.md) the Operator. 1. [Deploy and configure](/docs/deploy-configure.md) MongoDB resources. -1. [Create a database user](/docs/users.md) with SCRAM-SHA authentication. -1. [Secure](/docs/secure.md) MongoDB resources. +1. [Create a database user](/docs/users.md) with SCRAM authentication. +1. [Secure MongoDB resource connections](/docs/secure.md) using TLS. ## Supported Features diff --git a/docs/users.md b/docs/users.md index 3155a71be..d65ff7d5d 100644 --- a/docs/users.md +++ b/docs/users.md @@ -1,18 +1,10 @@ # Create a Database User # -You can create database users through the [MongoDB CRD](deploy/crds/mongodb.com_v1_mongodb_scram_cr.yaml). +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). -SCRAM authentication is always enabled. +You cannot disable SCRAM authentication. -## Table of Contents - -- [Create a Database User with SCRAM Authentication](#create-a-database-user-with-scram-authentication) - - [Create a User Secret](#create-a-user-secret) - - [Modify the MongoDB CRD](#modify-the-mongodb-crd) - -## Create a Database User with SCRAM Authentication - -### Create a User Secret +## Create a User Secret 1. Copy the following example secret. @@ -21,33 +13,33 @@ SCRAM authentication is always enabled. apiVersion: v1 kind: Secret metadata: - name: # corresponds to spec.users.passwordSecretRef.name + name: # corresponds to spec.users.passwordSecretRef.name in the MongoDB CRD type: Opaque stringData: - password: # corresponds to spec.users.passwordSecretRef.key + 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. 1. Save the secret with a `.yaml` file extension. 1. Apply the secret in Kubernetes: ``` - kubectl apply -f .yaml + kubectl apply -f .yaml --namespace ``` -### Modify the MongoDB CRD +## Modify the MongoDB CRD 1. Add the following fields to the MongoDB resource definition: - | *Key* | *Type* | *Description* | *Required?* | + | Key | Type | Description | Required? | |----|----|----|----| - | spec.users | array of objects | Configures database users for this deployment. | Yes | - | spec.users.name | string | Username of the database user. | Yes | - | spec.users.db | string | Database that the user authenticates against. Defaults to `admin`. | No | - | spec.users.passwordSecretRef.name | string | Name of the secret that contains the user's plain text password. | |Yes| - | spec.users.passwordSecretRef.key | string| Key in the secret that corresponds to the value of the user's password. Defaults to `password`. | No | - | spec.users.roles | array of objects | Configures roles assigned to the user. | Yes | - | spec.users.roles.role.name | string | Name of the role. Valid values are [built-in roles](https://docs.mongodb.com/manual/reference/built-in-roles/#built-in-roles). | Yes | - | spec.users.roles.role.db | string | Database that the role applies to. | Yes | + | `spec.users` | array of objects | Configures database users for this deployment. | Yes | + | `spec.users.name` | string | Username of the database user. | Yes | + | `spec.users.db` | string | Database that the user authenticates against. Defaults to `admin`. | No | + | `spec.users.passwordSecretRef.name` | string | Name of the secret that contains the user's plain text password. | Yes| + | `spec.users.passwordSecretRef.key` | string| Key in the secret that corresponds to the value of the user's password. Defaults to `password`. | No | + | `spec.users.roles` | array of objects | Configures roles assigned to the user. | Yes | + | `spec.users.roles.role.name` | string | Name of the role. Valid values are [built-in roles](https://docs.mongodb.com/manual/reference/built-in-roles/#built-in-roles). | Yes | + | `spec.users.roles.role.db` | string | Database that the role applies to. | Yes | ``` --- @@ -78,10 +70,17 @@ SCRAM authentication is always enabled. 1. Apply the updated MongoDB resource definition: ``` - kubectl apply -f .yaml --namespace + kubectl apply -f .yaml --namespace ``` - The Operator generates SCRAM credentials for the new user from the password secret. -1. Once the resource is running, delete the password secret. +1. Once the MongoDB resource is running, securely store the user's password and then delete the user secret: ``` kubectl delete secret --namespace ``` + +## Next Steps + +- To authenticate to your MongoDB resource, run the following command: + ``` + mongo "mongodb://-svc..svc.cluster.local:27017/?replicaSet=" --username --password --authenticationDatabase + ``` +- 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. From 0f0213ae00d35e57efdc7dc13991041e7caa8b4e Mon Sep 17 00:00:00 2001 From: Melissa Mahoney Date: Mon, 14 Sep 2020 14:50:31 -0700 Subject: [PATCH 5/7] copy review --- README.md | 24 ++++++++++++------------ docs/README.md | 10 ++++++++++ docs/secure.md | 4 ++-- docs/users.md | 7 ++++--- 4 files changed, 28 insertions(+), 17 deletions(-) create mode 100644 docs/README.md diff --git a/README.md b/README.md index acb36b076..34e30252d 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ If you are a MongoDB Enterprise customer, or need Enterprise features such as Ba ## Documentation -See the [`/docs`](/docs) directory to view documentation on how to: +See the [documentation](/docs) to learn how to: 1. [Install or upgrade](/docs/install-upgrade.md) the Operator. 1. [Deploy and configure](/docs/deploy-configure.md) MongoDB resources. @@ -26,15 +26,15 @@ See the [`/docs`](/docs) directory to view documentation on how to: The MongoDB Community Kubernetes Operator supports the following features: -- MongoDB Topology: [replica sets](https://docs.mongodb.com/manual/replication/) -- Upgrading and downgrading MongoDB server version -- Scaling replica sets up and down -- Reading from and writing to the replica set while scaling, upgrading, and downgrading. These operations are done in an "always up" manner. -- Reporting of MongoDB server state via the [MongoDB resource](/deploy/crds/mongodb.com_mongodb_crd.yaml) `status` field -- 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 +- Create [replica sets](https://docs.mongodb.com/manual/replication/) +- Upgrade and downgrade MongoDB server version +- Scale replica sets up and down +- Read from and write to the replica set while scaling, upgrading, and downgrading. These operations are done in an "always up" manner. +- Report MongoDB server state via the [MongoDB resource](/deploy/crds/mongodb.com_mongodb_crd.yaml) `status` field +- Use any of the available [Docker MongoDB images](https://hub.docker.com/_/mongo/) +- Connect to the replica set from inside the Kubernetes cluster (no external connectivity) +- Secure client-to-server and server-to-server connections with TLS +- Create users with [SCRAM](https://docs.mongodb.com/manual/core/security-scram/) authentication ### Planned Features - Server internal authentication via keyfile @@ -43,8 +43,8 @@ The MongoDB Community Kubernetes Operator supports the following features: Before you contribute to the MongoDB Community Kubernetes Operator, please read: -- [MongoDB Community Kubernetes Operator Architecture](docs/architecture.md) -- [Contributing to MongoDB Community Kubernetes Operator](docs/contributing.md) +- [MongoDB Community Kubernetes Operator Architecture](/docs/architecture.md) +- [Contributing to MongoDB Community Kubernetes Operator](/docs/contributing.md) Please file issues before filing PRs. For PRs to be accepted, contributors must sign our [CLA](https://www.mongodb.com/legal/contributor-agreement). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..eae6badbf --- /dev/null +++ b/docs/README.md @@ -0,0 +1,10 @@ +# MongoDB Community Kubernetes Operator Documentation # + +# Table of Contents + +- [Contribute to the MongoDB Kubernetes Operator](/docs/contributing.md) +- [MongoDB Community Kubernetes Operator Architecture](/docs/architecutre.md) +- [Install and Upgrade the Community Kubernetes Operator](/docs/install-upgrade.md) +- [Deploy and Configure MongoDB Resources](/docs/deploy-configure.md) +- [Create Database Users](/docs/users.md) +- [Secure MongoDB Resources](/docs/secure.md) diff --git a/docs/secure.md b/docs/secure.md index ae419246b..60d833c23 100644 --- a/docs/secure.md +++ b/docs/secure.md @@ -3,8 +3,8 @@ ## Table of Contents - [Secure MongoDB Resource Connections using TLS](#secure-mongodb-resource-connections-using-tls) - - [Prerequisites](#prerequisites-1) - - [Procedure](#procedure-1) + - [Prerequisites](#prerequisites) + - [Procedure](#procedure) ## Secure MongoDB Resource Connections using TLS diff --git a/docs/users.md b/docs/users.md index d65ff7d5d..fd0daabe6 100644 --- a/docs/users.md +++ b/docs/users.md @@ -1,6 +1,6 @@ # 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). +You can create a MongoDB database user to authenticate to your MongoDB resource using [SCRAM](https://docs.mongodb.com/manual/core/security-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). You cannot disable SCRAM authentication. @@ -19,7 +19,8 @@ You cannot disable SCRAM authentication. 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. +1. Update the value of `metadata.name` with any name for this secret. +1. Update the value of `stringData.password` with the user's password. 1. Save the secret with a `.yaml` file extension. 1. Apply the secret in Kubernetes: ``` @@ -72,7 +73,7 @@ You cannot disable SCRAM authentication. ``` kubectl apply -f .yaml --namespace ``` -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: ``` kubectl delete secret --namespace ``` From 67c66e167c5a255e8ea0c9ca1385d0140de98932 Mon Sep 17 00:00:00 2001 From: Melissa Mahoney Date: Wed, 16 Sep 2020 13:15:23 -0700 Subject: [PATCH 6/7] tech review --- docs/users.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/users.md b/docs/users.md index fd0daabe6..c1293a684 100644 --- a/docs/users.md +++ b/docs/users.md @@ -73,15 +73,16 @@ You cannot disable SCRAM authentication. ``` kubectl apply -f .yaml --namespace ``` -1. After the MongoDB resource is running, securely store the user's password and then delete the user secret: - ``` - kubectl delete secret --namespace - ``` ## Next Steps +- After the MongoDB resource is running, the Operator no longer requires the user's secret. MongoDB recommends that you securely store the user's password and then delete the user secret: + ``` + kubectl delete secret --namespace + ``` + - To authenticate to your MongoDB resource, run the following command: ``` mongo "mongodb://-svc..svc.cluster.local:27017/?replicaSet=" --username --password --authenticationDatabase ``` -- 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. +- To change a user's password, create and apply a new secret resource definition with a `metadata.name` that is the same as the name specified in `passwordSecretRef.name` of the MongoDB CRD. The Operator will automatically regenerate credentials. From b4f5f4b269b128a5ceab6876f5d4bc9dacf4b1c3 Mon Sep 17 00:00:00 2001 From: Melissa Mahoney Date: Thu, 17 Sep 2020 07:28:47 -0700 Subject: [PATCH 7/7] tech review 2 --- .DS_Store | Bin 0 -> 8196 bytes deploy/.DS_Store | Bin 0 -> 6148 bytes docs/README.md | 2 +- docs/users.md | 4 ++-- 4 files changed, 3 insertions(+), 3 deletions(-) create mode 100644 .DS_Store create mode 100644 deploy/.DS_Store diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..48cab7faf57ec32242104b12dbd48b36a55d4ebc GIT binary patch literal 8196 zcmeHMziSjh82#pM^-gU97N!u~$^;QL_y@Q-E|rZW2zKUvaXGxp9=YT|EWAd+!eA*P z7-DB33W{9>J3*|(QUnVtEkwH%zWH&x-|Ua8L=G|oJKr+jn|bfv&hG5&5s|2DH5Z6x ziKvW2#+hTNGK$R0BUK8f1>=xFf9kduRvKZipF+9@=YVs-Ip7>{4mby<#R06@vXpby zeVui+bHF)pARUm;2Oo!wfr%p>)uRKI+5#YYXjTR1Gx7w{H!(1Aq$4sYLU%>fU4_|V z2;Cj+zQF}1j&#)BNtn%tFwDa2P=sQ~_`ZUZ2y}F{bHF)}c0lgkJvv8i>d+?Nzl$?- zdpy?*tJQiptfQ^$l};@FzVmL;&NnCK`)l#H0dZN~rKK@1tO= zzQfdn+kO1rkZv{yjcz>*yYl&NC2T7$eM#oIs9W3TAN4RN|6!yl6B%Eq$w*6|UL}h#?*_FkP2Th4&}1@P$Nv894=3-c zi4tXF?sV4TEA3!V+>QfGkqu1IKHNxn@p>+e;QYI9m%lx$m>bp_hhLq1l%+>}m3lmV zO_I0kpL;yVHJpCGJib|?zMMTPZ}aX*-tw3i^P`6Inso)})aNV=*YWbltMS7tH5S)1 z31{h|RjI2)L(I_)T%``?>$A*|+xo31J!An*K8{r!vPj%WN7V(DgvfTa9Y>7*FvPiU ea)F5>9g#u#?;irp%d%Vl@rK~me>DdWV)YlIf#1{s literal 0 HcmV?d00001 diff --git a/deploy/.DS_Store b/deploy/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..617ac7b19ba37432157c03972a6e540b3d1217c2 GIT binary patch literal 6148 zcmeHKu};H44E2==1z0*V-pYh3#2%vX0jNKK(o}RvNtF;LhAiy-0XrMNz^A|;Fm>el z&I*aziV373yYjt@&pzM1NO4U>Ca$vy(U^!rDC6h=!xrIn)(shnh2sqGkyW!iEs7iu zD#Kua-(5g6Dk-C?`~F&EelwZQisj1R=cMiiEQ=&b^CE>Ue1AB7`h0x5=&xt(`g!>J ze0JYoUoER%ese1OXV|ZhW2;~HJnQw<$4l(;?eP6R+fTmzb4Ez7 zq6{bl%D|8rkTM+}4fzs!c4a^r_!S2D`(UArkznJ|eL66>762H)>;!Y}B{;?kMuLq; ztU!zp1^Q4UEr#*ouv_tq1RIY&oQyOdMlu`eP>jot{jGB+6M5888BhlL4D9*GG1vdg z-Ti+*NS~AeW#C^iV1i_t#JG~w){V.yaml --namespace ``` -## Modify the MongoDB CRD +## Modify the MongoDB Resource 1. Add the following fields to the MongoDB resource definition: