Health Checks

Open Inwoner provides several health check endpoints for monitoring and orchestration purposes. These endpoints allow you to verify the application’s health and readiness in different deployment scenarios.

Available Endpoints

`/_healthz/`

Reports all configured checks, including:

Database connection and permissions
Configured caches
Verification that all migrations have been executed

This is the most expensive check and suitable for the Kubernetes startup probe.

`/_healthz/livez/`

The cheapest check - it does not check any dependencies like the database or caches.

This endpoint is extremely suitable for:

HTTP liveness probe in Kubernetes
Docker engine health check

`/_healthz/readyz/`

A check slightly more expensive than the liveness subset. It verifies:

Database connection
Default cache connections

This endpoint is suitable for the readiness probe in Kubernetes.

Docker Compose Configuration

Docker Compose supports health checks via the healthcheck directive. Use the /_healthz/livez/ endpoint for basic health monitoring:

services:
  web:
    image: maykinmedia/open-inwoner:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/_healthz/livez/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 40s

Note

Docker Compose does not have separate liveness/readiness/startup probes like Kubernetes. The healthcheck directive serves as a general health check.

Kubernetes Configuration

Kubernetes provides three distinct probe types that can use different health check endpoints:

Startup Probe

Use /_healthz/ for the startup probe to ensure the application is fully initialized:

startupProbe:
  httpGet:
    path: /_healthz/
    port: 8000
  failureThreshold: 45
  periodSeconds: 10

Liveness Probe

Use /_healthz/livez/ for the liveness probe to detect if the application needs to be restarted:

livenessProbe:
  httpGet:
    path: /_healthz/livez/
    port: 8000
  initialDelaySeconds: 60
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

Readiness Probe

Use /_healthz/readyz/ for the readiness probe to control traffic routing:

readinessProbe:
  httpGet:
    path: /_healthz/readyz/
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 3

Response Format

All health check endpoints return an overview of the checks that have passed or failed. The response format depends on the Accept header:

text/html: Human-readable overview (default for browsers)
application/json: Machine-readable format (for monitoring tools)

You can force JSON output by appending ?format=json to any health check URL.

HTTP Status Codes

200 OK: All checks passed
500 Server Error: One or more checks failed

Troubleshooting

If health checks fail, examine the response body for details: