From 884a44af8bc2079e856b2c2e2dbe029c41eaab78 Mon Sep 17 00:00:00 2001 From: Thomas Boerger Date: Sun, 7 Oct 2018 18:37:35 +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 | 82 ++++++++++++++++++++++++++++++ docs/content/license.md | 2 +- docs/content/usage.md | 6 --- docs/layouts/partials/style.html | 23 ++++++--- docs/static/service-discovery.png | Bin 0 -> 314857 bytes docs/static/syntax.css | 59 +++++++++++++++++++++ 9 files changed, 191 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 db92ac2..f67ee0c 100644 --- a/docs/config.toml +++ b/docs/config.toml @@ -1,6 +1,7 @@ baseURL = "https://promhippie.github.io/prometheus-scw-sd/" languageCode = "en-us" title = "Prometheus Scaleway SD" +pygmentsUseClasses = true [blackfriday] angledQuotes = true diff --git a/docs/content/building.md b/docs/content/building.md index a487356..2d5cd2f 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-scw-sd +cd $GOPATH/src/github.com/promhippie/prometheus-scw-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-scw-sd -h` to see all available options. diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md index 4583eb8..1784078 100644 --- a/docs/content/getting-started.md +++ b/docs/content/getting-started.md @@ -7,4 +7,86 @@ 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 4f445d609f0894a5fe40c20e7a42d565 "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 4f445d609f0894a5fe40c20e7a42d565 "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-scw-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 4f445d609f0894a5fe40c20e7a42d565 "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 4f445d609f0894a5fe40c20e7a42d565 "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 Hetzner" >}} + +## 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_SCW_TOKEN +: Access token for the Scaleway API, required for authentication + +PROMETHEUS_SCW_ORG +: Organization for the Scaleway API, required for authentication + +PROMETHEUS_SCW_REGION +: Region for the Scaleway API, required for authentication + +PROMETHEUS_SCW_LOG_LEVEL +: Only log messages with given severity, defaults to `info` + +PROMETHEUS_SCW_LOG_PRETTY +: Enable pretty messages for logging, defaults to `true` + +PROMETHEUS_SCW_WEB_ADDRESS +: Address to bind the metrics server, defaults to `0.0.0.0:9000` + +PROMETHEUS_SCW_WEB_PATH +: Path to bind the metrics server, defaults to `/metrics` + +PROMETHEUS_SCW_OUTPUT_FILE +: Path to write the file_sd config, defaults to `/etc/prometheus/scw.json` + +PROMETHEUS_SCW_OUTPUT_REFRESH +: Discovery refresh interval in seconds, defaults to `30` + +## Labels + +* `__meta_scaleway_name` +* `__meta_scaleway_id` +* `__meta_scaleway_arch` +* `__meta_scaleway_image_id` +* `__meta_scaleway_image_name` +* `__meta_scaleway_public_ipv4` +* `__meta_scaleway_state` +* `__meta_scaleway_private_ipv4` +* `__meta_scaleway_hostname` +* `__meta_scaleway_org` +* `__meta_scaleway_commercial_type` +* `__meta_scaleway_platform` +* `__meta_scaleway_hypervisor` +* `__meta_scaleway_node` +* `__meta_scaleway_blade` +* `__meta_scaleway_chassis` +* `__meta_scaleway_cluster` +* `__meta_scaleway_zone` + +## Metrics + +prometheus_scw_sd_request_duration_seconds +: Histogram of latencies for requests to the Scaleway API + +prometheus_scw_sd_request_failures_total +: Total number of failed requests to the Scaleway API diff --git a/docs/content/license.md b/docs/content/license.md index 4230f08..67b047f 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-scw-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 @@ + +