iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Connect ASP.NET Core health-check endpoints to Kubernetes probes, but give each probe a distinct job: startup gates checks during initialization, readiness controls whether a Pod receives traffic, and liveness indicates whether a container should be restarted. A single endpoint that reports every dependency for all three probes can turn a temporary outage into unnecessary restarts.
What an ASP.NET Core health endpoint actually tells you
A health endpoint only confirms what its registered checks measure. An endpoint mapped without dependency checks can confirm that the application responds; it does not, by itself, prove that a database, queue, or other dependency is healthy. In a minimal-hosting app, register checks with AddHealthChecks and expose an endpoint with MapHealthChecks. Microsoft’s ASP.NET Core 10.0 guidance shows this pattern: Health checks in ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHealthChecks();
var app = builder.Build();
app.MapHealthChecks("/healthz");
app.Run();This creates a basic endpoint with a plaintext status response. To test dependencies or application-specific conditions, register appropriate checks; custom checks implement IHealthCheck and return a HealthCheckResult with Healthy, Degraded, or Unhealthy status. Keep checks small and responsive. Microsoft recommends registering health-check services as singletons.
For new minimal-hosting applications, MapHealthChecks integrates the endpoint with routing, allowing endpoint-aware middleware such as authorization and distinct endpoint configurations. UseHealthChecks remains an option when middleware-pipeline placement and short-circuit behavior are needed in an existing setup.
#1 Best Overall
Keep startup, readiness, and liveness separate
Kubernetes gives the three probe types different consequences. Use separate routes and filtered check sets when the signals differ; an initialization delay or dependency outage should not automatically tell Kubernetes that the process is irrecoverably broken.
| Probe | Question it answers | Effect of failure | Appropriate signal |
|---|---|---|---|
| Startup | Has initialization finished? | If it fails through the configured failure threshold, Kubernetes kills the container, subject to the Pod restart policy. Readiness and liveness probes do not begin until startup succeeds. | Slow initialization or application startup completion. |
| Readiness | Can this container receive requests now? | The Pod becomes unready and Services stop using it as a backend. The container keeps running and Kubernetes continues probing. | Temporary inability to serve traffic, including a required dependency condition. |
| Liveness | Is the process functioning, or might restarting it help? | After the consecutive-failure threshold is reached, Kubernetes restarts the container. | A process failure it cannot recover from, such as a deadlock. |
Once startup succeeds, readiness and liveness probes can run in parallel; neither waits for the other. Configure startup gating or initial delays to match the application’s lifecycle. Kubernetes explains probe behavior in Configure Liveness, Readiness and Startup Probes.
Microsoft’s example tags checks with ready, then maps a readiness route to that tag and a liveness route to a predicate that excludes registered checks:
Free tools Windows power users keep installed
One-click scans. No signup required.
builder.Services.AddHealthChecks()
.AddCheck<DatabaseHealthCheck>(
"database",
tags: new[] { "ready" });
var app = builder.Build();
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
Predicate = check => check.Tags.Contains("ready")
});
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
Predicate = _ => false
});
app.Run();Here, readiness includes the tagged database check, while liveness checks endpoint responsiveness without running registered dependency checks. This is an illustrative shape: select readiness checks according to whether the app can serve requests, and keep liveness limited to failures where restarting the process is a reasonable recovery action. For hosted-service initialization, an application-specific check can reflect whether startup work has completed.
Rank #3
Configure the Kubernetes probes to match those routes
An HTTP probe names a path and a container port. The kubelet treats HTTP response codes from 200 through 399 as success; other codes are failures. Ensure the application listens on the configured port and that the routes are reachable from the probe. Prefer a small health response over a large application response.
spec:
containers:
- name: app
ports:
- name: http
containerPort: 8080
startupProbe:
httpGet:
path: /health/startup
port: http
periodSeconds: 10
timeoutSeconds: 1
failureThreshold: 30
readinessProbe:
httpGet:
path: /health/ready
port: http
periodSeconds: 10
timeoutSeconds: 1
livenessProbe:
httpGet:
path: /health/live
port: http
periodSeconds: 10
timeoutSeconds: 1The paths and named port above are an example configuration, not universal requirements. If the app does not need a distinct startup condition, configure startup behavior to suit its initialization rather than mapping a misleading endpoint.
Kubernetes documents defaults of periodSeconds: 10, timeoutSeconds: 1, successThreshold: 1, and failureThreshold: 3 (Kubernetes documentation last modified 2025-10-16). These are defaults, not recommended values for every service. The failure threshold counts consecutive failures. For startup and liveness it can lead to a restart; for readiness it marks the Pod unready while probing continues.
Recommended Free Tools
The Kubernetes documentation’s startup example uses failureThreshold: 30 and periodSeconds: 10, allowing up to 300 seconds for startup. This illustrates how threshold and period combine; it is not a general startup-duration recommendation. Microsoft’s readiness example uses initialDelaySeconds: 30 and timeoutSeconds: 1; those values are specific to that example, not a universal baseline.
Best Value
Make HTTP status behavior intentional
ASP.NET Core’s documented default status mapping is Healthy to HTTP 200, Degraded to HTTP 200, and Unhealthy to HTTP 503. Kubernetes accepts 200–399 as successful, so a Degraded result remains probe-successful by default. Decide whether degradation should continue receiving traffic, be surfaced through separate monitoring, or be mapped differently. ASP.NET Core allows status mapping to be configured through HealthCheckOptions.ResultStatusCodes.
Health-check middleware prevents response caching by default by setting or overriding Cache-Control, Expires, and Pragma headers. AllowCachingResponses can change that behavior. Avoid placing connection strings, exception details, or other sensitive diagnostics in a response exposed to unauthenticated callers.
Choose checks and thresholds based on recovery
- Put traffic eligibility in readiness. If a dependency is essential to serving requests, its check may belong in readiness so Kubernetes stops routing traffic to that Pod while leaving the process running.
- Keep liveness focused on process recovery. A downstream dependency outage usually does not mean restarting every application process will help. Kubernetes warns that “Incorrect implementation of liveness probes can lead to cascading failures.”
- Use startup for genuine initialization time. Startup success gates readiness and liveness; tune its allowance to the service’s actual startup behavior.
- Account for check cost and latency. A probe must complete within its timeout. Avoid expensive, broad diagnostics on frequently polled endpoints.
- Validate status and routing together. Confirm the app listens on the probe’s container port, each path maps to the intended filtered check set, and the resulting HTTP status has the intended Kubernetes consequence.
Probe thresholds are operational trade-offs: a short timeout or small failure threshold reacts sooner but is less tolerant of brief delays; a longer allowance delays detection. Consider the effect of removing a Pod from traffic separately from restarting its container.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Version and hosting notes
The Microsoft guidance linked here is the ASP.NET Core 10.0 view, displayed as updated 2026-02-25. Its examples include both current minimal-hosting code and older Startup-based patterns; the code above uses minimal hosting. The Kubernetes probe documentation cited here was last modified 2025-10-16. Defaults and probe behavior can be version-sensitive, so check the documentation for the Kubernetes version running your cluster.
Microsoft states that AspNetCore.Diagnostics.HealthChecks is not maintained or supported by Microsoft. Do not treat that third-party library as a Microsoft-supported component; the built-in ASP.NET Core health-check APIs are sufficient for the endpoint pattern shown here.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
