Skip to content
PowerDNS server container with multiple backends and metrics exported for Prometheus.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

PowerDNS with various backends

This image provides a reasonably small PowerDNS setup, based on the Alpine docker images. It supports the following backends out of the box:

It also provides Prometheus metrics for simple monitoring of the server. This was done to provide an out-of-the-box container to use in Kubernetes.


The image will run with the random backend, providing random DNS records for and Prometheus metrics on port 9120. Run with:

docker run -d --rm -p 1053:53/udp -p 1053:53 -p 9120:9120 synyx/pdns

PowerDNS should be answering queries shortly after:

dig -p 1053 +short @localhost

The Prometheus metrics are also available:

curl localhost:9120/metrics


Configuration for PowerDNS can be done in two ways.

The first & most simple is via environment variables. All possible settings for the PowerDNS server can be set by making the setting name all uppercase, replacing - with _ and prefixing it with PDNS_. For example, to configure MySQL backend, you can do the following:

docker run -d --rm -p 1053:53/udp -p 1053:53 -p 9120:9120 \
  -e PDNS_LAUNCH=gmysql \
  -e \
  -e PDNS_GMYSQL_USER=pdns \

If you want to debug the configuration that is done via environment variables, you can set the variable PDNS_DEBUG_ENV=true and the startup scripts will dump the environment and generated configuration to stderr. CAUTION: This can expose credentials in the log output and should therefore not be used on production systems.

The second option is, to simply mount a PowerDNS configuration file to /etc/pdns/pdns.conf or /etc/pdns/pdns.d/myconfig.conf. The default configuration will pick up all config files in /etc/pdns/pdns.d:

docker run -d --rm -p 1053:53/udp -p 1053:53 -p 9120:9120 \
  -v ./myconfig.conf:/etc/pdns/pdns.d/myconfig.conf

The Prometheus exporter exposes only two environment variables for configuration right now:

  • EXPORTER_LISTEN_ADDRESS to set a Golang compatible bind address specification (e.g. EXPORTER_LISTEN_ADDRESS= The default is simply :9120, listening on all interfaces on port 9120.
  • EXPORTER_TELEMETRY_PATH to set the HTTP path, metrics are exposed at (e.g. EXPORTER_TELEMETRY_PATH=/newmetrics). The default is to expose at /metrics.

Design & Caveats

While the Docker design philosophy is run a single process, we wanted to have out-of-the-box metrics support. Since PowerDNS exposes the internal metrics mainly via an UNIX socket, the decision was made to use runit to run PowerDNS and the Prometheus exporter side by side.

The caveat is, that now the container won't simply exit or crash when PowerDNS is misconfigured. Since this container is targeting Kubernetes, this issue can be remedied by simply applying an in-container health check by executing pdns_control rping periodically.


You can’t perform that action at this time.