|author||Thomas Draebing <email@example.com>||Thu Mar 05 16:45:51 2020 +0100|
|committer||Thomas Draebing <firstname.lastname@example.org>||Thu Apr 16 14:25:53 2020 +0200|
Create CA-certificate file for promtail during installation For TLS-verification promtail requires a CA-certificate, which had to be created manually. Change-Id: Ia1fe191bad7f3d1ca4a1568921ad67d22c47efd7
This project provides a setup for monitoring Gerrit instances. The setup is based on Prometheus and Grafana running in Kubernetes. In addition, logging will be provided by Grafana Loki.
The setup is provided as a helm chart. It can be installed using Helm (This README expects Helm version 3.0 or higher).
The charts used in this setup are the chart provided in the open source and can be found on GitHub:
This project just provides
values.yaml-files that are already configured to work with the
metrics-reporter-prometheus-plugin of Gerrit to make the setup easier.
Gerrit requires the following plugin to be installed:
Promtail has to be installed with access to the
logs-directory in the Gerrit- site. A configuration-file for Promtail will be provided in this setup. Find the documentation for Promtail here
To install and configure Helm, follow the official guide.
ytt is a templating tool for yaml-files. It is required for some last moment configuration. Installation instructions can be found here.
Pipenv sets up a virtual python environment and installs required python packages based on a lock-file, ensuring a deterministic Python environment. Instruction on how Pipenv can be installed, can be found here
A cluster with at least 3 free CPUs and 4 GB of free memory are required. In addition persistent storage of about 30 GB will be used.
The charts currently expect a Nginx ingress controller to be installed in the cluster.
Loki will store the data chunks in an object store. This store has to be callable via the S3 API.
To have dashboards deployed automatically during installation, export the dashboards to a JSON-file or create JSON-files describing the dashboards in another way. Put these dashboards into the
./dashboards-directory of this repository. During the installation the dashboards will be added to a configmap and with this automatically installed to Grafana.
While this project is supposed to provide a specialized and opinionated monitoring setup, some configuration is highly dependent on the specific installation. These options have to be configured in the
./config.yaml before installing and are listed here:
|Hostname (incl. port, if required) of the Gerrit server to monitor|
|Username of Gerrit user with ‘View Metrics’ capabilities|
|Password of Gerrit user with ‘View Metrics’ capabilities|
|Path to directory, where Promtail is allowed to save files (e.g. |
|Path to directory containing the Gerrit logs (e.g. |
|The namespace the charts are installed to|
|Whether to skip TLS certificate verification|
|CA certificate used for TLS certificate verification|
|Prometheus server ingress hostname|
|Username for Prometheus|
|Password for Prometheus|
|API URL of the Slack Webhook|
|Channel to which the alerts should be posted|
|Loki ingress hostname|
|Username for Loki|
|Password for Loki|
|Protocol used for communicating with S3|
|Hostname of the S3 object store|
|The EC2 accessToken used for authentication with S3|
|The secret associated with the accessToken|
|The name of the S3 bucket|
|The region in which the S3 bucket is hosted|
|Grafana ingress hostname|
|Username for the admin user|
|Password for the admin user|
|Whether to enable LDAP|
|Hostname of LDAP server|
|Port of LDAP server (Has to be |
|Password of LDAP server|
|Bind DN (username) of the LDAP server|
|List of base DNs to discover accounts (Has to have the format |
|List of base DNs to discover groups (Has to have the format |
|Whether dashboards can be edited manually in the UI|
The configuration file contains secrets. Thus, to be able to share the configuration, e.g. with the CI-system, it is meant to be encrypted. The encryption is explained here.
gerrit-monitoring.py install-command will decrypt the file before templating, if it was encrypted with
Before using the script, set up a python environment using
The installation will use the environment of the current shell. Thus, make sure that the path for
helm are set. Also the
KUBECONFIG-variable has to be set to point to the kubeconfig of the target Kubernetes cluster.
This project provides a script to quickly install the monitoring setup. To use it, run:
pipenv run python ./gerrit-monitoring.py \ --config config.yaml \ install \ [--output ./dist] \ [--dryrun] \ [--update-repo]
The command will use the given configuration (
-c) to create the final files in the directory given by
./dist) and install/update the Kubernetes resources and charts, if the
-d flag is not set. If the
--update-repo-flag is used, the helm repository will be updated before installing the helm charts. This is for example required, if a chart version was updated.
Promtail has to be installed with access to the directory containing the Gerrit logs, e.g. on the same host. The installation as described above will create a configuration file for Promtail, which can be found in
./dist/promtail.yaml. Use it to configure Promtail by using the
-config.file=./dist/promtail.yaml- parameter, when starting Promtail. Using the Promtail binary directly this would result in the following command:
$PATH_TO_PROMTAIL/promtail \ -config.file=./dist/promtail.yaml
If TLS-verification is activated, the CA-certificate used for verification (usually the one configured for
tls.caCert) has to be present in the directory configured for
promtail.storagePath in the
config.yaml and has to be called
The Promtail configuration provided here expects the logs to be available in JSON-format. This can be configured by setting
log.jsonLogging = true in the
To remove the Prometheus chart from the cluster, run
helm uninstall prometheus --namespace $NAMESPACE helm uninstall loki --namespace $NAMESPACE helm uninstall grafana --namespace $NAMESPACE kubectl delete -f ./dist/configuration
To also release the volumes, run
kubectl delete -f ./dist/storage
NOTE: Doing so, all data, which was not backed up will be lost!
Remove the namespace:
kubectl delete -f ./dist/namespace.yaml
./gerrit-monitoring.py uninstall-script will automatically remove the charts installed in the configured namespace and delete the namespace as well:
pipenv run python ./gerrit-monitoring.py \ --config config.yaml \ uninstall