ln-774-healthcheck-setup

Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-770-crosscutting-setup

Configures health check endpoints for Kubernetes probes and monitoring.

Overview

Phase 1: Receive Context + Identify Dependencies

Accept Context Store and scan for dependencies to monitor.

Required Context:

• STACK: .NET or Python
• PROJECT_ROOT: Project directory path

Idempotency Check:

• .NET: Grep for AddHealthChecks or MapHealthChecks
• Python: Grep for /health route
• If found: Return { "status": "skipped" }

Dependency Detection:

Phase 2: Design Health Check Strategy

Define three types of health endpoints per Kubernetes best practices.

Endpoint Types

When Each Probe Fails

Phase 3: Research Health Check Patterns

Use MCP tools for current documentation.

For .NET:

MCP ref: "ASP.NET Core health checks Kubernetes probes"
Context7: /dotnet/aspnetcore

For Python:

MCP ref: "FastAPI health check endpoint Kubernetes"
Context7: /tiangolo/fastapi

Key Patterns to Research:

1. Database health checks (connection pool)
2. Redis connectivity check
3. Custom health check implementation
4. Health check response writer customization

Phase 4: Configure Kubernetes Probes

Determine probe timing based on application characteristics.

Probe Configuration

Startup Probe Calculation:

Max startup time = initialDelaySeconds + (periodSeconds × failureThreshold)
Default: 0 + (5 × 30) = 150 seconds

Phase 5: Generate Implementation

.NET Output Files

Generation Process:

1. Use MCP ref for current ASP.NET Core health checks API
2. Generate HealthCheckExtensions with:
   • AddHealthChecks registration
   • Database health check (if detected)
   • Redis health check (if detected)
   • Custom StartupHealthCheck
3. Configure three endpoints with proper tags

Packages to Add:

• AspNetCore.HealthChecks.NpgSql (if PostgreSQL)
• AspNetCore.HealthChecks.Redis (if Redis)
• AspNetCore.HealthChecks.MySql (if MySQL)

Registration Code:

builder.Services.AddHealthCheckServices(builder.Configuration);
// ...
app.MapHealthCheckEndpoints();

Python Output Files

Generation Process:

1. Use MCP ref for FastAPI health patterns
2. Generate health router with:
   • /health/live endpoint (simple)
   • /health/ready endpoint (with dependency checks)
   • /health/startup endpoint
3. Generate health_checker service for dependency verification

Registration Code:

from routes.health import health_router
app.include_router(health_router)

Kubernetes Manifest Snippet

Generate for inclusion in deployment.yaml:

livenessProbe:
  httpGet:
    path: /health/live
    port: 5000
  initialDelaySeconds: 10
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health/ready
    port: 5000
  initialDelaySeconds: 5
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 3

startupProbe:
  httpGet:
    path: /health/startup
    port: 5000
  periodSeconds: 5
  failureThreshold: 30

Phase 6: Validate

Validation Steps:

1. Syntax check:

   • .NET: dotnet build --no-restore
   • Python: python -m py_compile routes/health.py

2. Endpoint test:

   curl http://localhost:5000/health/live
   curl http://localhost:5000/health/ready
   curl http://localhost:5000/health/startup
   

3. Verify response format:

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

4. Dependency failure test:

   • Stop database
   • Verify /health/ready returns 503
   • Verify /health/live still returns 200

Return to Coordinator

{
  "status": "success",
  "files_created": [
    "Extensions/HealthCheckExtensions.cs",
    "HealthChecks/StartupHealthCheck.cs"
  ],
  "packages_added": [
    "AspNetCore.HealthChecks.NpgSql"
  ],
  "registration_code": "builder.Services.AddHealthCheckServices(configuration);",
  "message": "Configured health checks with liveness, readiness, and startup probes"
}

Reference Links

• ASP.NET Core Health Checks
• Kubernetes Probes
• AWS EKS Health Check Best Practices

Critical Rules

• Three separate endpoints — /health/live, /health/ready, /health/startup per Kubernetes best practices
• Liveness must not check dependencies — only confirms app is alive (avoids cascade restarts)
• Readiness checks all dependencies — DB, Redis, RabbitMQ connectivity verified
• Auto-detect dependencies from project files — scan csproj/requirements for known packages
• Idempotent — if AddHealthChecks/MapHealthChecks or /health route exists, return status: "skipped"

Definition of Done

• Context Store received (stack, project root)
• Dependencies detected (PostgreSQL, MySQL, Redis, RabbitMQ, MongoDB)
• Health check endpoints generated (live, ready, startup) for detected stack
• Kubernetes probe manifest snippet generated with proper timing parameters
• Syntax validated (dotnet build or py_compile)
• Structured JSON response returned to ln-770 coordinator

Version: 2.0.0 Last Updated: 2026-01-10