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 exporter 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 exporter based on a static configuration with the container name as a hostname:

global:
  scrape_interval: 1m
  scrape_timeout: 10s
  evaluation_interval: 1m

scrape_configs:
- job_name: hetzner
  static_configs:
  - targets:
    - hetzner_exporter:9502

After 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 exporter. Don’t forget to update the environment variables with the required credentials.

version: '2'

volumes:
  prometheus:

services:
  prometheus:
    image: prom/prometheus:latest
    restart: always
    ports:
      - 9090:9090
    volumes:
      - prometheus:/prometheus
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  hetzner_exporter:
    image: promhippie/hetzner-exporter:latest
    restart: always
    environment:
      - HETZNER_EXPORTER_USERNAME=#ws+qOeMD4UP
      - HETZNER_EXPORTER_PASSWORD=CNFPCgivAAqWu613
      - HETZNER_EXPORTER_LOG_PRETTY=true

Since 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:

  hetzner_exporter:
-   image: promhippie/hetzner-exporter:latest
+   image: promhippie/hetzner-exporter:1.0.0
    restart: always
    environment:
      - HETZNER_EXPORTER_USERNAME=#ws+qOeMD4UP
      - HETZNER_EXPORTER_PASSWORD=CNFPCgivAAqWu613
      - HETZNER_EXPORTER_LOG_PRETTY=true

If you want to access the exporter directly you should bind it to a local port, otherwise only Prometheus will have access to the exporter. For debugging purpose or just to discover all available metrics directly you can apply this change to your docker-compose.yml, after that you can access it directly at http://localhost:9502/metrics:

  hetzner-exporter:
    image: promhippie/hetzner-exporter:latest
    restart: always
+   ports:
+     - 127.0.0.1:9502:9502
    environment:
      - HETZNER_EXPORTER_USERNAME=#ws+qOeMD4UP
      - HETZNER_EXPORTER_PASSWORD=CNFPCgivAAqWu613
      - HETZNER_EXPORTER_LOG_PRETTY=true

If you want to secure the access to the exporter 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:

  hetzner_exporter:
    image: promhippie/hetzner-exporter:latest
    restart: always
    environment:
+     - HETZNER_EXPORTER_WEB_CONFIG=path/to/web-config.json
      - HETZNER_EXPORTER_USERNAME=#ws+qOeMD4UP
      - HETZNER_EXPORTER_PASSWORD=CNFPCgivAAqWu613
      - HETZNER_EXPORTER_LOG_PRETTY=true

If you want to provide the required secrets from a file it’s also possible. For this use case you can write the secret to a file on any path and reference it with the following format:

  hetzner_exporter:
    image: promhippie/hetzner-exporter:latest
    restart: always
    environment:
-     - HETZNER_EXPORTER_USERNAME=#ws+qOeMD4UP
-     - HETZNER_EXPORTER_PASSWORD=CNFPCgivAAqWu613
+     - HETZNER_EXPORTER_USERNAME=file://path/to/secret/file/with/username
+     - HETZNER_EXPORTER_PASSWORD=file://path/to/secret/file/with/password
      - HETZNER_EXPORTER_LOG_PRETTY=true

Finally the exporter 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 the prometheus.yml and docker-compose.yml.

That’s all, the exporter should be up and running. Have fun with it and hopefully you will gather interesting metrics and never run into issues. You can access the exporter at http://localhost:9502/metrics and Prometheus at http://localhost:9090.

Configuration

HETZNER_EXPORTER_LOG_LEVEL: Only log messages with given severity, defaults to info
HETZNER_EXPORTER_LOG_PRETTY: Enable pretty messages for logging, defaults to false
HETZNER_EXPORTER_WEB_ADDRESS: Address to bind the metrics server, defaults to 0.0.0.0:9502
HETZNER_EXPORTER_WEB_PATH: Path to bind the metrics server, defaults to /metrics
HETZNER_EXPORTER_WEB_PPROF: Enable pprof debugging for server, defaults to false
HETZNER_EXPORTER_WEB_TIMEOUT: Server metrics endpoint timeout, defaults to 10s
HETZNER_EXPORTER_WEB_CONFIG: Path to web-config file
HETZNER_EXPORTER_REQUEST_TIMEOUT: Request timeout as duration, defaults to 5s
HETZNER_EXPORTER_USERNAME: Username for the Hetzner API
HETZNER_EXPORTER_PASSWORD: Password for the Hetzner API
HETZNER_EXPORTER_COLLECTOR_SERVERS: Enable collector for servers, defaults to true
HETZNER_EXPORTER_COLLECTOR_SSH_KEYS: Enable collector for SSH keys, defaults to true
HETZNER_EXPORTER_COLLECTOR_STORAGEBOXES: Enable collector for Storageboxes, defaults to false

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.

Metrics

You can a rough list of available metrics below, additionally to these metrics you will always get the standard metrics exported by the Golang client of Prometheus. If you want to know more about these standard metrics take a look at the process collector and the Go collector.

hetzner_request_duration_seconds{collector}: Histogram of latencies for requests to the api per collector
hetzner_request_failures_total{collector}: Total number of failed requests to the api per collector
hetzner_server_cancelled{id, name, datacenter}: If 1 the server have been cancelled, 0 otherwise
hetzner_server_flatrate{id, name, datacenter}: If 1 the server got a flatrate enabled, 0 otherwise
hetzner_server_paid_timestamp{id, name, datacenter}: Timestamp of the date until server is paid
hetzner_server_running{id, name, datacenter}: If 1 the server is running, 0 otherwise
hetzner_server_traffic_bytes{id, name, datacenter}: Amount of included traffic for the server
hetzner_ssh_key{name, type, size, fingerprint}: Information about SSH keys in your Hetzner robot
hetzner_storagebox_cancelled{id, name, location, login}: If 1 the storagebox have been cancelled, 0 otherwise
hetzner_storagebox_data{id, name, location, login}: Used storage by files for the storagebox in MB
hetzner_storagebox_external{id, name, location, login}: If 1 the storagebox can be accessed from external, 0 otherwise
hetzner_storagebox_locked{id, name, location, login}: If 1 the storagebox have been locked, 0 otherwise
hetzner_storagebox_paid{id, name, location, login}: Timestamp of the date until storagebox is paid
hetzner_storagebox_quota{id, name, location, login}: Available storage for the storagebox in MB
hetzner_storagebox_samba{id, name, location, login}: If 1 the storagebox can be accessed via samba, 0 otherwise
hetzner_storagebox_snapshots{id, name, location, login}: Used storage by snapshots for the storagebox in MB
hetzner_storagebox_ssh{id, name, location, login}: If 1 the storagebox can be accessed via ssh, 0 otherwise
hetzner_storagebox_usage{id, name, location, login}: Used storage for the storagebox in MB
hetzner_storagebox_webdav{id, name, location, login}: If 1 the storagebox can be accessed via webdav, 0 otherwise
hetzner_storagebox_zfs{id, name, location, login}: If 1 the zfs directory is visible, 0 otherwise

Kubernetes Back to Top

Kubernetes

Currently we are covering the most famous installation methods on Kubernetes, you can choose between Kustomize and Helm.

Kustomize

We won’t cover the installation of Kustomize within this guide, to get it installed and working please read the upstream documentation. After the installation of Kustomize you just need to prepare a kustomization.yml wherever you like similar to this:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: hetzner-exporter

resources:
  - github.com/promhippie/hetzner_exporter//deploy/kubernetes?ref=master

configMapGenerator:
  - name: hetzner-exporter
    behavior: merge
    literals: []

secretGenerator:
  - name: hetzner-exporter
    behavior: merge
    literals: []

After that you can simply execute kustomize build | kubectl apply -f - to get the manifest applied. Generally it’s best to use fixed versions of the container images, this can be done quite easy, you just need to append this block to your kustomization.yml to use this specific version:

images:
  - name: quay.io/promhippie/hetzner-exporter
    newTag: 1.1.0

After applying this manifest the exporter should be directly visible within your Prometheus instance if you are using the Prometheus Operator as these manifests are providing a ServiceMonitor.

Helm

We won’t cover the installation of Helm within this guide, to get it installed and working please read the upstream documentation. After the installation of Helm you just need to execute the following commands:

helm repo add promhippie https://promhippie.github.io/charts
helm show values promhippie/hetzner-exporter
helm install hetzner-exporter promhippie/hetzner-exporter

You can also watch that available values and generally the details of the chart provided by us within our chart repository or on Artifacthub.

After applying this manifest the exporter should be directly visible within your Prometheus instance depending on your installation if you enabled the annotations or the service monitor.

Hetzner Exporter