Skip to content

Health Checks

Health Endpoints and Kubernetes Probes

Document Version: 1.0.0
Last Updated: 2026-02-10

1. Health Endpoint Overview

Component Endpoint Method Auth Required
API Server /api/v1/health GET No
API Server /api/v1/health/database GET No
API Server /api/v1/health/system GET Bearer Token
OCSP Responder /health GET No
OCSP Responder /ready GET No
OCSP Responder /live GET No

2. API Server Health

Basic Health Check

GET /api/v1/health HTTP/1.1
Host: vault.example.com

Response 200 OK: 

{
  "status": "healthy",
  "version": "1.8.0",
  "components": {
    "database": "healthy",
    "redis": "healthy",
    "ocsp": "healthy"
  }
}

Response 503 Service Unavailable: 

{
  "status": "unhealthy",
  "version": "1.8.0",
  "components": {
    "database": "unhealthy",
    "redis": "healthy",
    "ocsp": "healthy"
  }
}

Database Health

GET /api/v1/health/database HTTP/1.1

Response: 

{
  "status": "healthy",
  "latency_ms": 2,
  "connections": {
    "active": 5,
    "idle": 10,
    "max": 100
  }
}

System Health (Authenticated)

GET /api/v1/health/system HTTP/1.1
Authorization: Bearer <admin-token>

Response: 

{
  "status": "healthy",
  "version": "1.8.0",
  "uptime_seconds": 864000,
  "components": {
    "database": {
      "status": "healthy",
      "latency_ms": 2
    },
    "redis": {
      "status": "healthy",
      "latency_ms": 1
    },
    "ocsp": {
      "status": "healthy",
      "latency_ms": 5
    },
    "license": {
      "status": "valid",
      "expires_at": "2027-02-10T00:00:00Z",
      "tier": "enterprise"
    }
  },
  "statistics": {
    "total_secrets": 1250,
    "total_certificates": 340,
    "active_agents": 15,
    "active_users": 42
  }
}

3. OCSP Responder Health

Readiness Probe

GET /ready HTTP/1.1

Returns 200 OK when the OCSP responder is ready to process requests (database connected, signing key loaded).

Liveness Probe

GET /live HTTP/1.1

Returns 200 OK when the OCSP responder process is alive. This probe does not verify database connectivity.

Full Health

GET /health HTTP/1.1

Response: 

{
  "status": "healthy",
  "components": {
    "database": "connected",
    "signing_key": "loaded",
    "ca_certificates": 2
  }
}

4. Kubernetes Probe Configuration

# API Server
livenessProbe:
  httpGet:
    path: /api/v1/health
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 30
  failureThreshold: 3
  timeoutSeconds: 10

readinessProbe:
  httpGet:
    path: /api/v1/health
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 10
  failureThreshold: 3
  timeoutSeconds: 5

startupProbe:
  httpGet:
    path: /api/v1/health
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 5
  failureThreshold: 30
  timeoutSeconds: 5

# OCSP Responder
livenessProbe:
  httpGet:
    path: /live
    port: 8081
  periodSeconds: 30
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /ready
    port: 8081
  periodSeconds: 10
  failureThreshold: 3

5. Health Check Script

For on-premise deployments, use this script for automated health verification:

#!/bin/bash
# mazevault-health-check.sh

BASE_URL="${MAZEVAULT_URL:-https://localhost}"

# Check API health
api_status=$(curl -sk "$BASE_URL/api/v1/health" -o /dev/null -w '%{http_code}')
if [ "$api_status" != "200" ]; then
  echo "CRITICAL: API Server unhealthy (HTTP $api_status)"
  exit 2
fi

# Check OCSP health
ocsp_status=$(curl -sk "$BASE_URL/ocsp/health" -o /dev/null -w '%{http_code}' 2>/dev/null)
if [ "$ocsp_status" != "200" ]; then
  echo "WARNING: OCSP Responder unhealthy (HTTP $ocsp_status)"
  exit 1
fi

echo "OK: All components healthy"
exit 0