Merge pull request #1 from promhippie/add-docs

Add basic documentation and build instructions
promhippie · Oct 7, 2018 · ba1bc89 · ba1bc89
2 parents 00c6143 + facaabd
commit ba1bc89
Show file tree

Hide file tree

Showing 9 changed files with 185 additions and 15 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git a/docs/layouts/partials/style.html b/docs/layouts/partials/style.html
@@ -1,3 +1,5 @@
+<link rel="stylesheet" href="syntax.css" />
+
 <style type="text/css">
 	body,
 	div,
@@ -148,13 +150,12 @@
 		color: #d54e21;
 	}
 
-	code,
-	cite {
-		background-color: #F0F2F4;
-		border-radius: 3px;
-		color: #000;
-		font: monospace;
-		padding: 2px 7px;
+	.highlight pre {
+		padding: 10px;
+	}
+
+	.highlight {
+		margin-bottom: 4%;
 	}
 
 	a {
@@ -212,6 +213,14 @@
 		column-gap: 20px;
 	}
 
+	dl dt {
+		font-weight: bold;
+	}
+
+	dl dd {
+		padding-left: 10px;
+	}
+
 	@media screen and (min-width: 500px) {
 		ul.col-2 {
 			-webkit-column-count: 3;

diff --git a/docs/static/service-discovery.png b/docs/static/service-discovery.png
diff --git a/docs/static/syntax.css b/docs/static/syntax.css
@@ -0,0 +1,59 @@
+/* Background */ .chroma { color: #f8f8f2; background-color: #272822 }
+/* Error */ .chroma .err { color: #960050; background-color: #1e0010 }
+/* LineTableTD */ .chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; }
+/* LineTable */ .chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; width: auto; overflow: auto; display: block; }
+/* LineHighlight */ .chroma .hl { display: block; width: 100%;background-color: #ffffcc }
+/* LineNumbersTable */ .chroma .lnt { margin-right: 0.4em; padding: 0 0.4em 0 0.4em; }
+/* LineNumbers */ .chroma .ln { margin-right: 0.4em; padding: 0 0.4em 0 0.4em; }
+/* Keyword */ .chroma .k { color: #66d9ef }
+/* KeywordConstant */ .chroma .kc { color: #66d9ef }
+/* KeywordDeclaration */ .chroma .kd { color: #66d9ef }
+/* KeywordNamespace */ .chroma .kn { color: #f92672 }
+/* KeywordPseudo */ .chroma .kp { color: #66d9ef }
+/* KeywordReserved */ .chroma .kr { color: #66d9ef }
+/* KeywordType */ .chroma .kt { color: #66d9ef }
+/* NameAttribute */ .chroma .na { color: #a6e22e }
+/* NameClass */ .chroma .nc { color: #a6e22e }
+/* NameConstant */ .chroma .no { color: #66d9ef }
+/* NameDecorator */ .chroma .nd { color: #a6e22e }
+/* NameException */ .chroma .ne { color: #a6e22e }
+/* NameFunction */ .chroma .nf { color: #a6e22e }
+/* NameOther */ .chroma .nx { color: #a6e22e }
+/* NameTag */ .chroma .nt { color: #f92672 }
+/* Literal */ .chroma .l { color: #ae81ff }
+/* LiteralDate */ .chroma .ld { color: #e6db74 }
+/* LiteralString */ .chroma .s { color: #e6db74 }
+/* LiteralStringAffix */ .chroma .sa { color: #e6db74 }
+/* LiteralStringBacktick */ .chroma .sb { color: #e6db74 }
+/* LiteralStringChar */ .chroma .sc { color: #e6db74 }
+/* LiteralStringDelimiter */ .chroma .dl { color: #e6db74 }
+/* LiteralStringDoc */ .chroma .sd { color: #e6db74 }
+/* LiteralStringDouble */ .chroma .s2 { color: #e6db74 }
+/* LiteralStringEscape */ .chroma .se { color: #ae81ff }
+/* LiteralStringHeredoc */ .chroma .sh { color: #e6db74 }
+/* LiteralStringInterpol */ .chroma .si { color: #e6db74 }
+/* LiteralStringOther */ .chroma .sx { color: #e6db74 }
+/* LiteralStringRegex */ .chroma .sr { color: #e6db74 }
+/* LiteralStringSingle */ .chroma .s1 { color: #e6db74 }
+/* LiteralStringSymbol */ .chroma .ss { color: #e6db74 }
+/* LiteralNumber */ .chroma .m { color: #ae81ff }
+/* LiteralNumberBin */ .chroma .mb { color: #ae81ff }
+/* LiteralNumberFloat */ .chroma .mf { color: #ae81ff }
+/* LiteralNumberHex */ .chroma .mh { color: #ae81ff }
+/* LiteralNumberInteger */ .chroma .mi { color: #ae81ff }
+/* LiteralNumberIntegerLong */ .chroma .il { color: #ae81ff }
+/* LiteralNumberOct */ .chroma .mo { color: #ae81ff }
+/* Operator */ .chroma .o { color: #f92672 }
+/* OperatorWord */ .chroma .ow { color: #f92672 }
+/* Comment */ .chroma .c { color: #75715e }
+/* CommentHashbang */ .chroma .ch { color: #75715e }
+/* CommentMultiline */ .chroma .cm { color: #75715e }
+/* CommentSingle */ .chroma .c1 { color: #75715e }
+/* CommentSpecial */ .chroma .cs { color: #75715e }
+/* CommentPreproc */ .chroma .cp { color: #75715e }
+/* CommentPreprocFile */ .chroma .cpf { color: #75715e }
+/* GenericDeleted */ .chroma .gd { color: #f92672 }
+/* GenericEmph */ .chroma .ge { font-style: italic }
+/* GenericInserted */ .chroma .gi { color: #a6e22e }
+/* GenericStrong */ .chroma .gs { font-weight: bold }
+/* GenericSubheading */ .chroma .gu { color: #75715e }