From 8aa5c68c38ced1aa8db46f582e1033451450d779 Mon Sep 17 00:00:00 2001 From: Bartek Grzybowski Date: Mon, 21 Jun 2021 16:04:38 +0200 Subject: [DOC] Add documentation for kube-prometheus stack Change-Id: I8439792c2901171d4063a564b44db0717ed7e8e0 Issue-ID: INT-1926 Signed-off-by: Bartek Grzybowski --- docs/BuildGuide.rst | 6 ++-- docs/InstallGuide.rst | 70 +++++++++++++++++++++++++++++++++++++ docs/images/grafana-dashboards.png | Bin 0 -> 84655 bytes docs/images/grafana-signin.png | Bin 0 -> 139666 bytes 4 files changed, 74 insertions(+), 2 deletions(-) create mode 100644 docs/images/grafana-dashboards.png create mode 100644 docs/images/grafana-signin.png (limited to 'docs') diff --git a/docs/BuildGuide.rst b/docs/BuildGuide.rst index ae5a792a..6c6463ae 100644 --- a/docs/BuildGuide.rst +++ b/docs/BuildGuide.rst @@ -130,12 +130,14 @@ Download all required binaries and docker images. Run download.py twice (as show # all data lists are taken from ./build/data_lists/ folder by default # all resources will be stored in expected folder structure within "../resources" folder ./build/download/download.py --docker ./build/data_lists/infra_docker_images.list ../resources/offline_data/docker_images_infra \ - --http ./build/data_lists/infra_bin_utils.list ../resources/downloads + --http ./build/data_lists/infra_bin_utils.list ../resources/downloads \ + --http ./build/data_lists/kube_prometheus_stack_http.list ../resources/downloads # second argument for --docker is not present, images are just pulled and cached ./build/download/download.py --docker ./build/data_lists/rke_docker_images.list \ --docker ./build/data_lists/k8s_docker_images.list \ - --docker ./build/data_lists/onap_docker_images.list + --docker ./build/data_lists/onap_docker_images.list \ + --docker ./build/data_lists/kube_prometheus_stack_docker_images.list diff --git a/docs/InstallGuide.rst b/docs/InstallGuide.rst index 61c52cc2..32d8ef04 100644 --- a/docs/InstallGuide.rst +++ b/docs/InstallGuide.rst @@ -601,6 +601,72 @@ For additional information concerning the Kubernetes Dashboard please refer to t ----- +Appendix 3. Running kube-prometheus stack +----------------------------------------- + +`Kube-prometheus stack`_ is a collection of Kubernetes manifests, Grafana dashboards, and Prometheus rules combined with documentation and scripts to provide easy to operate end-to-end Kubernetes cluster monitoring with Prometheus using the `Prometheus Operator`_. + +The Stack is not deployed by default in Offline ONAP Platform, but all artifacts which it requires are downloaded by relevant scripts in the package build phase (see `Build Guide`_). + +Setup (optional) +~~~~~~~~~~~~~~~~ + +Kube-prometheus stack itself is a Kubernetes native application provisioned using Helm Charts. As such it can be configured using Helm values. Offline Installer provides a handy way for passing those values to the helm installation process. + +Any values for the Stack should be defined as subkeys of **kube_prometheus_helm_values** variable in **application_configuration.yml**. For instance, in order to override the default Grafana password, insert below structure into application_configuration.yml:: + + kube_prometheus_helm_values: + grafana: + adminPassword: + +Another example - to set custom storage size for Prometheus tsdb:: + + + kube_prometheus_helm_values: + prometheus: + prometheusSpec: + storageSpec: + volumeClaimTemplate: + spec: + resources: + requests: + storage: 6Gi + +A comprehensive list of Helm values for the Stack can be obtained on the `Kube-prometheus stack`_ project site, in the `values.yaml`_ file. Additional values for the Grafana can be checked on the `Grafana`_ project site in the *charts/grafana/values.yaml* file. + +Installation +~~~~~~~~~~~~ + +In order to actually install this tool it's required to set the following variable in application_configuration.yml:: + + kube_prometheus_stack_enabled: true + +After the Offline Platform installation process is complete, the Stack will be deployed into its own kubernetes and helm namespace **kube-prometheus**. + +Accessing Grafana dashboard +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The most straightforward way to access the Grafana UI is by leveraging the *port-forward* k8s facility. Issue following command on the Infra host:: + + kubectl -n kube-prometheus port-forward --address 0.0.0.0 svc/kube-prometheus-stack-grafana 8081:80 + +Then navigate to http://:8081 to access the UI: + +.. image:: images/grafana-signin.png + :alt: Grafana Login page + +Default username is *admin* and the default password is *prom-operator*. + +In the left pane navigate to *Dashboards -> Manage* to see the various pre-defined dashboards that come bundled with kube-prometheus stack. There is also the *Custom* folder which holds few additional dashes defined by the Offline Installer authors: + +.. image:: images/grafana-dashboards.png + :alt: Grafana dashboards + +Caveats +~~~~~~~ + +Kube-prometheus stack bundled with Offline Installer requires at least release v3 of Helm. If you wish to deploy the Stack you need to set relevant v3 release of Helm. Please see **Part 2. Configuration** for details. + .. _Build Guide: ./BuildGuide.rst .. _Software requirements: https://docs.onap.org/projects/onap-oom/en/latest/oom_cloud_setup_guide.html#software-requirements .. _Hardware requirements: https://docs.onap.org/projects/onap-oom/en/latest/oom_cloud_setup_guide.html#minimum-hardware-configuration @@ -608,3 +674,7 @@ For additional information concerning the Kubernetes Dashboard please refer to t .. _Offline installer: https://gerrit.onap.org/r/q/oom/offline-installer .. _RKE: https://rancher.com/products/rke/ .. _Helm: https://helm.sh/ +.. _Kube-prometheus stack: https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack +.. _Prometheus Operator: https://github.com/prometheus-operator/prometheus-operator +.. _values.yaml: https://github.com/prometheus-community/helm-charts/blob/main/charts/kube-prometheus-stack/values.yaml +.. _Grafana: https://github.com/grafana/helm-charts diff --git a/docs/images/grafana-dashboards.png b/docs/images/grafana-dashboards.png new file mode 100644 index 00000000..9cedeabb Binary files /dev/null and b/docs/images/grafana-dashboards.png differ diff --git a/docs/images/grafana-signin.png b/docs/images/grafana-signin.png new file mode 100644 index 00000000..73bc28af Binary files /dev/null and b/docs/images/grafana-signin.png differ -- cgit 1.2.3-korg