Usage Back to Top
Installation
We won’t cover further details how to properly setup Prometheus itself, we will only cover some basic setup based on docker-compose. But if you want to run this service discovery without docker-compose you should be able to adopt that to your needs.
First of all we need to prepare a configuration for Prometheus that includes the service discovery which simply maps to a node exporter.
global:
scrape_interval: 1m
scrape_timeout: 10s
evaluation_interval: 1m
scrape_configs:
- job_name: node
file_sd_configs:
- files: [ "/etc/sd/hcloud.json" ]
relabel_configs:
- source_labels: [__meta_hcloud_public_ipv4]
replacement: "${1}:9100"
target_label: __address__
- source_labels: [__meta_hcloud_datacenter]
target_label: datacenter
- source_labels: [__meta_hcloud_name]
target_label: instance
- job_name: hcloud-sd
static_configs:
- targets:
- hcloud-sd:9000After preparing the configuration we need to create the docker-compose.yml
within the same folder, this docker-compose.yml starts a simple
Prometheus instance together with the service discovery. Don’t
forget to update the environment 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.
version: '2'
volumes:
prometheus:
services:
prometheus:
image: prom/prometheus:latest
restart: always
ports:
- 9090:9090
volumes:
- prometheus:/prometheus
- ./prometheus.yml:/etc/prometheus/prometheus.yml
- ./service-discovery:/etc/sd
hcloud-sd:
image: promhippie/prometheus-hcloud-sd:latest
restart: always
environment:
- PROMETHEUS_HCLOUD_LOG_PRETTY=true
- PROMETHEUS_HCLOUD_OUTPUT_FILE=/etc/sd/hcloud.json
- PROMETHEUS_HCLOUD_TOKEN=your-token
volumes:
- ./service-discovery:/etc/sdSince our latest 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 DockerHub or Quay, 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 file:
hcloud-sd:
- image: promhippie/prometheus-hcloud-sd:latest
+ image: promhippie/prometheus-hcloud-sd:0.5.0
restart: always
environment:
- PROMETHEUS_HCLOUD_LOG_PRETTY=true
- PROMETHEUS_HCLOUD_OUTPUT_FILE=/etc/sd/hcloud.json
- PROMETHEUS_HCLOUD_TOKEN=your-token
volumes:
- ./service-discovery:/etc/sd
Depending on how you have launched and configured Prometheus it’s
possible that it’s running as user nobody, in that case you should run the
service discovery as this user as well, otherwise Prometheus won’t
be able to read the generated JSON file:
hcloud-sd:
image: promhippie/prometheus-hcloud-sd:latest
restart: always
+ user: '65534'
environment:
- PROMETHEUS_HCLOUD_LOG_PRETTY=true
- PROMETHEUS_HCLOUD_OUTPUT_FILE=/etc/sd/hcloud.json
- PROMETHEUS_HCLOUD_TOKEN=your-token
volumes:
- ./service-discovery:/etc/sd
If you want to secure the access to the exporter or also the HTTP service discovery endpoint you can provide a web config. You just need to provide a path to the config file in order to enable the support for it, for details about the config format look at the documentation section:
hcloud-sd:
image: promhippie/prometheus-hcloud-sd:latest
restart: always
environment:
+ - PROMETHEUS_HCLOUD_WEB_CONFIG=path/to/web-config.json
- PROMETHEUS_HCLOUD_LOG_PRETTY=true
- PROMETHEUS_HCLOUD_OUTPUT_FILE=/etc/sd/hcloud.json
- PROMETHEUS_HCLOUD_TOKEN=your-token
volumes:
- ./service-discovery:/etc/sd
To avoid the dependency on a shared filesystem between this service discovery and the Prometheus configuration directory, you are able to use the new HTTP service discovery starting with Prometheus >= v2.28, you just need to switch the engine for this service discovery:
hcloud-sd:
image: promhippie/prometheus-hcloud-sd:latest
restart: always
environment:
- PROMETHEUS_HCLOUD_LOG_PRETTY=true
+ - PROMETHEUS_HCLOUD_OUTPUT_ENGINE=http
- PROMETHEUS_HCLOUD_OUTPUT_FILE=/etc/sd/hcloud.json
- PROMETHEUS_HCLOUD_TOKEN=your-token
volumes:
- ./service-discovery:/etc/sd
To use the HTTP service discovery you just need to change the Prometheus configuration mentioned above a little bit:
scrape_configs:
- job_name: node
http_sd_configs:
- url: http://hcloud-sd:9000/sd
relabel_configs:
- source_labels: [__meta_hcloud_public_ipv4]
replacement: "${1}:9100"
target_label: __address__
- source_labels: [__meta_hcloud_datacenter]
target_label: datacenter
- source_labels: [__meta_hcloud_name]
target_label: instanceFinally the service discovery should be configured fine, let’s start this stack
with docker-compose], you just need to execute docker-compose up
within the directory where you have stored prometheus.yml and
docker-compose.yml. That’s all, the service discovery should be up and
running. You can access Prometheus at
http://localhost:9090.
Prometheus service discovery for Hetzner Cloud
Configuration
Environment variables
If you prefer to configure the service with environment variables you can see the available variables below, in case you want to configure multiple accounts with a single service you are forced to use the configuration file as the environment variables are limited to a single account. As the service is pretty lightweight you can even start an instance per account and configure it entirely by the variables, it’s up to you.
- PROMETHEUS_HCLOUD_LOG_LEVEL
- Only log messages with given severity, defaults to
info - PROMETHEUS_HCLOUD_LOG_PRETTY
- Enable pretty messages for logging, defaults to
false - 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_WEB_CONFIG
- Path to web-config file
- PROMETHEUS_HCLOUD_OUTPUT_ENGINE
- Enabled engine like file or http, defaults to
file - 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 - PROMETHEUS_HCLOUD_TOKEN
- Access token for the HetznerCloud API
- PROMETHEUS_HCLOUD_CONFIG
- Path to HetznerCloud configuration file
Web Configuration
If you want to secure the service by TLS or by some basic authentication you can
provide a YAML configuration file which follows the Prometheus
toolkit format. You can see a full configuration example within the
toolkit documentation.
Configuration file
Especially if you want to configure multiple accounts within a single service
discovery you got to use the configuration file. So far we support the file
formats JSON and YAML, if you want to get a full example configuration just
take a look at our repository, there you can always see the latest
configuration format. These example configurations include all available
options, they also include the default values.
Labels
__address____meta_hcloud_city__meta_hcloud_cores__meta_hcloud_country__meta_hcloud_cpu__meta_hcloud_datacenter__meta_hcloud_disk__meta_hcloud_image_name__meta_hcloud_image_type__meta_hcloud_ipv4_<name>__meta_hcloud_label_<name>__meta_hcloud_location__meta_hcloud_memory__meta_hcloud_name__meta_hcloud_os_flavor__meta_hcloud_os_version__meta_hcloud_project__meta_hcloud_public_ipv4__meta_hcloud_public_ipv6__meta_hcloud_status__meta_hcloud_storage__meta_hcloud_type
Metrics
- prometheus_hcloud_sd_request_duration_seconds{project}
- Histogram of latencies for requests to the Hetzner Cloud API
- prometheus_hcloud_sd_request_failures_total{project}
- Total number of failed requests to the Hetzner Cloud API