From e4fef714424a33ed0c812383729c4a1b73b52253 Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Fri, 11 Mar 2022 13:37:19 +0100 Subject: [PATCH] docs: add documentation for prometheus-operator usage (#171) --- .dictionary | 3 + docs/content/configuration/cli.md | 8 +-- docs/content/configuration/defaults.md | 10 +-- docs/content/configuration/env.md | 10 +-- docs/content/setup/docker.md | 10 ++- docs/content/setup/pip.md | 18 ++--- docs/content/setup/prometheus-operator.md | 80 +++++++++++++++++++++++ docs/content/usage/advanced.md | 53 +++++++++++++++ docs/content/usage/getting-started.md | 67 +++++-------------- docs/data/menu/main.yml | 8 ++- prometheuspvesd/exception.py | 2 +- 11 files changed, 179 insertions(+), 90 deletions(-) create mode 100644 docs/content/setup/prometheus-operator.md create mode 100644 docs/content/usage/advanced.md diff --git a/.dictionary b/.dictionary index 8def8e9..27ad7ac 100644 --- a/.dictionary +++ b/.dictionary @@ -19,3 +19,6 @@ VMID Telegraf QEMU cloud-init +Prometheus +Kubernetes +namespace diff --git a/docs/content/configuration/cli.md b/docs/content/configuration/cli.md index a673d1e..a89dc23 100644 --- a/docs/content/configuration/cli.md +++ b/docs/content/configuration/cli.md @@ -4,9 +4,7 @@ title: CLI options You can get all available CLI options by running `prometheus-pve-sd --help`: - - -{{< highlight Shell "linenos=table" >}} +```Shell $ prometheus-pve-sd --help usage: prometheus-pve-sd [-h] [-c CONFIG_FILE] [-o OUTPUT_FILE] [-d LOOP_DELAY] [--no-service] [-f LOG_FORMAT] [-v] [-q] [--version] @@ -26,6 +24,4 @@ optional arguments: -v increase log level -q decrease log level --version show program's version number and exit -{{< /highlight >}} - - +``` diff --git a/docs/content/configuration/defaults.md b/docs/content/configuration/defaults.md index 85cdf81..bfb6d0c 100644 --- a/docs/content/configuration/defaults.md +++ b/docs/content/configuration/defaults.md @@ -2,10 +2,7 @@ title: Default settings --- - - - -{{< highlight YAML "linenos=table" >}} +```Shell --- logging: # supported log levels: debug|info|warning|error|critical @@ -45,7 +42,4 @@ pve: # password: secure # auth_timeout: 5 # verify_ssl: true -{{< /highlight >}} - - - +``` diff --git a/docs/content/configuration/env.md b/docs/content/configuration/env.md index 90817a0..e38152d 100644 --- a/docs/content/configuration/env.md +++ b/docs/content/configuration/env.md @@ -2,10 +2,7 @@ title: Environment Variables --- - - - -{{< highlight Shell "linenos=table" >}} +```Shell PROMETHEUS_PVE_SD_CONFIG_FILE= # supported log levels: debug|info|warning|error|critical @@ -32,7 +29,4 @@ PROMETHEUS_PVE_SD_PVE_USER= PROMETHEUS_PVE_SD_PVE_PASSWORD= PROMETHEUS_PVE_SD_PVE_AUTH_TIMEOUT=5 PROMETHEUS_PVE_SD_PVE_VERIFY_SSL=true -{{< /highlight >}} - - - +``` diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md index 60015b6..7b2332b 100644 --- a/docs/content/setup/docker.md +++ b/docs/content/setup/docker.md @@ -2,9 +2,7 @@ title: Using docker --- - - -{{< highlight Shell "linenos=table" >}} +```Shell docker run \ -e PROMETHEUS_PVE_SD_LOG_LEVEL=info \ -e PROMETHEUS_PVE_SD_LOG_FORMAT=console \ @@ -16,11 +14,11 @@ docker run \ -e PY_COLORS=1 \ -v $(pwd):/out \ thegeeklab/prometheus-pve-sd -{{< /highlight >}} - - +``` {{< hint info >}} **Info**\ Keep in mind, that you have to pass SELinux labels (:Z or :z) to your mount option if you are working on SELinux enabled systems. {{< /hint >}} + +After configuring and starting the service, Prometheus need to be [configured](/usage/getting-started/#prometheus-configuration) to use the external service discovery. diff --git a/docs/content/setup/pip.md b/docs/content/setup/pip.md index 19a234a..116af4c 100644 --- a/docs/content/setup/pip.md +++ b/docs/content/setup/pip.md @@ -2,10 +2,7 @@ title: Using pip --- - - - -{{< highlight Shell "linenos=table" >}} +```Shell # From PyPI as unprivileged user $ pip install prometheus-pve-sd --user @@ -14,7 +11,12 @@ $ sudo pip install prometheus-pve-sd # From Wheel file $ pip install https://github.com/thegeeklab/prometheus-pve-sd/releases/download/v0.1.0/prometheus_pve_sd-0.1.0-py3-none-any.whl -{{< /highlight >}} - - - +``` + +Start the service: + +```Shell +prometheus-pve-sd -vv --loop-delay 900 -o /etc/prometheus/pve.json +``` + +After configuring and starting the service, Prometheus need to be [configured](/usage/getting-started/#prometheus-configuration) to use the external service discovery. diff --git a/docs/content/setup/prometheus-operator.md b/docs/content/setup/prometheus-operator.md new file mode 100644 index 0000000..ea50798 --- /dev/null +++ b/docs/content/setup/prometheus-operator.md @@ -0,0 +1,80 @@ +--- +title: Using Prometheus Operator +--- + +{{< toc >}} + +As an alternative to local files service discovery Prometheus also support discoveries form HTTP endpoints. In a Kubernetes setup, with the Prometheus operator, it makes more sense to use this [HTTP SD](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#http_sd_config) instead of mounting the output file of the `prometheus-pve-sd` to the container. + +The `prometheus-pve-sd` module doesn't have a dedicated HTTP endpoint, therefore you need to use a web server sidecar, that hosts the static file. The following deployment configuration can serve as a starting point for most setups, and just requires some minor adjustments, depending on your Kubernetes setup. + +## Kubernetes configuration + +Deployment configuration: + +```YAML +apiVersion: apps/v1 +kind: Deployment +metadata: + creationTimestamp: null + labels: + app: proxmox-service-discovery + name: proxmox-service-discovery +spec: + replicas: 1 + selector: + matchLabels: + app: proxmox-service-discovery + strategy: {} + template: + metadata: + creationTimestamp: null + labels: + app: proxmox-service-discovery + spec: + containers: + - image: nginx + name: webserver + resources: {} + ports: + - containerPort: 80 + protocol: TCP + name: http + volumeMounts: + - name: pve-sd-output + mountPath: /usr/share/nginx/html + - image: thegeeklab/prometheus-pve-sd + name: prometheus-pve-sd + resources: {} + env: + - name: PROMETHEUS_PVE_SD_OUTPUT_FILE + value: /tmp/pve/proxmox.json + # Add more configurations here, or use a configMap or secret to inject the remaining configs + volumeMounts: + - name: pve-sd-output + mountPath: /tmp/pve/ + volumes: + - name: pve-sd-output + emptyDir: {} +status: {} +``` + +Additionally you will need a service, that exposes the HTTP endpoint within Kubernetes so Prometheus can scrape it. + +Service configuration: + +```YAML +apiVersion: v1 +kind: Service +metadata: + name: pve-sd-service +spec: + selector: + app: proxmox-service-discovery + ports: + - protocol: TCP + port: 80 + targetPort: 80 +``` + +After configuring and starting the service, Prometheus need to be [configured](/usage/getting-started/#prometheus-configuration) to use the external service discovery. diff --git a/docs/content/usage/advanced.md b/docs/content/usage/advanced.md new file mode 100644 index 0000000..5a11cad --- /dev/null +++ b/docs/content/usage/advanced.md @@ -0,0 +1,53 @@ +--- +title: Getting Started +--- + +{{< toc >}} + +## Prometheus relabeling + +### Use IP address labels + +Instead of `__meta_pve_name`, it is also possible to configure Prometheus to use the address provided by `__meta_pve_ipv4` or `__meta_pve_ipv4` for connections: + +```YAML +relabel_configs: +- replacement: ${1}:9273 + source_labels: + - __meta_pve_ipv4 + target_label: __address__ +``` + +### Convert tags to custom labels + +Tags of a node exposed by the `__meta_pve_tags` might be useful to build more complex configurations in Prometheus. As an example, an `alert` tag can be extracted to dine alerting routes based on the tag value. + +**Example:** + +Extract `group` and `alert` from a list of tags like this: `__meta_pve_tags="alert:team-1,group:cluster-1,node:node-1"` + +```YAML +relabel_configs: +- source_labels: + - __meta_pve_tags + regex: ".*group:([\w\-_]*)" + target_label: "group" + replacement: "${1}" +- source_labels: + - __meta_pve_tags + regex: ".*alert:([\w\-_]*)" + target_label: "alert" + replacement: "${1}" +``` + +Use the extracted `alert` label to set an Alertmanager route: + +```YAML +routes: +- receiver: "empty" + matchers: + - alert = muted +- receiver: "team-1" + matchers: + - alert = team-1 +``` diff --git a/docs/content/usage/getting-started.md b/docs/content/usage/getting-started.md index 829b4b7..072c88d 100644 --- a/docs/content/usage/getting-started.md +++ b/docs/content/usage/getting-started.md @@ -4,14 +4,6 @@ title: Getting Started {{< toc >}} -## Start PVE SD - -Create a [configuration file](/configuration/defaults/) with the required parameters to connect to your Proxmox VE (PVE) server before you start the service. - -```Shell -prometheus-pve-sd -vv --loop-delay 900 -o /etc/prometheus/pve.json -``` - ## Available Labels The following list of meta labels can be used to relabel your scrape results: @@ -51,6 +43,8 @@ The following list of meta labels can be used to relabel your scrape results: ## Prometheus configuration +### File service discovery + Prometheus needs a basic file service discovery configuration to fetch system metrics from the host's discovered from PVE. Depending on the used metrics exporter the configuration need to be adjusted, using [Telegraf](https://github.com/influxdata/telegraf/#telegraf) a starter configuration might look like this: ```YAML @@ -60,8 +54,6 @@ Prometheus needs a basic file service discovery configuration to fetch system me job_name: telegraf-pve metrics_path: /metrics relabel_configs: - - replacement: telegraf - target_label: job - replacement: ${1}:9273 source_labels: - __meta_pve_name @@ -71,48 +63,21 @@ Prometheus needs a basic file service discovery configuration to fetch system me target_label: instance ``` -### Use IP address labels - -Instead of `__meta_pve_name`, it is also possible to configure Prometheus to use the address provided by `__meta_pve_ipv4` or `__meta_pve_ipv4` for connections: - -```YAML -relabel_configs: -- replacement: ${1}:9273 - source_labels: - - __meta_pve_ipv4 - target_label: __address__ -``` - -### Convert tags to custom labels - -Tags of a node exposed by the `__meta_pve_tags` might be useful to build more complex configurations in Prometheus. As an example, an `alert` tag can be extracted to dine alerting routes based on the tag value. - -**Example:** - -Extract `group` and `alert` from a list of tags like this: `__meta_pve_tags="alert:team-1,group:cluster-1,node:node-1"` +### HTTP service discovery -```YAML -relabel_configs: -- source_labels: - - __meta_pve_tags - regex: ".*group:([\w\-_]*)" - target_label: "group" - replacement: "${1}" -- source_labels: - - __meta_pve_tags - regex: ".*alert:([\w\-_]*)" - target_label: "alert" - replacement: "${1}" -``` - -Use the extracted `alert` label to set an Alertmanager route: +If the static file is served by a web server, e.g. while using the [Prometheus Operator](/setup/prometheus-operator/) setup, a HTTP service discovery configuration is required: ```YAML -routes: -- receiver: "empty" - matchers: - - alert = muted -- receiver: "team-1" - matchers: - - alert = team-1 +- http_sd_configs: + url: pve-sd-service:80/proxmox.json + job_name: telegraf-pve + metrics_path: /metrics + relabel_configs: + - replacement: ${1}:9273 + source_labels: + - __meta_pve_name + target_label: __address__ + - source_labels: + - __meta_pve_name + target_label: instance ``` diff --git a/docs/data/menu/main.yml b/docs/data/menu/main.yml index 1ccb147..426966f 100644 --- a/docs/data/menu/main.yml +++ b/docs/data/menu/main.yml @@ -2,10 +2,12 @@ main: - name: Setup sub: - - name: Using pip + - name: Using PIP ref: "/setup/pip" - - name: Using docker + - name: Using Docker ref: "/setup/docker" + - name: Using Prometheus Operator + ref: "/setup/prometheus-operator" - name: Configuration ref: "/configuration" sub: @@ -19,3 +21,5 @@ main: sub: - name: Getting Started ref: "/usage/getting-started" + - name: Advanced + ref: "/usage/advanced" diff --git a/prometheuspvesd/exception.py b/prometheuspvesd/exception.py index c6890b0..31475d5 100644 --- a/prometheuspvesd/exception.py +++ b/prometheuspvesd/exception.py @@ -3,7 +3,7 @@ class PrometheusSDError(Exception): - """Generic exception class for promtheus-pve-sd.""" + """Generic exception class for Prometheus-pve-sd.""" def __init__(self, msg, original_exception=""): super(PrometheusSDError,