ln-774-healthcheck-setup

intent

sets up three kubernetes-compliant health check endpoints (liveness, readiness, startup) for .NET or Python services. use this when deploying to kubernetes and you need probes to monitor app state, dependency health, and initialization progress. prevents cascading restarts by decoupling liveness from dependency checks.

inputs

context from ln-770 coordinator

• STACK: "dotnet" or "python" (required)
• PROJECT_ROOT: absolute path to project directory (required)
• DEPENDENCIES: list of detected services (PostgreSQL, MySQL, Redis, RabbitMQ, MongoDB, etc.)

external connections

• database connections (PostgreSQL, MySQL, MongoDB): connection strings from env or config
• Redis: connection string, default localhost:6379
• RabbitMQ: AMQP connection string
• http port: application listen port (5000 default for Python, 5000+ for .NET Kestrel)

runtime requirements

• .NET: AspNetCore.Diagnostics.HealthChecks nuget package and stack-specific extensions (AspNetCore.HealthChecks.NpgSql, AspNetCore.HealthChecks.Redis, etc.)
• Python: FastAPI or similar http framework, httpx or requests for health checks
• Kubernetes cluster: 1.16+ for startup probe support

procedure

phase 1: receive context and scan for existing health checks

1. accept context store from coordinator containing STACK, PROJECT_ROOT, DEPENDENCIES list
2. scan project for existing health check implementation
   • input: PROJECT_ROOT path
   • .NET: grep PROJECT_ROOT for "AddHealthChecks" or "MapHealthChecks" in Program.cs or Startup.cs
   • Python: grep PROJECT_ROOT for "/health" route in main app file or routers
   • output: boolean flag health_checks_exist
3. if health checks already exist, return early with {"status": "skipped", "reason": "health checks already configured"} and stop
4. detect dependencies by scanning project manifest files
   • input: PROJECT_ROOT, STACK
   • .NET: parse *.csproj for package references matching known dependency patterns
   • Python: parse requirements.txt or pyproject.toml for package names
   • output: list of detected dependencies (e.g., ["PostgreSQL", "Redis", "RabbitMQ"])

phase 2: design health check strategy

5. define three endpoint purposes and kubernetes probe mapping
   • input: detected dependencies list
   • output: endpoint specification
     • /health/live: liveness probe, responds 200 if app process alive (no dependency checks)
     • /health/ready: readiness probe, responds 200 only if all dependencies are healthy and accessible
     • /health/startup: startup probe, responds 200 only after initial warmup/initialization complete (K8s 1.16+)

phase 3: research current health check patterns

6. retrieve current documentation for health check implementation
   • input: STACK type
   • use MCP tools to fetch latest patterns for chosen stack:
     • .NET: "ASP.NET Core health checks Kubernetes probes" from /dotnet/aspnetcore context
     • Python: "FastAPI health check endpoint Kubernetes" from /tiangolo/fastapi context
   • output: current best-practice code snippets, response format, timing recommendations

phase 4: configure kubernetes probe timing

7. calculate probe timing parameters based on worst-case startup scenario
   • input: dependency count, typical connection pool warm-up time (estimate 100-200ms per dependency)
   • output: probe configuration dictionary
     • liveness: initialDelaySeconds=10, periodSeconds=10, timeoutSeconds=5, failureThreshold=3
     • readiness: initialDelaySeconds=5, periodSeconds=5, timeoutSeconds=3, failureThreshold=3
     • startup: initialDelaySeconds=0, periodSeconds=5, timeoutSeconds=3, failureThreshold=30
   • note: startup probe max wait = periodSeconds × failureThreshold = 5 × 30 = 150 seconds

phase 5: generate health check implementation

8. generate health check code for detected stack

   • input: STACK, detected dependencies, probe timing config
   • .NET output: create two files
     • Extensions/HealthCheckExtensions.cs: AddHealthChecks registration with dependency checks
     • HealthChecks/StartupHealthCheck.cs: custom IHealthCheck implementation for startup state
     • add nuget packages based on detected dependencies (AspNetCore.HealthChecks.NpgSql, AspNetCore.HealthChecks.Redis, etc.)
     • registration code: builder.Services.AddHealthCheckServices(builder.Configuration); and app.MapHealthCheckEndpoints();
   • Python output: create two files
     • routes/health.py: FastAPI router with three endpoints (/health/live, /health/ready, /health/startup)
     • services/health_checker.py: helper functions to verify each dependency (database ping, redis ping, etc.)
     • registration code: app.include_router(health_router)
   • output: file paths and registration code snippets

9. generate kubernetes manifest snippet for inclusion in deployment.yaml

   • input: probe timing config, app port
   • output: yaml block containing livenessProbe, readinessProbe, startupProbe specs with httpGet paths and parameters

phase 6: validate health checks

10. syntax validation

    • input: generated code files
    • .NET: run dotnet build --no-restore in PROJECT_ROOT
    • Python: run python -m py_compile routes/health.py services/health_checker.py
    • output: pass/fail status

11. endpoint functional test (local or containerized)

    • input: running app on configured port
    • execute: curl http://localhost:5000/health/live, curl http://localhost:5000/health/ready, curl http://localhost:5000/health/startup
    • output: http status codes (200 expected for all if dependencies available)

12. verify response format

    • input: response from /health/ready endpoint
    • expected json structure:

      {
        "status": "Healthy",
        "checks": {
          "database": { "status": "Healthy", "duration": "00:00:00.0234" },
          "redis": { "status": "Healthy", "duration": "00:00:00.0012" }
        },
        "totalDuration": "00:00:00.0250"
      }
      

    • output: validation pass/fail

13. dependency failure test

    • input: running app with access to at least one dependency
    • actions: stop/block dependency (e.g., docker stop postgres-container)
    • verify: /health/ready returns 503 Service Unavailable, /health/live still returns 200 OK
    • verify: after dependency restored, /health/ready returns 200 again
    • output: failure/recovery test result

14. return result to coordinator

    • input: all test results, file paths, packages added, registration code
    • output: structured json with status, file list, packages, registration code, and success message

decision points

if health checks already exist (phase 1, step 3)

• return {"status": "skipped"} and halt. do not overwrite or regenerate.

if STACK is "dotnet" (phase 5, step 8)

• generate C# implementation with AspNetCore.Diagnostics.HealthChecks
• check for NpgSql, MySql.Data, StackExchange.Redis, RabbitMQ.Client, MongoDB.Driver in csproj and add corresponding health check package if detected
• if none detected, include generic http health checks only

if STACK is "python" (phase 5, step 8)

• generate FastAPI router with async endpoint handlers
• check for psycopg2/asyncpg, mysql-connector-python, redis, pika/aio-pika, pymongo in requirements and add corresponding health check logic if detected

if probe timing tests timeout (phase 6, step 13)

• increase initialDelaySeconds by 5-10 seconds, retest, and report new timing to coordinator

if dependency health check fails (phase 6, step 12)

• check if dependency is required or optional: required means /health/ready must fail, optional means only log warning in /health/ready response

if app port is not 5000 (phase 6, step 11)

• use PROJECT_ROOT config file or environment variable to determine correct port, then adjust curl and kubernetes manifest accordingly

output contract

success case

return structured json to ln-770 coordinator:

{
  "status": "success",
  "stack": "dotnet | python",
  "files_created": [
    "Extensions/HealthCheckExtensions.cs",
    "HealthChecks/StartupHealthCheck.cs"
  ],
  "packages_added": [
    "AspNetCore.HealthChecks.NpgSql",
    "AspNetCore.HealthChecks.Redis"
  ],
  "registration_code": "builder.Services.AddHealthCheckServices(builder.Configuration);\napp.MapHealthCheckEndpoints();",
  "kubernetes_manifest": {
    "livenessProbe": {...},
    "readinessProbe": {...},
    "startupProbe": {...}
  },
  "endpoints": [
    {"path": "/health/live", "checks": []},
    {"path": "/health/ready", "checks": ["database", "redis"]},
    {"path": "/health/startup", "checks": ["warmup"]}
  ],
  "validation_results": {
    "syntax_check": "pass",
    "endpoint_tests": "pass",
    "response_format": "pass",
    "dependency_failure_test": "pass"
  },
  "message": "Configured health checks with liveness, readiness, and startup probes"
}

skipped case

{
  "status": "skipped",
  "reason": "health checks already configured in Extensions/HealthCheckExtensions.cs"
}

failure case

{
  "status": "error",
  "step": "phase 6, step 13",
  "reason": "dependency failure test timed out after 30s",
  "remediation": "increase initialDelaySeconds to 15 and retry"
}

file locations:

• .NET: Extensions/HealthCheckExtensions.cs, HealthChecks/StartupHealthCheck.cs relative to PROJECT_ROOT
• Python: routes/health.py, services/health_checker.py relative to PROJECT_ROOT
• kubernetes manifest: include in deployment.yaml spec.containers[].livenessProbe, readinessProbe, startupProbe sections

outcome signal

the skill worked if:

1. three endpoints are callable and respond with correct http status (200 for healthy states, 503 for degraded readiness)
2. liveness probe never checks dependencies (always 200 unless app process dead)
3. readiness probe returns 503 immediately when any critical dependency is unavailable or slow
4. startup probe blocks liveness/readiness until initial warmup (150s default) passes
5. response json includes "status" field and nested "checks" object with per-dependency health and duration metrics
6. kubernetes deployment manifests can be updated with the generated probe specs and pod scheduling respects probe outcomes
7. no manual probe configuration needed beyond pasting generated code and kubernetes yaml snippet
8. coordinator receives structured json output with file paths and registration code ready for commit