From 554699a4ae84734247599a88268e4db6db0b20e0 Mon Sep 17 00:00:00 2001 From: Neaj Morshad Date: Fri, 25 Oct 2024 11:23:50 +0600 Subject: [PATCH] Add MSSQLServer Monitoring Doc Signed-off-by: Neaj Morshad --- docs/guides/mssqlserver/monitoring/_index.md | 10 + .../guides/mssqlserver/monitoring/overview.md | 106 +++++++ .../monitoring/using-prometheus-operator.md | 274 ++++++++++++++++++ 3 files changed, 390 insertions(+) create mode 100755 docs/guides/mssqlserver/monitoring/_index.md create mode 100644 docs/guides/mssqlserver/monitoring/overview.md create mode 100644 docs/guides/mssqlserver/monitoring/using-prometheus-operator.md diff --git a/docs/guides/mssqlserver/monitoring/_index.md b/docs/guides/mssqlserver/monitoring/_index.md new file mode 100755 index 0000000000..755087d452 --- /dev/null +++ b/docs/guides/mssqlserver/monitoring/_index.md @@ -0,0 +1,10 @@ +--- +title: Monitoring MSSQLServer +menu: + docs_{{ .version }}: + identifier: ms-monitoring-mssqlserver + name: Monitoring + parent: ms-mssqlserver-guides + weight: 40 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/mssqlserver/monitoring/overview.md b/docs/guides/mssqlserver/monitoring/overview.md new file mode 100644 index 0000000000..4ba46e11af --- /dev/null +++ b/docs/guides/mssqlserver/monitoring/overview.md @@ -0,0 +1,106 @@ +--- +title: MSSQLServer Monitoring Overview +description: MSSQLServer Monitoring Overview +menu: + docs_{{ .version }}: + identifier: ms-monitoring-overview + name: Overview + parent: ms-monitoring-mssqlserver + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Monitoring MSSQLServer with KubeDB + +KubeDB has native support for monitoring via [Prometheus](https://prometheus.io/). You can use builtin [Prometheus](https://github.com/prometheus/prometheus) scraper or [Prometheus operator](https://github.com/prometheus-operator/prometheus-operator) to monitor KubeDB managed databases. This tutorial will show you how database monitoring works with KubeDB and how to configure Database crd to enable monitoring. + +## Overview + +KubeDB uses Prometheus [exporter](https://prometheus.io/docs/instrumenting/exporters/#databases) images to export Prometheus metrics for respective databases. Following diagram shows the logical flow of database monitoring with KubeDB. + +

+  Database Monitoring Flow +

+ +When a user creates a database crd with `spec.monitor` section configured, KubeDB operator provisions the respective database and injects an exporter image as sidecar to the database pod. It also creates a dedicated stats service with name `{database-crd-name}-stats` for monitoring. Prometheus server can scrape metrics using this stats service. + +## Configure Monitoring + +In order to enable monitoring for a database, you have to configure `spec.monitor` section. KubeDB provides following options to configure `spec.monitor` section: + +| Field | Type | Uses | +| -------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `spec.monitor.agent` | `Required` | Type of the monitoring agent that will be used to monitor this database. It can be `prometheus.io/builtin` or `prometheus.io/operator`. | +| `spec.monitor.prometheus.exporter.port` | `Optional` | Port number where the exporter side car will serve metrics. | +| `spec.monitor.prometheus.exporter.args` | `Optional` | Arguments to pass to the exporter sidecar. | +| `spec.monitor.prometheus.exporter.env` | `Optional` | List of environment variables to set in the exporter sidecar container. | +| `spec.monitor.prometheus.exporter.resources` | `Optional` | Resources required by exporter sidecar container. | +| `spec.monitor.prometheus.exporter.securityContext` | `Optional` | Security options the exporter should run with. | +| `spec.monitor.prometheus.serviceMonitor.labels` | `Optional` | Labels for `ServiceMonitor` crd. | +| `spec.monitor.prometheus.serviceMonitor.interval` | `Optional` | Interval at which metrics should be scraped. | + +## Sample Configuration + +A sample YAML for Redis crd with `spec.monitor` section configured to enable monitoring with [Prometheus operator](https://github.com/prometheus-operator/prometheus-operator) is shown below. + +```yaml +apiVersion: kubedb.com/v1 +kind: Redis +metadata: + name: sample-redis + namespace: databases +spec: + version: 6.0.20 + deletionPolicy: WipeOut + configSecret: # configure Redis to use password for authentication + name: redis-config + storageType: Durable + storage: + storageClassName: default + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 5Gi + monitor: + agent: prometheus.io/operator + prometheus: + serviceMonitor: + labels: + release: prometheus + exporter: + args: + - --redis.password=$(REDIS_PASSWORD) + env: + - name: REDIS_PASSWORD + valueFrom: + secretKeyRef: + name: _name_of_secret_with_redis_password + key: password # key with the password + resources: + requests: + memory: 512Mi + cpu: 200m + limits: + memory: 512Mi + cpu: 250m + securityContext: + runAsUser: 2000 + allowPrivilegeEscalation: false +``` + +Assume that above Redis is configured to use basic authentication. So, exporter image also need to provide password to collect metrics. We have provided it through `spec.monitor.args` field. + +Here, we have specified that we are going to monitor this server using Prometheus operator through `spec.monitor.agent: prometheus.io/operator`. KubeDB will create a `ServiceMonitor` crd in `monitoring` namespace and this `ServiceMonitor` will have `release: prometheus` label. + +## Next Steps + +- Learn how to monitor Elasticsearch database with KubeDB using [builtin-Prometheus](/docs/guides/elasticsearch/monitoring/using-builtin-prometheus.md) and using [Prometheus operator](/docs/guides/elasticsearch/monitoring/using-prometheus-operator.md). +- Learn how to monitor MSSQLServer database with KubeDB using [builtin-Prometheus](/docs/guides/mssqlserver/monitoring/using-builtin-prometheus.md) and using [Prometheus operator](/docs/guides/mssqlserver/monitoring/using-prometheus-operator.md). +- Learn how to monitor MySQL database with KubeDB using [builtin-Prometheus](/docs/guides/mysql/monitoring/builtin-prometheus/index.md) and using [Prometheus operator](/docs/guides/mysql/monitoring/prometheus-operator/index.md). +- Learn how to monitor MongoDB database with KubeDB using [builtin-Prometheus](/docs/guides/mongodb/monitoring/using-builtin-prometheus.md) and using [Prometheus operator](/docs/guides/mongodb/monitoring/using-prometheus-operator.md). +- Learn how to monitor Redis server with KubeDB using [builtin-Prometheus](/docs/guides/redis/monitoring/using-builtin-prometheus.md) and using [Prometheus operator](/docs/guides/redis/monitoring/using-prometheus-operator.md). +- Learn how to monitor Memcached server with KubeDB using [builtin-Prometheus](/docs/guides/memcached/monitoring/using-builtin-prometheus.md) and using [Prometheus operator](/docs/guides/memcached/monitoring/using-prometheus-operator.md). diff --git a/docs/guides/mssqlserver/monitoring/using-prometheus-operator.md b/docs/guides/mssqlserver/monitoring/using-prometheus-operator.md new file mode 100644 index 0000000000..5b5eaeae64 --- /dev/null +++ b/docs/guides/mssqlserver/monitoring/using-prometheus-operator.md @@ -0,0 +1,274 @@ +--- +title: Monitor MSSQLServer using Prometheus Operator +menu: + docs_{{ .version }}: + identifier: ms-using-prometheus-operator-monitoring + name: Prometheus Operator + parent: ms-monitoring-mssqlserver + weight: 15 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Monitoring MSSQLServer Using Prometheus operator + +[Prometheus operator](https://github.com/prometheus-operator/prometheus-operator) provides simple and Kubernetes native way to deploy and configure Prometheus server. This tutorial will show you how to use Prometheus operator to monitor MSSQLServer database deployed with KubeDB. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- To learn how Prometheus monitoring works with KubeDB in general, please visit [here](/docs/guides/mssqlserver/monitoring/overview.md). + +- To keep Prometheus resources isolated, we are going to use a separate namespace called `monitoring` to deploy respective monitoring resources. We are going to deploy database in `demo` namespace. + + ```bash + $ kubectl create ns monitoring + namespace/monitoring created + + $ kubectl create ns demo + namespace/demo created + ``` + +- We need a [Prometheus operator](https://github.com/prometheus-operator/prometheus-operator) instance running. If you don't already have a running instance, deploy one following the docs from [here](https://github.com/appscode/third-party-tools/blob/master/monitoring/prometheus/operator/README.md). + +- If you already don't have a Prometheus server running, deploy one following tutorial from [here](https://github.com/appscode/third-party-tools/blob/master/monitoring/prometheus/operator/README.md#deploy-prometheus-server). + +> Note: YAML files used in this tutorial are stored in [docs/examples/mssqlserver](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/mssqlserver) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Find out required labels for ServiceMonitor + +We need to know the labels used to select `ServiceMonitor` by a `Prometheus` crd. We are going to provide these labels in `spec.monitor.prometheus.labels` field of MSSQLServer crd so that KubeDB creates `ServiceMonitor` object accordingly. + +At first, let's find out the available Prometheus server in our cluster. + +```bash +$ kubectl get prometheus --all-namespaces +NAMESPACE NAME AGE +monitoring prometheus 18m +``` + +> If you don't have any Prometheus server running in your cluster, deploy one following the guide specified in **Before You Begin** section. + +Now, let's view the YAML of the available Prometheus server `prometheus` in `monitoring` namespace. + +```yaml +$ kubectl get prometheus -n monitoring prometheus -o yaml +apiVersion: monitoring.coreos.com/v1 +kind: Prometheus +metadata: + annotations: + kubectl.kubernetes.io/last-applied-configuration: | + {"apiVersion":"monitoring.coreos.com/v1","kind":"Prometheus","metadata":{"annotations":{},"labels":{"prometheus":"prometheus"},"name":"prometheus","namespace":"monitoring"},"spec":{"replicas":1,"resources":{"requests":{"memory":"400Mi"}},"serviceAccountName":"prometheus","serviceMonitorSelector":{"matchLabels":{"release":"prometheus"}}}} + creationTimestamp: 2019-01-03T13:41:51Z + generation: 1 + labels: + prometheus: prometheus + name: prometheus + namespace: monitoring + resourceVersion: "44402" + selfLink: /apis/monitoring.coreos.com/v1/namespaces/monitoring/prometheuses/prometheus + uid: 5324ad98-0f5d-11e9-b230-080027f306f3 +spec: + replicas: 1 + resources: + requests: + memory: 400Mi + serviceAccountName: prometheus + serviceMonitorSelector: + matchLabels: + release: prometheus +``` + +Notice the `spec.serviceMonitorSelector` section. Here, `release: prometheus` label is used to select `ServiceMonitor` crd. So, we are going to use this label in `spec.monitor.prometheus.labels` field of MSSQLServer crd. + +## Deploy MSSQLServer with Monitoring Enabled + +At first, let's deploy an MSSQLServer database with monitoring enabled. Below is the MSSQLServer object that we are going to create. + +```yaml +apiVersion: kubedb.com/v1 +kind: MSSQLServer +metadata: + name: coreos-prom-mssqlserver + namespace: demo +spec: + version: "13.13" + deletionPolicy: WipeOut + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + monitor: + agent: prometheus.io/operator + prometheus: + serviceMonitor: + labels: + release: prometheus + interval: 10s +``` + +Here, + +- `monitor.agent: prometheus.io/operator` indicates that we are going to monitor this server using Prometheus operator. +- `monitor.prometheus.namespace: monitoring` specifies that KubeDB should create `ServiceMonitor` in `monitoring` namespace. + +- `monitor.prometheus.labels` specifies that KubeDB should create `ServiceMonitor` with these labels. + +- `monitor.prometheus.interval` indicates that the Prometheus server should scrape metrics from this database with 10 seconds interval. + +Let's create the MSSQLServer object that we have shown above, + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/mssqlserver/monitoring/coreos-prom-mssqlserver.yaml +mssqlserverql.kubedb.com/coreos-prom-mssqlserver created +``` + +Now, wait for the database to go into `Running` state. + +```bash +$ kubectl get ms -n demo coreos-prom-mssqlserver +NAME VERSION STATUS AGE +coreos-prom-mssqlserver 10.2-v5 Running 38s +``` + +KubeDB will create a separate stats service with name `{MSSQLServer crd name}-stats` for monitoring purpose. + +```bash +$ kubectl get svc -n demo --selector="app.kubernetes.io/instance=coreos-prom-mssqlserver" +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +coreos-prom-mssqlserver ClusterIP 10.107.102.123 5432/TCP 58s +coreos-prom-mssqlserver-replicas ClusterIP 10.109.11.171 5432/TCP 58s +coreos-prom-mssqlserver-stats ClusterIP 10.110.218.172 56790/TCP 51s +``` + +Here, `coreos-prom-mssqlserver-stats` service has been created for monitoring purpose. + +Let's describe this stats service. + +```yaml +$ kubectl describe svc -n demo coreos-prom-mssqlserver-stats +Name: coreos-prom-mssqlserver-stats +Namespace: demo +Labels: app.kubernetes.io/name=mssqlserveres.kubedb.com + app.kubernetes.io/instance=coreos-prom-mssqlserver +Annotations: monitoring.appscode.com/agent: prometheus.io/operator +Selector: app.kubernetes.io/name=mssqlserveres.kubedb.com,app.kubernetes.io/instance=coreos-prom-mssqlserver +Type: ClusterIP +IP: 10.110.218.172 +Port: prom-http 56790/TCP +TargetPort: prom-http/TCP +Endpoints: 172.17.0.7:56790 +Session Affinity: None +Events: +``` + +Notice the `Labels` and `Port` fields. `ServiceMonitor` will use these information to target its endpoints. + +KubeDB will also create a `ServiceMonitor` crd in `monitoring` namespace that select the endpoints of `coreos-prom-mssqlserver-stats` service. Verify that the `ServiceMonitor` crd has been created. + +```bash +$ kubectl get servicemonitor -n monitoring +NAME AGE +kubedb-demo-coreos-prom-mssqlserver 1m +``` + +Let's verify that the `ServiceMonitor` has the label that we had specified in `spec.monitor` section of MSSQLServer crd. + +```yaml +$ kubectl get servicemonitor -n monitoring kubedb-demo-coreos-prom-mssqlserver -o yaml +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + creationTimestamp: 2019-01-03T15:47:08Z + generation: 1 + labels: + release: prometheus + monitoring.appscode.com/service: coreos-prom-mssqlserver-stats.demo + name: kubedb-demo-coreos-prom-mssqlserver + namespace: monitoring + resourceVersion: "53969" + selfLink: /apis/monitoring.coreos.com/v1/namespaces/monitoring/servicemonitors/kubedb-demo-coreos-prom-mssqlserver + uid: d3c419ad-0f6e-11e9-b230-080027f306f3 +spec: + endpoints: + - honorLabels: true + interval: 10s + path: /metrics + port: prom-http + namespaceSelector: + matchNames: + - demo + selector: + matchLabels: + app.kubernetes.io/name: mssqlserveres.kubedb.com + app.kubernetes.io/instance: coreos-prom-mssqlserver +``` + +Notice that the `ServiceMonitor` has label `release: prometheus` that we had specified in MSSQLServer crd. + +Also notice that the `ServiceMonitor` has selector which match the labels we have seen in the `coreos-prom-mssqlserver-stats` service. It also, target the `prom-http` port that we have seen in the stats service. + +## Verify Monitoring Metrics + +At first, let's find out the respective Prometheus pod for `prometheus` Prometheus server. + +```bash +$ kubectl get pod -n monitoring -l=app=prometheus +NAME READY STATUS RESTARTS AGE +prometheus-prometheus-0 3/3 Running 1 63m +``` + +Prometheus server is listening to port `9090` of `prometheus-prometheus-0` pod. We are going to use [port forwarding](https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster/) to access Prometheus dashboard. + +Run following command on a separate terminal to forward the port 9090 of `prometheus-prometheus-0` pod, + +```bash +$ kubectl port-forward -n monitoring prometheus-prometheus-0 9090 +Forwarding from 127.0.0.1:9090 -> 9090 +Forwarding from [::1]:9090 -> 9090 +``` + +Now, we can access the dashboard at `localhost:9090`. Open [http://localhost:9090](http://localhost:9090) in your browser. You should see `prom-http` endpoint of `coreos-prom-mssqlserver-stats` service as one of the targets. + +

+  Prometheus Target +

+ +Check the `endpoint` and `service` labels marked by red rectangle. It verifies that the target is our expected database. Now, you can view the collected metrics and create a graph from homepage of this Prometheus dashboard. You can also use this Prometheus server as data source for [Grafana](https://grafana.com/) and create beautiful dashboard with collected metrics. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run following commands + +```bash +# cleanup database +kubectl delete -n demo ms/coreos-prom-mssqlserver + +# cleanup prometheus resources +kubectl delete -n monitoring prometheus prometheus +kubectl delete -n monitoring clusterrolebinding prometheus +kubectl delete -n monitoring clusterrole prometheus +kubectl delete -n monitoring serviceaccount prometheus +kubectl delete -n monitoring service prometheus-operated + +# cleanup prometheus operator resources +kubectl delete -n monitoring deployment prometheus-operator +kubectl delete -n dmeo serviceaccount prometheus-operator +kubectl delete clusterrolebinding prometheus-operator +kubectl delete clusterrole prometheus-operator + +# delete namespace +kubectl delete ns monitoring +kubectl delete ns demo +``` + +## Next Steps + +- Monitor your MSSQLServer database with KubeDB using [built-in Prometheus](/docs/guides/mssqlserver/monitoring/using-builtin-prometheus.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md).