klod68/health-check-endpoint

---

name: health-check-endpoint description: "Use when deploying an ASP.NET Core application to Azure App Service, Kubernetes, or any cloud platform that requires health probes, or when load balancers need to route around unhealthy instances and deployment slots must verify readiness before traffic swap. Covers AddHealthChecks registration, liveness vs readiness probe separation with tag-based filtering, custom IHealthCheck implementations, structured JSON response format, and platform-specific configuration for Azure App Service, Kubernetes, and Docker Compose. Domain: Cloud Readiness, Observability. Level: Foundational. Tags: health-check, cloud-native, monitoring, azure, kubernetes, observability."

Health Check Endpoint

Problem

Cloud platforms (Azure App Service, Kubernetes, AWS ELB) need to know if your application is alive and ready to serve traffic. Without a health endpoint:

• Load balancers can't route around unhealthy instances
• Auto-scaling can't detect degraded instances
• Deployment slots can't verify a new version is ready before swapping
• Monitoring tools have no structured health signal

Solution: /health Endpoint with ASP.NET Core Health Checks

Minimal Setup (2 lines)

// In Program.cs — Service registration
builder.Services.AddHealthChecks();

// In Program.cs — Endpoint mapping
app.MapHealthChecks("/health").AllowAnonymous();

This returns:

• 200 OK with body Healthy when the app is running
• 503 Service Unavailable when any check fails

Why .AllowAnonymous()

Health endpoints are probed by infrastructure (load balancers, orchestrators) that doesn't authenticate. Without AllowAnonymous(), probes get 401 and the app is marked unhealthy.

Implementation Tiers

Tier 1: Basic liveness (is the process alive?)

builder.Services.AddHealthChecks();
app.MapHealthChecks("/health").AllowAnonymous();

Tier 2: Dependency checks (can the app do useful work?)

builder.Services.AddHealthChecks()
    .AddSqlServer(connectionString, name: "database", tags: ["ready"])
    .AddRedis(redisConnectionString, name: "cache", tags: ["ready"])
    .AddUrlGroup(new Uri("https://api.external.com/ping"), name: "external-api", tags: ["ready"]);

Tier 3: Separate liveness and readiness endpoints

// Liveness: is the process alive? (no dependency checks)
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = _ => false  // No checks — just confirms the process is running
}).AllowAnonymous();

// Readiness: can the app serve requests? (checks dependencies)
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready")
}).AllowAnonymous();

Tier 4: Custom health check

public class DiskSpaceHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken ct = default)
    {
        var drive = new DriveInfo(Path.GetPathRoot(Environment.CurrentDirectory)!);
        var freeGb = drive.AvailableFreeSpace / (1024.0 * 1024 * 1024);

        return Task.FromResult(freeGb switch
        {
            < 1 => HealthCheckResult.Unhealthy($"Low disk space: {freeGb:F1} GB"),
            < 5 => HealthCheckResult.Degraded($"Disk space warning: {freeGb:F1} GB"),
            _ => HealthCheckResult.Healthy($"Disk space OK: {freeGb:F1} GB")
        });
    }
}

// Register
builder.Services.AddHealthChecks()
    .AddCheck<DiskSpaceHealthCheck>("disk-space", tags: ["ready"]);

Tier 5: Structured JSON response

app.MapHealthChecks("/health", new HealthCheckOptions
{
    ResponseWriter = async (context, report) =>
    {
        context.Response.ContentType = "application/json";
        var result = new
        {
            status = report.Status.ToString(),
            duration = report.TotalDuration,
            checks = report.Entries.Select(e => new
            {
                name = e.Key,
                status = e.Value.Status.ToString(),
                duration = e.Value.Duration,
                description = e.Value.Description,
                exception = e.Value.Exception?.Message
            })
        };
        await context.Response.WriteAsJsonAsync(result);
    }
}).AllowAnonymous();

Response:

{
  "status": "Healthy",
  "duration": "00:00:00.0234567",
  "checks": [
    { "name": "database", "status": "Healthy", "duration": "00:00:00.0120000" },
    { "name": "cache", "status": "Healthy", "duration": "00:00:00.0050000" }
  ]
}

Platform Configuration

Azure App Service

In Azure Portal → App Service → Health check:

• Path: /health
• Threshold: 3 failed probes before marking unhealthy
• Probe interval: 30 seconds (default, not configurable)

Kubernetes

livenessProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 15

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10

Docker Compose

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 30s
  timeout: 10s
  retries: 3

Required Packages

<!-- Core (always needed) -->
<PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="9.0.0" />

<!-- Database checks (optional) -->
<PackageReference Include="AspNetCore.HealthChecks.SqlServer" Version="8.0.0" />
<PackageReference Include="AspNetCore.HealthChecks.Redis" Version="8.0.0" />
<PackageReference Include="AspNetCore.HealthChecks.Uris" Version="8.0.0" />

Note: AddHealthChecks() is included in the ASP.NET Core shared framework — no extra package needed for basic use.

When to Use

• Always. Every web application deployed to a cloud platform should have a health endpoint.

When NOT to Use

• Console applications or background workers (use IHostedService health reporting instead)
• Applications behind API gateways that do their own health probing (still useful, just not platform-facing)

Gotchas

1. Don't put heavy checks in liveness: Liveness probes run frequently. A slow database query in a liveness probe can cause false unhealthy signals. Put dependency checks in readiness only.
2. Timeout your checks: If a dependency check hangs, the health endpoint hangs. Set timeout in AddCheck options.
3. Don't expose sensitive data: The default response is just Healthy/Unhealthy. JSON responses with exception messages should only be exposed on internal endpoints.
4. Cache results: For expensive checks, use HealthCheckRegistration.Delay and Period to avoid running on every probe.
5. Test it: Include /health in your integration test suite (see Integration Testing with WebApplicationFactory skill).

Related Skills

• Multi-Stage CI/CD Pipeline (post-deploy health verification)
• Integration Testing with WebApplicationFactory (test the health endpoint)