Health Checks, Readiness and Liveness Probes

Health checks give Kubernetes, load balancers, and monitoring systems a programmatic way to determine whether an API instance is healthy and ready to serve traffic. ASP.NET Core’s built-in health check system supports multiple check types (database connectivity, external services, custom business logic) and exposes them via HTTP endpoints. Kubernetes uses two separate probes: the liveness probe (is the process alive?) restarts a container on failure, and the readiness probe (is it ready to serve traffic?) temporarily removes it from load balancing. Getting these right prevents both stuck processes and premature traffic routing.

Health Check Configuration #

// dotnet add package AspNetCore.HealthChecks.SqlServer
// dotnet add package AspNetCore.HealthChecks.Redis

// ── Program.cs — register health checks ───────────────────────────────────
builder.Services
    .AddHealthChecks()
    // Database connectivity check
    .AddSqlServer(
        builder.Configuration.GetConnectionString("Default")!,
        name: "database",
        tags: ["ready"])   // only included in readiness check

    // Redis check
    .AddRedis(
        builder.Configuration.GetConnectionString("Redis")!,
        name: "redis",
        tags: ["ready"])

    // Custom business logic check
    .AddCheck<RequiredSeedDataHealthCheck>("seed-data", tags: ["ready"])

    // Self (always healthy — for liveness)
    .AddCheck("self", () => HealthCheckResult.Healthy(), tags: ["live"]);

// ── Map health check endpoints ─────────────────────────────────────────────
// Liveness — is the process alive? (no DB check — it might be the DB that's broken)
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("live"),
    ResponseWriter = WriteHealthResponse,
});

// Readiness — is it ready to serve requests? (includes DB, Redis checks)
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready") || check.Tags.Contains("live"),
    ResponseWriter = WriteHealthResponse,
});

// Full health endpoint — for internal monitoring only (protect from public)
app.MapHealthChecks("/health", new HealthCheckOptions
{
    ResponseWriter = WriteHealthResponse,
}).RequireAuthorization("HealthCheckPolicy");

// ── Custom JSON response writer ────────────────────────────────────────────
static Task WriteHealthResponse(HttpContext context, HealthReport report)
{
    context.Response.ContentType = "application/json";
    var result = JsonSerializer.Serialize(new
    {
        status     = report.Status.ToString(),
        duration   = report.TotalDuration.TotalMilliseconds,
        checks     = report.Entries.Select(e => new
        {
            name     = e.Key,
            status   = e.Value.Status.ToString(),
            duration = e.Value.Duration.TotalMilliseconds,
            error    = e.Value.Exception?.Message,
        })
    });
    return context.Response.WriteAsync(result);
}

Custom Health Check #

// ── Custom health check — verifies required seed data exists ──────────────
public class RequiredSeedDataHealthCheck(AppDbContext db) : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken ct = default)
    {
        try
        {
            var roleCount = await db.Roles.CountAsync(ct);
            if (roleCount == 0)
                return HealthCheckResult.Degraded(
                    "Required roles are missing — seed data may not have been applied.");

            var adminExists = await db.Users
                .AnyAsync(u => db.UserRoles
                    .Any(ur => ur.UserId == u.Id &&
                               db.Roles.Any(r => r.Id == ur.RoleId && r.Name == "Admin")), ct);

            return adminExists
                ? HealthCheckResult.Healthy("Seed data is present.")
                : HealthCheckResult.Degraded("Admin user is missing from seed data.");
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy("Seed data check failed.", ex);
        }
    }
}

// Register: builder.Services.AddScoped<RequiredSeedDataHealthCheck>();
// Apply:    .AddCheck<RequiredSeedDataHealthCheck>("seed-data", tags: ["ready"])

Common Mistakes #

Mistake 1 — Including database check in liveness probe (unnecessary container restarts) #

❌ Wrong — liveness includes SQL check; DB is slow; container marked unhealthy and restarted unnecessarily.

✅ Correct — liveness checks process health only; readiness includes DB, Redis, external services.

Mistake 2 — Exposing detailed health info publicly (infrastructure reconnaissance) #

❌ Wrong — /health returns full check list including error messages; public internet can read service topology.

✅ Correct — require authentication for full health; public /health/live and /health/ready return only aggregate status.