Skip to content

Health Checks (v4.5.0+)

Poweradmin can expose two endpoints that a monitoring system reads without logging in, so you find out that the database or the PowerDNS API has gone away before a user does.

Both are disabled by default. They answer without a session and without an API key, so turn on only the one you need and restrict it at your reverse proxy.

These endpoints report on Poweradmin itself. For PowerDNS server statistics, see the PowerDNS Server Status page instead.

Enabling

In config/settings.php:

'health' => [
    'enabled' => true,        // GET /api/health
    'ping_enabled' => true,   // GET /ping
    'db_timeout' => 2,        // seconds; how long the database check waits to connect
    'pdns_timeout' => 2,      // seconds; how long the PowerDNS check waits
],

In Docker, set PA_HEALTH_ENABLED=true and PA_HEALTH_PING_ENABLED=true. See Docker Installation.

Neither endpoint depends on api.enabled. You can run a health check with the API key system switched off entirely.

While a flag is off its endpoint returns 404, indistinguishable from a build that never had the feature.

GET /ping - liveness

Answers if the PHP process can serve a request. It touches nothing else, so it still answers while the database is down. Use it to decide whether to restart a container or pull an instance out of a load balancer.

$ curl -i https://dns.example.com/ping
HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Cache-Control: no-store

ok

GET /api/health - readiness

Reports whether Poweradmin can reach its dependencies. Use it to decide whether an instance should receive traffic.

$ curl -s https://dns.example.com/api/health
{"status":"ok","checks":{"database":"ok","pdns_api":"ok"}}

Returns 200 when healthy and 503 when any check failed:

$ curl -s -o /dev/null -w '%{http_code}\n' https://dns.example.com/api/health
503
{"status":"error","checks":{"database":"down","pdns_api":"ok"}}

Checks

Check Meaning
database ok if Poweradmin can open a connection and run a statement, otherwise down
pdns_api ok if the PowerDNS API answered, down if it did not, skipped if no PowerDNS API is configured

skipped is normal for installs using the database backend, where Poweradmin talks to the PowerDNS database directly and never calls the API. A skipped check never causes a 503.

If dns.backend is set to api and no PowerDNS API is configured, the check reports down rather than skipped. On that backend an unconfigured API means no zone operation can work, so the instance is not ready.

What the response does not contain

The endpoint is unauthenticated, so a check either passed or it did not. The response carries no version number, hostname, database driver, or error text.

The reason a check failed goes to the application's diagnostic log instead. That log is off by default, so set logging.type to native (PA_LOGGING_TYPE=native in Docker) to have connection errors written to the PHP error log:

'logging' => [
    'type' => 'native',
],

With diagnostic logging left at its null default, a failing check is reported as down and nothing is written anywhere. That is deliberate: an endpoint scraped every few seconds would otherwise fill the log with one line per scrape for as long as the outage lasts.

Response time

Both checks are bounded so an unreachable dependency cannot hold the request open for the operating system's TCP timeout. The database connect is capped by health.db_timeout and the PowerDNS call by health.pdns_timeout, both 2 seconds by default. The PowerDNS request retries once, so its worst case is roughly twice that value. Set your monitoring timeout above the sum.

Restricting access

Anyone who can reach these paths can call them. Deny them at the proxy and allow only your monitoring system.

nginx

location ~ ^/(ping|api/health)$ {
    allow 10.0.0.0/8;
    deny all;
    try_files $uri /index.php$is_args$args;
}

Apache

<LocationMatch "^/(ping|api/health)$">
    Require ip 10.0.0.0/8
</LocationMatch>

Token and result cache (v4.5.0+)

Two optional settings limit what an anonymous caller can trigger. Both are off by default.

'health' => [
    'enabled' => true,
    'token' => 'a-long-random-string',   // required in the X-Health-Token header
    'cache_seconds' => 10,               // reuse the last result for 10 seconds
],

With token set, /api/health answers 403 to any request without a matching X-Health-Token header and runs no check. /ping is not affected.

With cache_seconds above 0, the result is kept in a file in the system temp directory and reused until it is that many seconds old, so frequent scrapes make at most one database connect and one PowerDNS call per window. A failure is cached too, so the probe reports recovery up to that many seconds late.

In Docker, use PA_HEALTH_TOKEN (or PA_HEALTH_TOKEN__FILE for a secret file) and PA_HEALTH_CACHE_SECONDS.

Docker

The image ships a HEALTHCHECK that requests / (from 4.6.0, /ping when PA_HEALTH_PING_ENABLED=true), which succeeds even when the database is down. To make the container status reflect real readiness, enable the endpoint and override the healthcheck:

services:
  poweradmin:
    image: poweradmin/poweradmin:4.5.0
    environment:
      - PA_HEALTH_ENABLED=true
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost/api/health"]
      interval: 30s
      timeout: 5s
      retries: 3

With PA_HEALTH_TOKEN set in environment:, send it from the check, or the container reports unhealthy:

    healthcheck:
      test: ["CMD-SHELL", "curl -fsS -H \"X-Health-Token: $$PA_HEALTH_TOKEN\" http://localhost/api/health"]

A token read from PA_HEALTH_TOKEN__FILE is not visible to the healthcheck process; read the secret file in the command instead.

Kubernetes

Use /ping for liveness and /api/health for readiness. A failing dependency should stop traffic reaching the pod, not restart it:

env:
  - name: PA_HEALTH_ENABLED
    value: "true"
  - name: PA_HEALTH_PING_ENABLED
    value: "true"
livenessProbe:
  httpGet:
    path: /ping
    port: 80
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /api/health
    port: 80
  periodSeconds: 30
  timeoutSeconds: 5

With a token configured, add it to the readiness probe:

readinessProbe:
  httpGet:
    path: /api/health
    port: 80
    httpHeaders:
      - name: X-Health-Token
        value: a-long-random-string