Health Checks¶

Craft Easy API provides health check endpoints for container orchestrators, load balancers, and monitoring systems.

Endpoints¶

`GET /health`¶

Simple liveness probe. Returns 200 OK if the process is running:

curl http://localhost:5001/health

{
  "status": "ok"
}

`GET /ready`¶

Readiness probe that verifies the application can serve traffic (database connected, etc.):

curl http://localhost:5001/ready

{
  "status": "ok"
}

`GET /admin/health/detailed`¶

Detailed health check that runs all registered health checks with individual status:

curl http://localhost:5001/admin/health/detailed

{
  "status": "ok",
  "checks": {
    "database": { "status": "ok", "duration_ms": 12 },
    "redis": { "status": "ok", "duration_ms": 3 }
  }
}

Possible statuses per check:

Status	Meaning
`ok`	Check passed
`failed`	Check returned an error
`timeout`	Check exceeded the timeout
`error`	Check threw an exception

Configuration¶

Setting	Default	Description
`HEALTH_CHECK_TIMEOUT_MS`	`5000`	Maximum time (ms) for each health check to complete

Health Check Registry¶

Register custom health checks for your application's dependencies:

from craft_easy.core.health import health_registry

async def check_external_api():
    response = await httpx.get("https://api.stripe.com/v1/health")
    if response.status_code != 200:
        raise Exception("Stripe API unavailable")

health_registry.register("stripe", check_external_api)

Registry API:

class HealthCheckRegistry:
    def register(self, name: str, check: Callable) -> None:
        """Register a named health check function."""

    async def run_all(self, timeout_ms: int = 5000) -> dict:
        """Run all checks with timeout, returns status per check."""

Container Orchestration¶

Kubernetes¶

livenessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /ready
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 5

Azure Container Apps¶

{
  "probes": [
    {
      "type": "liveness",
      "httpGet": { "path": "/health", "port": 8000 }
    },
    {
      "type": "readiness",
      "httpGet": { "path": "/ready", "port": 8000 }
    }
  ]
}

GCP Cloud Run¶

Cloud Run uses the default / or a configured startup probe:

startupProbe:
  httpGet:
    path: /health