From facaabd860fe7f1918c2fc791b55b3d4e3d9c577 Mon Sep 17 00:00:00 2001 From: Thomas Boerger Date: Sun, 7 Oct 2018 18:37:19 +0200 Subject: [PATCH] Add basic documentation and build instructions Signed-off-by: Thomas Boerger --- CHANGELOG.md | 6 +++ docs/config.toml | 1 + docs/content/building.md | 27 ++++++++++- docs/content/getting-started.md | 76 ++++++++++++++++++++++++++++++ docs/content/license.md | 2 +- docs/content/usage.md | 6 --- docs/layouts/partials/style.html | 23 ++++++--- docs/static/service-discovery.png | Bin 0 -> 295475 bytes docs/static/syntax.css | 59 +++++++++++++++++++++++ 9 files changed, 185 insertions(+), 15 deletions(-) delete mode 100644 docs/content/usage.md create mode 100644 docs/static/service-discovery.png create mode 100644 docs/static/syntax.css diff --git a/CHANGELOG.md b/CHANGELOG.md index e7c8ff5..a264983 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## [Unreleased] + +### Added + +* Add basic documentation + ## [0.1.0] - 2018-09-24 ### Added diff --git a/docs/config.toml b/docs/config.toml index f8023c1..83c8ffd 100644 --- a/docs/config.toml +++ b/docs/config.toml @@ -1,6 +1,7 @@ baseURL = "https://promhippie.github.io/prometheus-hcloud-sd/" languageCode = "en-us" title = "Prometheus HetznerCloud SD" +pygmentsUseClasses = true [blackfriday] angledQuotes = true diff --git a/docs/content/building.md b/docs/content/building.md index a487356..9cf94d3 100644 --- a/docs/content/building.md +++ b/docs/content/building.md @@ -2,5 +2,30 @@ title: "Building" date: 2018-05-02T00:00:00+00:00 anchor: "building" -weight: 30 +weight: 20 --- + +As this project is built with Go you need to install Go first. The installation of Go is out of the scope of this document, please follow the [official documentation](https://golang.org/doc/install). After the installation of Go you need to get the sources: + +{{< highlight txt >}} +go get -d github.com/promhippie/prometheus-hcloud-sd +cd $GOPATH/src/github.com/promhippie/prometheus-hcloud-sd +{{< / highlight >}} + +All required tool besides Go itself are bundled or getting automatically installed within the `GOPATH`. We are using [retool](https://github.com/twitchtv/retool) to keep the used tools consistent and [dep](https://github.com/golang/dep) to manage the dependencies. All commands to build this project are part of our `Makefile`. + +{{< highlight txt >}} +# install retool +make retool + +# sync dependencies +make sync + +# generate code +make generate + +# build binary +make build +{{< / highlight >}} + +Finally you should have the binary within the `bin/` folder now, give it a try with `./bin/prometheus-hcloud-sd -h` to see all available options. diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md index 4583eb8..5aae8e7 100644 --- a/docs/content/getting-started.md +++ b/docs/content/getting-started.md @@ -7,4 +7,80 @@ weight: 10 ## Installation +We won't cover further details how to properly setup [Prometheus](https://prometheus.io) itself, we will only cover some basic setup based on [docker-compose](https://docs.docker.com/compose/). But if you want to run this service discovery without [docker-compose](https://docs.docker.com/compose/) you should be able to adopt that to your needs. + +First of all we need to prepare a configuration for [Prometheus](https://prometheus.io) that includes the service discovery which simply maps to a node exporter. + +{{< gist tboerger b9c39b6571f48ce2b132de1531061531 "prometheus.yml" >}} + +After preparing the configuration we need to create the `docker-compose.yml` within the same folder, this `docker-compose.yml` starts a simple [Prometheus](https://prometheus.io) instance together with the service discovery. Don't forget to update the envrionment variables with the required credentials. If you are using a different volume for the service discovery you have to make sure that the container user is allowed to write to this volume. + +{{< gist tboerger b9c39b6571f48ce2b132de1531061531 "docker-compose.yml" >}} + +Since our `latest` Docker tag always refers to the `master` branch of the Git repository you should always use some fixed version. You can see all available tags at our [DockerHub repository](https://hub.docker.com/r/promhippie/prometheus-hcloud-sd/tags/), there you will see that we also provide a manifest, you can easily start the exporter on various architectures without any change to the image name. You should apply a change like this to the `docker-compose.yml`: + +{{< gist tboerger b9c39b6571f48ce2b132de1531061531 "tag.diff" >}} + +Finally the service discovery should be configured fine, let's start this stack with [docker-compose](https://docs.docker.com/compose/), you just need to execute `docker-compose up` within the directory where you have stored `prometheus.yml` and `docker-compose.yml`. + +{{< gist tboerger b9c39b6571f48ce2b132de1531061531 "output.log" >}} + +That's all, the service discovery should be up and running. You can access [Prometheus](https://prometheus.io) at [http://localhost:9090](http://localhost:9090). + +{{< figure src="service-discovery.png" title="Prometheus service discovery for HetznerCloud" >}} + +## Kubernetes + +Currently we have not prepared a deployment for Kubernetes, but this is something we will provide for sure. Most interesting will be the integration into the [Prometheus Operator](https://coreos.com/operators/prometheus/docs/latest/), so stay tuned. + ## Configuration + +PROMETHEUS_HCLOUD_TOKEN +: Access token for the HetznerCloud API, required for authentication + +PROMETHEUS_HCLOUD_LOG_LEVEL +: Only log messages with given severity, defaults to `info` + +PROMETHEUS_HCLOUD_LOG_PRETTY +: Enable pretty messages for logging, defaults to `true` + +PROMETHEUS_HCLOUD_WEB_ADDRESS +: Address to bind the metrics server, defaults to `0.0.0.0:9000` + +PROMETHEUS_HCLOUD_WEB_PATH +: Path to bind the metrics server, defaults to `/metrics` + +PROMETHEUS_HCLOUD_OUTPUT_FILE +: Path to write the file_sd config, defaults to `/etc/prometheus/hcloud.json` + +PROMETHEUS_HCLOUD_OUTPUT_REFRESH +: Discovery refresh interval in seconds, defaults to `30` + +## Labels + +* `__meta_hcloud_name` +* `__meta_hcloud_status` +* `__meta_hcloud_public_ipv4` +* `__meta_hcloud_public_ipv6` +* `__meta_hcloud_type` +* `__meta_hcloud_cores` +* `__meta_hcloud_memory` +* `__meta_hcloud_disk` +* `__meta_hcloud_storage` +* `__meta_hcloud_cpu` +* `__meta_hcloud_datacenter` +* `__meta_hcloud_location` +* `__meta_hcloud_city` +* `__meta_hcloud_country` +* `__meta_hcloud_image_name` +* `__meta_hcloud_image_type` +* `__meta_hcloud_os_flavor` +* `__meta_hcloud_os_version` + +## Metrics + +prometheus_hcloud_sd_request_duration_seconds +: Histogram of latencies for requests to the HetznerCloud API + +prometheus_hcloud_sd_request_failures_total +: Total number of failed requests to the HetznerCloud API diff --git a/docs/content/license.md b/docs/content/license.md index a9ddc9b..3816e7d 100644 --- a/docs/content/license.md +++ b/docs/content/license.md @@ -2,7 +2,7 @@ title: "License" date: 2018-05-02T00:00:00+00:00 anchor: "license" -weight: 40 +weight: 30 --- This project is licensed under the [Apache 2.0](https://github.com/promhippie/prometheus-hcloud-sd/blob/master/LICENSE) license. For the license of the used libraries you have to check the respective sources. diff --git a/docs/content/usage.md b/docs/content/usage.md deleted file mode 100644 index c8be824..0000000 --- a/docs/content/usage.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Usage" -date: 2018-05-02T00:00:00+00:00 -anchor: "usage" -weight: 20 ---- diff --git a/docs/layouts/partials/style.html b/docs/layouts/partials/style.html index e884d91..cba6e12 100644 --- a/docs/layouts/partials/style.html +++ b/docs/layouts/partials/style.html @@ -1,3 +1,5 @@ + +