Skip to main content

Health Check API

The health check endpoint provides a simple way to verify that the application is running and responsive.

Endpoint​

GET /api/health

Response​

Success Response​

Status Code: 200 OK

Response Body:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "checks": {
    "kubernetes": {
      "status": "up",
      "latency": 45
    }
  }
}

Unhealthy Response​

Status Code: 503 Service Unavailable

Response Body:

{
  "status": "unhealthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "checks": {
    "kubernetes": {
      "status": "down",
      "latency": 5000,
      "error": "Failed to connect to Kubernetes API"
    }
  }
}

Response Fields​

FieldTypeDescription
statusstringOverall health status: "healthy" or "unhealthy"
timestampstringISO 8601 timestamp of the health check
checks.kubernetes.statusstringKubernetes API status: "up" or "down"
checks.kubernetes.latencynumberResponse time in milliseconds
checks.kubernetes.errorstringError message (only present when status is "down")

Usage​

Kubernetes Liveness Probe​

Use the health check endpoint in your Kubernetes deployment for liveness probes:

livenessProbe:
  httpGet:
    path: /api/health
    port: 3000
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

Kubernetes Readiness Probe​

Use the health check endpoint for readiness probes:

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

Docker Health Check​

Add a health check to your Docker container:

HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:3000/api/health || exit 1

Manual Testing​

Test the health check endpoint manually:

curl http://localhost:3000/api/health

Behavior​

  • The endpoint checks Kubernetes API connectivity by listing namespaces
  • Returns HTTP 200 when the Kubernetes API is reachable
  • Returns HTTP 503 when the Kubernetes API is unreachable
  • Includes latency metrics in the response
  • Has a 5-second timeout for health checks
  • Suitable for Kubernetes liveness and readiness probes

Troubleshooting​

Health Check Fails​

If the health check endpoint returns an error or times out:

  1. Check if the application is running:

    kubectl get pods -l app=kube-ingress-dash

  2. Check application logs:

    kubectl logs -l app=kube-ingress-dash

  3. Verify port configuration:

    • Default port is 3000
    • Check PORT environment variable if customized

  4. Check resource limits:

    • Application may be OOMKilled or CPU throttled
    • Review resource requests and limits

Probe Configuration Issues​

If Kubernetes probes are failing:

  • Increase initialDelaySeconds: Application may need more time to start
  • Increase timeoutSeconds: Network latency may cause timeouts
  • Adjust failureThreshold: Reduce false positives during high load

Best Practices​

  1. Set appropriate timeouts: Balance between quick failure detection and false positives
  2. Use different settings for liveness vs readiness: Readiness can be more aggressive
  3. Monitor probe failures: Set up alerts for repeated probe failures
  4. Test probe configuration: Verify probes work before deploying to production
Last updated on by Piotr Boruc