installers/k8s/README-osm_k8s_monitoring.md

   1 <!--
   2 Copyright 2019 Minsait - Indra S.A.
   3
   4 Licensed under the Apache License, Version 2.0 (the "License");
   5 you may not use this file except in compliance with the License.
   6 You may obtain a copy of the License at
   7
   8     http://www.apache.org/licenses/LICENSE-2.0
   9
  10 Unless required by applicable law or agreed to in writing, software
  11 distributed under the License is distributed on an "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 See the License for the specific language governing permissions and
  14 limitations under the License.
  15 Author: Jose Manuel Palacios (jmpalacios@minsait.com)
  16 Author: Jose Antonio Martinez (jamartinezv@minsait.com)
  17 -->
  18
  19 # Monitoring in Kubernetes based OSM
  20
  21 ## Introduction
  22
  23 This implementation deploys a PM stack based on Prometheus Operator plus a series of exporters for monitoring the OSM nodes and third party software modules (Kafka, mongodb and mysql)
  24
  25 In a high level, it consists of two scripts that deploy/undeploy the required objects in a previously existing Kubernetes based OSM installation.
  26 Those scripts use already existing and freely available software: Helm, Kubernetes Operator and a set of exporters and dashboards pretty much standard. Helm server part (tiller) and charts deployed depends on Kubernetes version 1.15.x. Charts versions are pre-configured in an installation script and can be easily changed.
  27
  28 As a result, there will be 3 folders in Grafana:
  29
  30 - Summary: with a quick view of the platform global status.
  31 - OSM Third Party Modules: dashboards for MongoDB, MyslqDB and Kafka.
  32 - Kubernetes cluster: dashboards for pods, namespaces, nodes, etc.
  33
  34 ## Requirements
  35
  36 - Kubernetes 1.15.X
  37 - OSM Kubernetes version Release 7
  38
  39 ## Components
  40
  41 - Installs the helm client on the host where the script is run (if not already installed)
  42 - Creates a service account in the k8s cluster to be used by tiller, with sufficient permissions to be able to deploy kubernetes objects.
  43 - Installs the helm server part (tiller) and assigns to tiller the previously created service account (if not already installed)
  44 - Creates a namespace (monitoring) where all the components that are part of the OSM deployment monitoring `pack` will be installed.
  45 - Installs prometheus-operator using the `stable/prometheus-operator` chart which is located at the default helm repository (<https://kubernetes-charts.storage.googleapis.com/>). This installs a set of basic metrics for CPU, memory, etc. of hosts and pods. It also includes grafana and dashboards.
  46 - Installs an exporter for mongodb using the `stable/prometheus-mongodb-exporter` chart, which is located at the default  helm repository (<https://kubernetes-charts.storage.googleapis.com/>).
  47 - Adds a dashboard for mongodb to grafana through a local yaml file.
  48 - Installs an exporter for mysql using the `stable/prometheus-mysql-exporter` chart which is located at the default helm repository (<https://kubernetes-charts.storage.googleapis.com/>).
  49 - Adds a dashboard for mysql to grafana through a local yaml file.
  50 - Installs an exporter for kafka using a custom-build helm chart with a deployment and its corresponding service and service monitor with local yaml files. We take the kafka exporter from <https://hub.docker.com/r/danielqsj/kafka-exporter>.
  51 - Add a dashboard for kafka to grafana through a local yaml file.
  52
  53 ## Versions
  54
  55 We use the following versions:
  56
  57 - PROMETHEUS_OPERATOR=6.18.0
  58 - PROMETHEUS_MONGODB_EXPORTER=2.3.0
  59 - PROMETHEUS_MYSQL_EXPORTER=0.5.1
  60 - HELM_CLIENT=2.15.2
  61
  62 ## Install
  63
  64 Note: This implementation is dependent on the Kubernetes OSM deployment, and the installation script must be executed AFTER the Kubernetes deployment has been completed. Notice that it is not applicable to the basic docker deployment.
  65
  66 ```bash
  67 usage: ./install_osm_k8s_monitoring.sh [OPTIONS]
  68 Install OSM Monitoring
  69   OPTIONS
  70      -n <namespace>   :   use specified kubernetes namespace - default: monitoring
  71      -s <service_type>:   service type (ClusterIP|NodePort|LoadBalancer) - default: NodePort
  72      --debug          :   debug script
  73      --dump           :   dump arguments and versions
  74      -h / --help      :   print this help
  75 ```
  76
  77 ## Uninstall
  78
  79 To uninstall the utility you must use the installation script.
  80
  81 ```sh
  82 ./uninstall_osm_k8s_monitoring.sh
  83 ```
  84
  85 It will uninstall all components of this utility. To see the options type --help.
  86
  87 ```sh
  88 usage: ./uninstall_osm_k8s_monitoring.sh [OPTIONS]
  89 Uninstall OSM Monitoring
  90   OPTIONS
  91      -n <namespace>:   use specified kubernetes namespace - default: monitoring
  92      --helm        :   uninstall tiller
  93      --debug       :   debug script
  94      -h / --help   :   print this help
  95 ```
  96
  97 ## Access to Grafana Web Monitoring
  98
  99 To view the WEB with the different dashboards it is necessary to connect to the service "grafana" installed with this utility
 100 and view the NodePort that uses. If the utility is installed with the default namespace "monitoring" you must type this:
 101
 102 ```sh
 103 kubectl get all --namespace monitoring
 104 ```
 105
 106 You must see the NodePort (greater than 30000) that uses the grafana service and type in your WEB browser:
 107
 108 ```sh
 109   http://<ip_your_osm_host>:<nodeport>
 110 ```
 111
 112 - Username: admin
 113 - Password: prom-operator