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 # OSM Monitoring
  20
  21 ## Introduction
  22
  23 This is an utility to monitor the OSM nodes and pods in the Kubernetes deployment. Metrics are stored in Prometheus and accessible in Grafana. Note that those "Prometheus" instance is not the same in the OSM core, but different one, aimed at the monitoring of the platform itself.
  24
  25 ## Requirements
  26
  27 OSM must be/have been deployed using the Kubernetes installer (that is, with the -c k8s option).
  28
  29 ## Versions
  30
  31 For reference, the versions for the external components used are as follows:
  32
  33 * PROMETHEUS_OPERATOR=6.18.0
  34 * PROMETHEUS_MONGODB_EXPORTER=2.3.0
  35 * PROMETHEUS_MYSQL_EXPORTER=0.5.1
  36 * HELM_CLIENT=2.15.2
  37
  38 ## Functionality
  39
  40 Kubernetes cluster metrics (for nodes, pods, deployments, etc.) are stored in the dedicated Prometheus instance and accessible using Grafana.
  41
  42 "Prometheus-operator" (<https://github.com/helm/charts/tree/master/stable/prometheus-operator>) provides the basic components and the monitoring of the basic Kubernetes resources. Additional "exporters" are used to gather metrics from Kafka, Mysql and Mongodb.
  43 It is important to note that Grafana is not installed with this chart because we are using Grafana installed with OSM core.
  44
  45 ## Install procedure
  46
  47 There are two ways to install the monitoring component based on the OSM global installer (<https://osm-download.etsi.org/ftp/osm-8.0-eight/install_osm.sh>)
  48
  49 * Using the --k8s_monitor switch in the OSM installation:
  50
  51 ```bash
  52 ./install_osm.sh -c k8s --k8s_monitor
  53 ```
  54
  55 * As a separated component (K8s based OSM only):
  56
  57 ```bash
  58 ./install_osm.sh -o k8s_monitor
  59 ```
  60
  61 All the components will be installed in the "monitoring" namespace. In addition, for debugging purposes, there is a standalone script is available in `devops/installers/k8s/install_osm_k8s_monitoring.sh`. To see the available options, type --help.
  62
  63 ```sh
  64 usage: ./install_osm_k8s_monitoring.sh [OPTIONS]
  65 Install OSM Monitoring
  66   OPTIONS
  67      -n <namespace>   :   use specified kubernetes namespace - default: monitoring
  68      -s <service_type>:   service type (ClusterIP|NodePort|LoadBalancer) - default: NodePort
  69      --debug          :   debug script
  70      --dump           :   dump arguments and versions
  71      -h / --help      :   print this help
  72 ```
  73
  74 ## Access to Grafana
  75
  76 The Grafana console can be accessed on the IP address of any node using port 3000, since a NodePort service is used: `http://<ip_your_osm_host>:3000`
  77
  78 The initial credentials are:
  79
  80 * Username: admin
  81 * Password: admin
  82
  83 ## Uninstall procedure
  84
  85 Use the uninstall script
  86
  87 ```sh
  88 ./install_osm.sh -o k8s_monitor --uninstall
  89 ```
  90
  91 In addition, for debugging purposes, there is a standalone script is available in `devops/installers/k8s/uninstall_osm_k8s_monitoring.sh`. To see the available options type --help.
  92
  93 ```bash
  94 usage: ./uninstall_osm_k8s_monitoring.sh [OPTIONS]
  95 Uninstall OSM Monitoring
  96   OPTIONS
  97      -n <namespace>:   use specified kubernetes namespace - default: monitoring
  98      --helm        :   uninstall tiller
  99      --debug       :   debug script
 100      -h / --help   :   print this help
 101 ```
 102
 103 ## Grafana Dashboards
 104
 105 Dashboard are organized in two folders:
 106
 107 * The folder "Kubernetes cluster" contains the dashboards available upstream as part of the standard prometheus operator helm installation:
 108
 109   * Kubernetes components (api server, kubelet, pods, etc)
 110   * Nodes of the cluster.
 111   * Prometheus operator components.
 112
 113 * The folder "Open Source MANO" contains additional dashboards customized for OSM:
 114   * Summary with a quick view of the overall status.
 115   * Host information
 116   * Third party components: Kafka, MongoDB, MySQL.
 117
 118 ## Adding new dashboards
 119
 120 New dashboards for OSM components should be included in "Open Source MANO" folder. Once we have the dashboard json file, please follow the instructions below to incorporate it into Grafana.
 121
 122 ```bash
 123 kubectl -n monitoring create configmap <configmap-name> --from-file=<dashboard-json-file>
 124 kubectl -n monitoring patch configmap <configmap-name> --patch '{"metadata": {"labels": {"grafana_dashboard": "1"},{"annotations": {k8s-sidecar-target-directory: "/tmp/dashboards/Open Source MANO"}}}}'
 125 ```
 126 where <configmap-name> and <dashboard-json-file> needs to be replaced with desired values. A proposal is that <configmap-name> begins with "osm-monitoring-osm-"
 127
 128 Once configmap is created and patched, we can download the manifest file for future use with next command:
 129 ```
 130 kubectl -n monitoring get configmap <configmap-name> -o yaml > <confimap-file>
 131 ```
 132
 133 Grafana Sidecar will read the label `grafana_dashboard: "1"` in the configmap and upload the dashboard information to Grafana.
 134
 135 The current dashboards can also be updated. It is only needed to modify/update the required yaml file available in `devops/installers/k8s` and apply them via kubectl. As an example `kubectl -n monitoring apply -f summary-dashboard.yaml` will update the changes made in the summary dashboard.