Prometheus: Hetzner Service Discovery

A server to provide automatic node discovery for Hetzner Cloud to Prometheus via HTTP service discovery.

In contrary to the integrated Hetzner SD configuration, this lets you use internal IPs and filter the node list using Hetzner labels or node filters, for example.

Installation

The easiest option will be using our Docker image matchory/hetzner-cloud-prometheus-sd:

docker run -p 127.0.0.1:7764:7764 matchory/hetzner-cloud-prometheus-sd --hetzner-api-token $HETZNER_API_TOKEN

You can also install the npm package globally:

npx @matchory/hetzner-cloud-prometheus-sd --hetzner-api-token $HETZNER_API_TOKEN

Usage

Upon starting the server, it will continuously synchronize its list of Hetzner cloud nodes with the Hetzner API, and return those to requests on the /sd endpoint. Additionally, the server also provides its own metrics endpoint.

Configuration

The server may be configured using command-line options, environment variables, or its configuration file. The following table shows all available settings:

| CLI option | Environment variable | Default value | Description | |:---------------------------|:-------------------------------|---------------|--------------------------------------------------------------------------------------------------------------------------| | -t, --api-token | HETZNER_SD_API_TOKEN | - | API token obtained from Hetzner Cloud (required). | | -h, --hostname | HETZNER_SD_HOSTNAME | localhost | Hostname to listen on. | | -a, --auth-bearer | HETZNER_SD_AUTH_BEARER | - | Bearer token to verify on incoming requests. Mutually exclusive with --auth-basic. | | -A, --auth-basic | HETZNER_SD_AUTH_BASIC | - | Basic auth credentials to verify on incoming requests, provided as user:pass. Mutually exclusive with --auth-bearer. | | -p, --port | HETZNER_SD_PORT | 7764 | Port to listen on. | | -H, --https | HETZNER_SD_HTTPS | false | Use HTTPS for the listening socket. Required for mTLS. | | --m-tls-ca | HETZNER_SD_MTLS_CA | - | Path to the mTLS certificate authority file. Ignored unless https is enabled. | | -r, --refresh-interval | HETZNER_SD_REFRESH_INTERVAL | 30000 (30s) | How often to synchronize with the Hetzner API in ms. | | --metrics-endpoint | HETZNER_SD_METRICS_ENDPOINT | /metrics | Endpoint to provide server metrics on. | | --node-port | HETZNER_SD_NODE_PORT | 9090 | Port on the nodes Prometheus should connect to. | | --node-network | HETZNER_SD_NODE_NETWORK | - | Name, ID, or CIDR range of the network to prefer when resolving nodes. If omitted, the public IP will be preferred. | | --node-label-prefix | HETZNER_SD_NODE_LABEL_PREFIX | hetzner | Prefix for labels attached to discovered nodes- | | --log-level | HETZNER_SD_LOG_LEVEL | debug | Log level for the server (must be one of debug, info, warn or error). | | --debug | HETZNER_SD_DEBUG | false | Enable debug mode. This will also include additional debugging information in HTTP responses. |

Note:
You can provide token parameters in secret files using the environment variables with a _FILE suffix, e.g. HETZNER_SD_API_TOKEN_FILE. This variable is expected to contain an absolute path to a file on the filesystem which contains the secret. Trailing whitespace will be removed; the secret will be read once, and cached for the runtime of the server. This works for the API token and authentication credentials, so currently we support the following secret files:

• HETZNER_SD_API_TOKEN_FILE
• HETZNER_SD_AUTH_BEARER_FILE
• HETZNER_SD_AUTH_BASIC_FILE

Development

For local development, you'll want to use yarn dev to compile the TypeScript sources and start the server.

Contributing

We welcome all contributions. If you need help or would like to see a feature implemented, please get in touch.

Releasing

To publish a new release, use the np utility on the command line.