(DOCSP-21346): Revised the Prometheus tutorial. (mongodb#932)

corryroot · web-flow · commit 93c86675b851 · 2022-03-24T12:00:12.000-04:00
* (DOCSP-21346): Revised the Prometheus tutorial.

* (DOCSP-21346): Incorporated JW's feedback.

* (DOCSP-21346): Fixed link.

* (DOCSP-21346): Added note about full URL.

* (DOCSP-21346): Fixed broken link.
diff --git a/docs/prometheus/README.md b/docs/prometheus/README.md
@@ -1,148 +1,189 @@
-# Using Prometheus with your MongoDB Resource
+# Use Prometheus with your MongoDB Resource
 
-We have added a sample yaml file that you could use to deploy a MongoDB resource
-in your Kubernetes cluster, with a
+ You can use the [mongodb-prometheus-sample.yaml](mongodb-prometheus-sample.yaml) file to 
+ deploy a MongoDB resource in your Kubernetes cluster, with a
 [`ServiceMonitor`](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/getting-started.md#related-resources)
-to indicate Prometheus how to consume metrics data from it.
+to indicate to Prometheus how to consume metrics data from 
+it.
 
-This is a simple MongoDB resource with one user, and with the `spec.Prometheus`
-attribute with basic HTTP Auth and no TLS, that will allow you to test
-Prometheus metrics coming from MongoDB.
+The sample specifies a simple MongoDB resource with one user,
+and the `spec.Prometheus` attribute with basic HTTP 
+authentication and no TLS. The sample lets you test
+the metrics that MongoDB sends to Prometheus.
 
 ## Quick Start
 
-We have tested this setup with version 0.54 of the [Prometheus
+We tested this setup with version 0.54 of the [Prometheus
 Operator](https://github.com/prometheus-operator/prometheus-operator).
 
-### Installing Prometheus Operator
+### Prerequisites
 
-The Prometheus Operator can be installed using Helm. Find the installation
-instructions
-[here](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack#kube-prometheus-stack):
+* Kubernetes 1.16+
+* Helm 3+
 
-This can be done with:
+### Install the Prometheus Operator
+
+You can install the Prometheus Operator using Helm. To learn 
+more, see the [installation instructions](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack#kube-prometheus-stack).
+
+To install the Prometheus Operator using Helm, run the 
+following commands:
 
 ``` shell
 helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
 helm repo update
-helm install prometheus prometheus-community/kube-prometheus-stack --namespace prometheus-system --create-namespace
+helm install prometheus prometheus-community/ \   
+  kube-prometheus-stack --namespace <prometheus-system> \   
+  --create-namespace
 ```
 
-### Installing MongoDB
-
-*Change after release to a proper Helm install.*
+### Install the MongoDB Community Kubernetes Operator
 
-* Create a Namespace to hold our MongoDB Operator and Resources
+Run the following command to install the Community Kubernetes 
+Operator and create a namespace to contain the Community 
+Kubernetes Operator and resources:
 
 ``` shell
-kubectl create namespace mongodb
+helm install community-operator mongodb/community-operator --namespace <mongodb> --create-namespace
 ```
 
-* Follow the [Installation Instructions](https://github.com/mongodb/mongodb-kubernetes-operator/blob/master/docs/install-upgrade.md#operator-in-same-namespace-as-resources)
+To learn more, see the [Installation Instructions](/docs/install-upgrade.md#operator-in-same-namespace-as-resources).
 
-## Creating a MongoDB Resource
+## Create a MongoDB Resource
 
-We have created a sample yaml definition that you can use to create a MongoDB
-resource and a `ServiceMonitor` that will indicate Prometheus to start scraping
-its metrics information.
+ You can use the [mongodb-prometheus-sample.yaml](mongodb-prometheus-sample.yaml) file to 
+ deploy a MongoDB resource in your Kubernetes cluster, with a
+[`ServiceMonitor`](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/getting-started.md#related-resources)
+to indicate to Prometheus how to consume metrics data from 
+it.
 
-You can apply it directly with:
+You can apply the sample directly with the following command:
 
 ``` shell
-kubectl apply -f mongodb-prometheus-sample.yaml
+kubectl apply -f <mongodb-prometheus-sample.yaml>
 ```
 
-This will create 2 `Secrets` containing authentication for a new MongoDB user
-and Basic HTTP Auth for the Prometheus endpoint. All of this in the `mongodb`
-Namespace.
+**Note:** If you haven't cloned the 
+[mongodb-kubernetes-operator](https://github.com/mongodb/mongodb-kubernetes-operator) 
+repository, you must provide the full URL that points to the 
+[mongodb-prometheus-sample.yaml](mongodb-prometheus-sample.yaml) file in the command:
+[https://raw.githubusercontent.com/mongodb/mongodb-kubernetes-operator/master/docs/prometheus/mongodb-prometheus-sample.yaml](mongodb-prometheus-sample.yaml)
+
+This command creates two `Secrets` that contain authentication 
+for a new MongoDB user and basic HTTP authentication for the 
+Prometheus endpoint. The command creates both `Secrets` in the 
+`mongodb` namespace.
 
-It will also create a `ServiceMonitor` that will configure Prometheus to consume
-this resurce's metrics. This will be created in the `prometheus-system`
+This command also creates a `ServiceMonitor` that configures 
+Prometheus to consume this resource's metrics. This command 
+creates the `ServiceMonitor` in the `prometheus-system`
 namespace.
 
+## Optional: Enable TLS on the Prometheus Endpoint
 
-## Bonus: Enable TLS on the Prometheus Endpoint
+### Install Cert-Manager
 
-### Installing Cert-Manager
+1. Run the following commands to install
+   [Cert-Manager](https://cert-manager.io/) using Helm:
 
-We will install [Cert-Manager](https://cert-manager.io/) from using Helm.
+   ``` shell
+   helm repo add jetstack https://charts.jetstack.io
+   helm repo update
+   helm install \
+     cert-manager jetstack/cert-manager \
+     --namespace cert-manager \
+     --create-namespace \
+     --version v1.7.1 \
+     --set installCRDs=true
+   ```
 
-``` shell
-helm repo add jetstack https://charts.jetstack.io
-helm repo update
-helm install \
-  cert-manager jetstack/cert-manager \
-  --namespace cert-manager \
-  --create-namespace \
-  --version v1.7.1 \
-  --set installCRDs=true
-```
+2. Now with Cert-Manager installed, create a Cert-Manager 
+   `Issuer` and then a `Certificate`. You can use the two files 
+   that we provide to create a new `Issuer`:
 
-Now with Cert-Manager installed we we'll create a Cert-Manager `Issuer` and then
-a `Certificate`. We provide 2 files that can be used to create a new `Issuer`.
+   a. Run the following command to create a `Secret` that 
+      contains the TLS certificate `tls.crt` and `tls.key` 
+      entries. You can use the certificate and key files that 
+      we provide in the [`testdata/tls`](/testdata/tls) directory to create a Cert-Manager `Certificate`.
 
-First we need to create a `Secret` holding a TLS certificate `tls.crt` and
-`tls.key` entries. We provide the certificate and key files that can be used to
-create a Cert-Manager `Certificate`, they are in the `testdata/tls` directory.
+      ``` shell
+      kubectl create secret tls issuer-secret --cert=../../testdata/tls/ca.crt --key=../../testdata/tls/ca.key \
+        --namespace mongodb
+      ```
 
-``` shell
-$ kubectl create secret tls issuer-secret --cert=../../testdata/tls/ca.crt --key=../../testdata/tls/ca.key \
-    --namespace mongodb
-secret/issuer-secret created
-```
+      The following response appears:
 
-And now we are ready to create a new `Issuer` and `Certificate`, by running the
-following command:
+      ``` shell
+      secret/issuer-secret created
+      ```
 
-``` shell
-$ kubectl apply -f issuer-and-cert.yaml --namespace mongodb
-issuer.cert-manager.io/ca-issuer created
-certificate.cert-manager.io/prometheus-target-cert created
-```
+   b. Run the following command to create a new `Issuer` and 
+      `Certificate`:
+
+      ``` shell
+      kubectl apply -f issuer-and-cert.yaml --namespace mongodb
+      ```
+      The following response appears:
 
-### Enabling TLS on the MongoDB CRD
+      ``` shell
+      issuer.cert-manager.io/ca-issuer created
+      certificate.cert-manager.io/prometheus-target-cert created
+      ```
 
-<center>_Make sure this configuration is not used in Production environments! A Security
-expert should be advising you on how to configure TLS_</center>
+### Enable TLS on the MongoDB CRD
 
-We need to add a new entry to `spec.prometheus` section of the MongoDB
-`CustomResource`; we can do it executing the following
-[patch](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/)
-operation.
+**Important!** Do **NOT** use this configuration in Production 
+environments! A security expert should advise you about how to 
+configure TLS.
+
+To enable TLS, you must add a new entry to the
+`spec.prometheus` section of the MongoDB `CustomResource`. Run 
+the following [patch](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/)
+operation to add the needed entry.
 
 ``` shell
-$ kubectl patch mdbc mongodb --type='json' \
-    -p='[{"op": "add", "path": "/spec/prometheus/tlsSecretKeyRef", "value":{"name": "prometheus-target-cert"}}]' \
-    --namespace mongodb
+kubectl patch mdbc mongodb --type='json' \
+  -p='[{"op": "add", "path": "/spec/prometheus/tlsSecretKeyRef", "value":{"name": "prometheus-target-cert"}}]' \
+  --namespace mongodb
+```
 
+The following response appears:
+
+``` shell
 mongodbcommunity.mongodbcommunity.mongodb.com/mongodb patched
 ```
 
-After a few minutes, the MongoDB resource should be back in Running phase. Now
-we need to configure our Prometheus `ServiceMonitor` to point at the HTTPS
-endpoint.
+After a few minutes, the MongoDB resource should return to the 
+Running phase. Now you must configure the Prometheus 
+`ServiceMonitor` to point to the HTTPS endpoint.
 
 ### Update ServiceMonitor
 
-To update our `ServiceMonitor` we will again patch the resource:
+To update the `ServiceMonitor`, run the following command to 
+patch the resource again:
 
 ``` shell
-$ kubectl patch servicemonitors mongodb-sm --type='json' \
+kubectl patch servicemonitors mongodb-sm --type='json' \
     -p='
 [
     {"op": "replace", "path": "/spec/endpoints/0/scheme", "value": "https"},
     {"op": "add",     "path": "/spec/endpoints/0/tlsConfig", "value": {"insecureSkipVerify": true}}
 ]
 ' \
     --namespace mongodb
+```
 
+The following reponse appears:
+
+``` shell
 servicemonitor.monitoring.coreos.com/mongodb-sm patched
 ```
 
-With these changes, the new `ServiceMonitor` will be pointing at the HTTPS
-endpoint (defined in `/spec/endpoints/0/scheme`). We are also setting
-`spec/endpoints/0/tlsConfig/insecureSkipVerify` to `true`, which will make
-Prometheus to not verify TLS certificates on MongoDB's end.
+With these changes, the new `ServiceMonitor` points to the HTTPS
+endpoint (defined in `/spec/endpoints/0/scheme`). You also 
+set `spec/endpoints/0/tlsConfig/insecureSkipVerify` to `true`, 
+so that Prometheus doesn't verify the TLS certificates on 
+MongoDB's end.
 
-Prometheus should now be able to scrape the MongoDB's target using HTTPS this
-time.
+Prometheus should now be able to scrape the MongoDB target 
+using HTTPS.
