Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Add MSSQLServer Monitoring Doc #707

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Add MSSQLServer Monitoring Doc #707

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/guides/mssqlserver/monitoring/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 }}
---
106 changes: 106 additions & 0 deletions docs/guides/mssqlserver/monitoring/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<p align="center">
  <img alt="Database Monitoring Flow" src="/docs/images/concepts/monitoring/database-monitoring-overview.svg">
</p>

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).
274 changes: 274 additions & 0 deletions docs/guides/mssqlserver/monitoring/using-prometheus-operator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <none> 5432/TCP 58s
coreos-prom-mssqlserver-replicas ClusterIP 10.109.11.171 <none> 5432/TCP 58s
coreos-prom-mssqlserver-stats ClusterIP 10.110.218.172 <none> 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: <none>
```

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.

<p align="center">
  <img alt="Prometheus Target" src="/docs/images/mssqlserver/monitoring/ms-coreos-prom-target.png" style="padding:10px">
</p>

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).
Loading