From 9d90c3b7870f77c512493e889b2a5015095516e2 Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Mon, 14 Jun 2021 09:45:19 +0200 Subject: [PATCH] docs: initial docs deployment (#10) --- .dictionary | 5 ++ .drone.jsonnet | 108 ++++++++++++------------- .drone.yml | 47 ++++++++++- .github/settings.yml | 1 + README.md | 4 +- docs/config.yaml | 31 +++++++ docs/content/_index.md | 15 ++++ docs/content/configuration/_index.md | 11 +++ docs/content/configuration/cli.md | 31 +++++++ docs/content/configuration/defaults.md | 42 ++++++++++ docs/content/configuration/env.md | 29 +++++++ docs/content/setup/_index.md | 3 + docs/content/setup/docker.md | 26 ++++++ docs/content/setup/pip.md | 20 +++++ docs/content/usage/_index.md | 58 +++++++++++++ docs/data/menu/main.yml | 19 +++++ docs/data/menu/more.yml | 10 +++ docs/static/.htaccess | 16 ++++ 18 files changed, 420 insertions(+), 56 deletions(-) create mode 100644 docs/config.yaml create mode 100644 docs/content/_index.md create mode 100644 docs/content/configuration/_index.md create mode 100644 docs/content/configuration/cli.md create mode 100644 docs/content/configuration/defaults.md create mode 100644 docs/content/configuration/env.md create mode 100644 docs/content/setup/_index.md create mode 100644 docs/content/setup/docker.md create mode 100644 docs/content/setup/pip.md create mode 100644 docs/content/usage/_index.md create mode 100644 docs/data/menu/main.yml create mode 100644 docs/data/menu/more.yml create mode 100644 docs/static/.htaccess diff --git a/.dictionary b/.dictionary index 3bacb67..462d726 100644 --- a/.dictionary +++ b/.dictionary @@ -5,3 +5,8 @@ xoxys Proxmox VE TBD +PVE +SELinux +CLI +JSON +toc diff --git a/.drone.jsonnet b/.drone.jsonnet index 9e82efc..b5c4a74 100644 --- a/.drone.jsonnet +++ b/.drone.jsonnet @@ -320,60 +320,60 @@ local PipelineDocs = { NPM_CONFIG_LOGLEVEL: 'error', }, }, - // { - // name: 'testbuild', - // image: 'thegeeklab/hugo:0.83.1', - // commands: [ - // 'hugo -s docs/ -b http://localhost/', - // ], - // }, - // { - // name: 'link-validation', - // image: 'thegeeklab/link-validator', - // commands: [ - // 'link-validator -ro', - // ], - // environment: { - // LINK_VALIDATOR_BASE_DIR: 'docs/public', - // }, - // }, - // { - // name: 'build', - // image: 'thegeeklab/hugo:0.83.1', - // commands: [ - // 'hugo -s docs/', - // ], - // }, - // { - // name: 'beautify', - // image: 'node:lts-alpine', - // commands: [ - // 'npm install -g js-beautify', - // "html-beautify -r -f 'docs/public/**/*.html'", - // ], - // environment: { - // FORCE_COLOR: true, - // NPM_CONFIG_LOGLEVEL: 'error', - // }, - // }, - // { - // name: 'publish', - // image: 'plugins/s3-sync', - // settings: { - // access_key: { from_secret: 's3_access_key' }, - // bucket: 'geekdocs', - // delete: true, - // endpoint: 'https://sp.rknet.org', - // path_style: true, - // secret_key: { from_secret: 's3_secret_access_key' }, - // source: 'docs/public/', - // strip_prefix: 'docs/public/', - // target: '/${DRONE_REPO_NAME}', - // }, - // when: { - // ref: ['refs/heads/main', 'refs/tags/**'], - // }, - // }, + { + name: 'testbuild', + image: 'thegeeklab/hugo:0.83.1', + commands: [ + 'hugo -s docs/ -b http://localhost/', + ], + }, + { + name: 'link-validation', + image: 'thegeeklab/link-validator', + commands: [ + 'link-validator -ro', + ], + environment: { + LINK_VALIDATOR_BASE_DIR: 'docs/public', + }, + }, + { + name: 'build', + image: 'thegeeklab/hugo:0.83.1', + commands: [ + 'hugo -s docs/', + ], + }, + { + name: 'beautify', + image: 'node:lts-alpine', + commands: [ + 'npm install -g js-beautify', + "html-beautify -r -f 'docs/public/**/*.html'", + ], + environment: { + FORCE_COLOR: true, + NPM_CONFIG_LOGLEVEL: 'error', + }, + }, + { + name: 'publish', + image: 'plugins/s3-sync', + settings: { + access_key: { from_secret: 's3_access_key' }, + bucket: 'geekdocs', + delete: true, + endpoint: 'https://sp.rknet.org', + path_style: true, + secret_key: { from_secret: 's3_secret_access_key' }, + source: 'docs/public/', + strip_prefix: 'docs/public/', + target: '/${DRONE_REPO_NAME}', + }, + when: { + ref: ['refs/heads/main', 'refs/tags/**'], + }, + }, ], depends_on: [ 'build-package', diff --git a/.drone.yml b/.drone.yml index 3e7017b..81dfc22 100644 --- a/.drone.yml +++ b/.drone.yml @@ -479,6 +479,51 @@ steps: FORCE_COLOR: true NPM_CONFIG_LOGLEVEL: error +- name: testbuild + image: thegeeklab/hugo:0.83.1 + commands: + - hugo -s docs/ -b http://localhost/ + +- name: link-validation + image: thegeeklab/link-validator + commands: + - link-validator -ro + environment: + LINK_VALIDATOR_BASE_DIR: docs/public + +- name: build + image: thegeeklab/hugo:0.83.1 + commands: + - hugo -s docs/ + +- name: beautify + image: node:lts-alpine + commands: + - npm install -g js-beautify + - html-beautify -r -f 'docs/public/**/*.html' + environment: + FORCE_COLOR: true + NPM_CONFIG_LOGLEVEL: error + +- name: publish + image: plugins/s3-sync + settings: + access_key: + from_secret: s3_access_key + bucket: geekdocs + delete: true + endpoint: https://sp.rknet.org + path_style: true + secret_key: + from_secret: s3_secret_access_key + source: docs/public/ + strip_prefix: docs/public/ + target: /${DRONE_REPO_NAME} + when: + ref: + - refs/heads/main + - refs/tags/** + trigger: ref: - refs/heads/main @@ -585,6 +630,6 @@ depends_on: --- kind: signature -hmac: b6ecc59cd94c224bbd990f1d6be90ec6c28e8faf121b37c56f47fa9befb77ad8 +hmac: 791f2a668d1295b69cb7000c3a38b8e3ca15d99b1c8ac40559c71aa9456fc018 ... diff --git a/.github/settings.yml b/.github/settings.yml index 5af2e62..aa4f657 100644 --- a/.github/settings.yml +++ b/.github/settings.yml @@ -1,6 +1,7 @@ repository: name: prometheus-pve-sd description: Prometheus Service Discovery for Proxmox VE + homepage: https://prometheus-pve-sd.geekdocs.de topics: prometheus, proxmox, metrics, sd, python private: false diff --git a/README.md b/README.md index e5a18db..28867f1 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,9 @@ Prometheus Service Discovery for Proxmox VE [![Source: GitHub](https://img.shields.io/badge/source-github-blue.svg?logo=github&logoColor=white)](https://github.com/thegeeklab/prometheus-pve-sd) [![License: MIT](https://img.shields.io/github/license/thegeeklab/prometheus-pve-sd)](https://github.com/thegeeklab/prometheus-pve-sd/blob/main/LICENSE) -TBD +This project provides a simple custom service discovery for [Prometheus](https://prometheus.io/). It is using the Proxmox PVE API to fetch Hosts and it's meta information to generate a Prometheus compatible [file based](https://prometheus.io/docs/guides/file-sd/) service discovery. Releases are available as Python Packages on [GitHub](https://github.com/thegeeklab/prometheus-pve-sd/releases) or [PyPI](https://pypi.org/project/prometheus-pve-sd/) and as Docker Image on [Docker Hub](https://hub.docker.com/r/thegeeklab/prometheus-pve-sd). + +You can find the full documentation at [https://prometheus-pve-sd.geekdocs.de](https://prometheus-pve-sd.geekdocs.de). ## Contributors diff --git a/docs/config.yaml b/docs/config.yaml new file mode 100644 index 0000000..78332bf --- /dev/null +++ b/docs/config.yaml @@ -0,0 +1,31 @@ +--- +baseURL: https://prometheus-pve-sd.geekdocs.de/ +title: prometheus-pve-sd +theme: hugo-geekdoc +pygmentsUseClasses: true +pygmentsCodeFences: true + +# Geekdoc configuration +disablePathToLower: true +enableGitInfo: true + +# Needed for mermaid/katex shortcodes +markup: + goldmark: + renderer: + unsafe: true + tableOfContents: + startLevel: 1 + +params: + geekdocMenuBundle: true + geekdocToC: 3 + + geekdocRepo: https://github.com/thegeeklab/prometheus-pve-sd + geekdocEditPath: edit/main/docs/content + + geekdocDateFormat: "Jan 2, 2006" + geekdocSearch: true + + geekdocLegalNotice: https://thegeeklab.de/legal-notice/#contact-information + geekdocPrivacyPolicy: https://thegeeklab.de/legal-notice/#privacy-policy diff --git a/docs/content/_index.md b/docs/content/_index.md new file mode 100644 index 0000000..c9041f3 --- /dev/null +++ b/docs/content/_index.md @@ -0,0 +1,15 @@ +--- +title: Documentation +--- + +[![Build Status](https://img.shields.io/drone/build/thegeeklab/prometheus-pve-sd?logo=drone&server=https%3A%2F%2Fdrone.thegeeklab.de)](https://drone.thegeeklab.de/thegeeklab/prometheus-pve-sd) +[![Docker Hub](https://img.shields.io/badge/dockerhub-latest-blue.svg?logo=docker&logoColor=white)](https://hub.docker.com/r/thegeeklab/prometheus-pve-sd) +[![Quay.io](https://img.shields.io/badge/quay-latest-blue.svg?logo=docker&logoColor=white)](https://quay.io/repository/thegeeklab/prometheus-pve-sd) +[![Python Version](https://img.shields.io/pypi/pyversions/prometheus-pve-sd.svg)](https://pypi.org/project/prometheus-pve-sd/) +[![PyPI Status](https://img.shields.io/pypi/status/prometheus-pve-sd.svg)](https://pypi.org/project/prometheus-pve-sd/) +[![PyPI Release](https://img.shields.io/pypi/v/prometheus-pve-sd.svg)](https://pypi.org/project/prometheus-pve-sd/) +[![GitHub contributors](https://img.shields.io/github/contributors/thegeeklab/prometheus-pve-sd)](https://github.com/thegeeklab/prometheus-pve-sd/graphs/contributors) +[![Source: GitHub](https://img.shields.io/badge/source-github-blue.svg?logo=github&logoColor=white)](https://github.com/thegeeklab/prometheus-pve-sd) +[![License: MIT](https://img.shields.io/github/license/thegeeklab/prometheus-pve-sd)](https://github.com/thegeeklab/prometheus-pve-sd/blob/main/LICENSE) + +This project provides a simple custom service discovery for [Prometheus](https://prometheus.io/). It is using the Proxmox PVE API to fetch Hosts and it's meta information to generate a Prometheus compatible [file based](https://prometheus.io/docs/guides/file-sd/) service discovery. Releases are available as Python Packages on [GitHub](https://github.com/thegeeklab/prometheus-pve-sd/releases) or [PyPI](https://pypi.org/project/prometheus-pve-sd/) and as Docker Image on [Docker Hub](https://hub.docker.com/r/thegeeklab/prometheus-pve-sd). diff --git a/docs/content/configuration/_index.md b/docs/content/configuration/_index.md new file mode 100644 index 0000000..36704b3 --- /dev/null +++ b/docs/content/configuration/_index.md @@ -0,0 +1,11 @@ +--- +title: Configuration +--- + +Changes can be made on different locations which will be processed in the following order (last wins): + +- default configuration (build-in) +- global configuration file (path depends on your operating system) +- user-defined configuration file +- environment variables +- CLI options diff --git a/docs/content/configuration/cli.md b/docs/content/configuration/cli.md new file mode 100644 index 0000000..a673d1e --- /dev/null +++ b/docs/content/configuration/cli.md @@ -0,0 +1,31 @@ +--- +title: CLI options +--- + +You can get all available CLI options by running `prometheus-pve-sd --help`: + + + +{{< highlight Shell "linenos=table" >}} +$ 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] + +Prometheus Service Discovery for Proxmox VE + +optional arguments: + -h, --help show this help message and exit + -c CONFIG_FILE, --config CONFIG_FILE + location of configuration file + -o OUTPUT_FILE, --output OUTPUT_FILE + output file + -d LOOP_DELAY, --loop-delay LOOP_DELAY + delay between discovery runs + --no-service run discovery only once + -f LOG_FORMAT, --log-format LOG_FORMAT + used log format + -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 new file mode 100644 index 0000000..4a0394a --- /dev/null +++ b/docs/content/configuration/defaults.md @@ -0,0 +1,42 @@ +--- +title: Default settings +--- + + + + +{{< highlight YAML "linenos=table" >}} +--- +logging: + # supported log levels: debug|info|warning|error|critical + level: warning + # supported log formats: console|json|simple + format: console + +output_file: +loop_delay: 300 +# Run pve sd in a loop and discover hosts every n seconds (as defined in loop_delay). +# Can be disabled to run disovery only once. +service: true + +exclude_state: [] +exclude_vmid: [] + +pve: + server: + user: + password + auth_timeout: 5 + verify_ssl: true + +# Example +# pve: +# server: proxmox.example.com +# user: root +# password: secure +# auth_timeout: 5 +# verify_ssl: true +{{< /highlight >}} + + + diff --git a/docs/content/configuration/env.md b/docs/content/configuration/env.md new file mode 100644 index 0000000..236481b --- /dev/null +++ b/docs/content/configuration/env.md @@ -0,0 +1,29 @@ +--- +title: Environment Variables +--- + + + + +{{< highlight Shell "linenos=table" >}} +PROMETHEUS_PVE_SD_CONFIG_FILE= +# supported log levels: debug|info|warning|error|critical +PROMETHEUS_PVE_SD_LOG_LEVEL=warning +# supported log formats: console|json|simple +PROMETHEUS_PVE_SD_LOG_FORMAT=console +PROMETHEUS_PVE_SD_OUTPUT_FILE= +PROMETHEUS_PVE_SD_LOOP_DELAY=300 +# Run pve sd in a loop and discover hosts every n seconds (as defined in PROMETHEUS_PVE_SD_LOOP_DELAY). +# Can be disabled to run disovery only once. +PROMETHEUS_PVE_SD_SERVICE=true +PROMETHEUS_PVE_SD_EXCLUDE_STATE= +PROMETHEUS_PVE_SD_EXCLUDE_VMID= +PROMETHEUS_PVE_SD_PVE_SERVER= +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/_index.md b/docs/content/setup/_index.md new file mode 100644 index 0000000..0e51640 --- /dev/null +++ b/docs/content/setup/_index.md @@ -0,0 +1,3 @@ +--- +title: Setup +--- diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md new file mode 100644 index 0000000..60015b6 --- /dev/null +++ b/docs/content/setup/docker.md @@ -0,0 +1,26 @@ +--- +title: Using docker +--- + + + +{{< highlight Shell "linenos=table" >}} +docker run \ + -e PROMETHEUS_PVE_SD_LOG_LEVEL=info \ + -e PROMETHEUS_PVE_SD_LOG_FORMAT=console \ + -e PROMETHEUS_PVE_SD_OUTPUT_FILE=/out/pve.json \ + -e PROMETHEUS_PVE_SD_SERVICE=false \ + -e PROMETHEUS_PVE_SD_PVE_SERVER=pve.example.com \ + -e PROMETHEUS_PVE_SD_PVE_USER=root \ + -e PROMETHEUS_PVE_SD_PVE_PASSWORD=secure \ + -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 >}} diff --git a/docs/content/setup/pip.md b/docs/content/setup/pip.md new file mode 100644 index 0000000..19a234a --- /dev/null +++ b/docs/content/setup/pip.md @@ -0,0 +1,20 @@ +--- +title: Using pip +--- + + + + +{{< highlight Shell "linenos=table" >}} +# From PyPI as unprivileged user +$ pip install prometheus-pve-sd --user + +# .. or as root +$ 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 >}} + + + diff --git a/docs/content/usage/_index.md b/docs/content/usage/_index.md new file mode 100644 index 0000000..e4c5251 --- /dev/null +++ b/docs/content/usage/_index.md @@ -0,0 +1,58 @@ +--- +title: Usage +--- + +{{< toc >}} + +## Start PVE SD + +Create a [configuration file](/configuration/defaults/) with the required parameters to connect to your PVE server before you start the service. + +```Shell +run 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: + +`__meta_pve_ip` + +`__meta_pve_name` + +`__meta_pve_type` + +`__meta_pve_vmid` + +`__meta_pve_cpu` + +`__meta_pve_cores` + +`__meta_pve_memory` + +`__meta_pve_status` + +`__meta_pve_groups` +: Groups will be discovered from the `Notes` field of a host and need to be set as JSON e.g. `{"groups":["group1","group2"]}` + +## Prometheus configuration + +This example configuration snippet for the Prometheus `scrape_config` Prometheus to scrape `telegraf` assuming that it is deployed on all your servers. + +```YAML +- file_sd_configs: + - files: + - /opt/prometheus/conf/file_sd/proxmox.json + job_name: telegraf-pve + metrics_path: /metrics + relabel_configs: + - replacement: telegraf + target_label: job + - 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 new file mode 100644 index 0000000..da79e25 --- /dev/null +++ b/docs/data/menu/main.yml @@ -0,0 +1,19 @@ +--- +main: + - name: Setup + sub: + - name: Using pip + ref: "/setup/pip" + - name: Using docker + ref: "/setup/docker" + - name: Configuration + ref: "/configuration" + sub: + - name: Default settings + ref: "/configuration/defaults" + - name: CLI options + ref: "/configuration/cli" + - name: Environment variables + ref: "/configuration/env" + - name: Usage + ref: "/usage" diff --git a/docs/data/menu/more.yml b/docs/data/menu/more.yml new file mode 100644 index 0000000..ab21ecb --- /dev/null +++ b/docs/data/menu/more.yml @@ -0,0 +1,10 @@ +--- +more: + - name: Releases + ref: "https://github.com/thegeeklab/prometheus-pve-sd/releases" + external: true + icon: "gdoc_download" + - name: "View Source" + ref: "https://github.com/thegeeklab/prometheus-pve-sd" + external: true + icon: "gdoc_github" diff --git a/docs/static/.htaccess b/docs/static/.htaccess new file mode 100644 index 0000000..b5a07f4 --- /dev/null +++ b/docs/static/.htaccess @@ -0,0 +1,16 @@ +ErrorDocument 404 /404.html + +ExpiresActive On +ExpiresDefault "access plus 600 seconds" +ExpiresByType text/css "access plus 1 week" +ExpiresByType text/javascript "access plus 1 month" +ExpiresByType text/html "access plus 1 seconds" +ExpiresByType application/javascript "access plus 1 month" +ExpiresByType application/x-javascript "access plus 1 month" +ExpiresByType image/gif "access plus 1 week" +ExpiresByType image/jpeg "access plus 1 week" +ExpiresByType image/png "access plus 1 week" +ExpiresByType image/x-icon "access plus 1 month" +ExpiresByType image/svg+xml "access plus 1 week" +ExpiresByType application/x-font-woff "access plus 1 week" +ExpiresByType application/font-woff2 "access plus 1 week"