github/prometheus-pve-sd
0
0
Fork 0
mirror of https://github.com/thegeeklab/prometheus-pve-sd.git synced 2024-06-02 07:59:40 +02:00
Code Issues Projects Releases Wiki Activity

refactor operator docs

Browse Source
This commit is contained in:
Robert Kaussow 2022-03-11 13:01:11 +01:00
parent af52a75926
commit 5d2d2c505e
Signed by: xoxys
GPG Key ID: 4E692A2EAECC03C0
10 changed files with 99 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/content/configuration/cli.md
View File

@ -4,9 +4,7 @@ title: CLI options
You can get all available CLI options by running `prometheus-pve-sd --help`:
<!-- prettier-ignore-start -->
<!-- spellchecker-disable -->
{{< 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 >}}
<!-- spellchecker-enable -->
<!-- prettier-ignore-end -->
```

10
docs/content/configuration/defaults.md
View File

@ -2,10 +2,7 @@
title: Default settings
---
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<!-- spellchecker-disable -->
{{< 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 >}}
<!-- spellchecker-enable -->
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
```

10
docs/content/configuration/env.md
View File

@ -2,10 +2,7 @@
title: Environment Variables
---
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<!-- spellchecker-disable -->
{{< 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 >}}
<!-- spellchecker-enable -->
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
```

10
docs/content/setup/docker.md
View File

@ -2,9 +2,7 @@
title: Using docker
---
<!-- prettier-ignore-start -->
<!-- spellchecker-disable -->
{{< 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 >}}
<!-- spellchecker-enable -->
<!-- prettier-ignore-end -->
```
{{< 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.

18
docs/content/setup/pip.md
View File

@ -2,10 +2,7 @@
title: Using pip
---
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<!-- spellchecker-disable -->
{{< 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 >}}
<!-- spellchecker-enable -->
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
```
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.

26
docs/content/setup/prometheus-operator.md
View File

@ -1,5 +1,5 @@
---
title: Use with Prometheus operator
title: Using Prometheus Operator
---
{{< toc >}}
@ -48,7 +48,7 @@ spec:
resources: {}
env:
- name: PROMETHEUS_PVE_SD_OUTPUT_FILE
value: /tmp/pve/pve-sd.json
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
@ -77,24 +77,4 @@ spec:
targetPort: 80
```
## Prometheus configuration
Prometheus needs a basic http service discovery configuration to fetch system metrics from the host's discovered from PVE. The following example assumes, that the above deployment was done in the same namespace as the Prometheus instance.
```YAML
- http_sd_configs:
url: pve-sd-service:80/pve-sd.json
job_name: pve-service-discovery
metrics_path: /metrics
relabel_configs:
- replacement: ${1}:9273
source_labels:
- __meta_pve_name
target_label: __address__
- source_labels:
- __meta_pve_name
target_label: instance
```
See [usage](/usage/) for more details on the relabel configuration
After configuring and starting the service, Prometheus need to be [configured](/usage/getting-started/#prometheus-configuration) to use the external service discovery.

53
docs/content/usage/advanced.md Normal file
View File

@ -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
```

67
docs/content/usage/getting-started.md
View File

@ -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
### HTTP service discovery
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:
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
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
- 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
```

8
docs/data/menu/main.yml
View File

@ -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"

2
prometheuspvesd/exception.py
View File

@ -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,