Table of Contents

Health Checks

Scope: This article is the NCAT implementation reference for generated behavior. Broader architectural rationale, alternatives, and tradeoffs live in ASI Backbone Learning; Learning is educational guidance, not a dependency of NCAT behavior.

The application includes baseline ASP.NET Core health check endpoints for local development, reverse proxy hosting, load balancers, container platforms, and future deployment scenarios.

Health checks are registered during service configuration:

builder.Services.AddApplicationHealthChecks();

The endpoints are mapped during application startup:

app.MapApplicationHealthChecks();

Implementation Locations

Default Endpoints

Endpoint Purpose
/health General application health endpoint.
/health/ready Readiness endpoint intended for dependency-aware checks such as database, cache, or external service availability.
/health/live Liveness endpoint intended to verify that the application process can respond.
/health/audit-integrity Audit integrity endpoint. Runs only checks tagged audit, such as the optional audit reconciliation check.

When EF Core data access is enabled, readiness includes the application-database check, which reports whether the application database accepts connections. The check is tagged ready and database and is registered only when the data access provider is not None. For file-backed SQLite, the check verifies that the configured database file already exists before opening the connection; it never creates a missing database as a side effect of readiness. Apply migrations before expecting a local instance to report ready.

The database readiness check can be turned off when another component already owns database readiness. The setting is read each time the check runs; when it is false, the registered check reports Healthy without contacting the database:

"ProjectTemplate": {
  "HealthChecks": {
    "DatabaseReadinessCheckEnabled": false
  }
}

The template does not add cache, queue, or external-service readiness checks. Consuming applications must register any additional tagged dependency checks that define production readiness for their service.

Audit integrity is intentionally kept out of readiness. An integrity finding needs operator review, but it does not stop an instance from serving traffic, and a failing readiness check would remove every replica from load balancing at the same moment. Alert on /health/audit-integrity instead. That endpoint returns 200 for Healthy and Degraded and 503 for Unhealthy. Because /health runs every registered check, it also reflects audit integrity; do not use /health as a load-balancer readiness probe.

Access and Deployment Boundary

All four health endpoints are mapped with .AllowAnonymous() intentionally. This keeps container, reverse-proxy, load-balancer, and orchestration probes independent of browser login state and prevents the authenticated fallback policy from turning a failed probe into an authentication redirect.

Anonymous application access does not imply unrestricted Internet exposure. Production deployments should restrict health endpoint reachability through the deployment boundary appropriate to the environment, such as:

  • Private ingress or internal load-balancer listeners.
  • Firewall, network security group, or service-mesh policy.
  • Reverse-proxy path restrictions.
  • Monitoring-system source restrictions.

Avoid returning secrets, configuration values, dependency connection details, exception messages, or other sensitive diagnostics from health responses. Applications that require authenticated health diagnostics should add a separate protected diagnostics endpoint rather than changing the lightweight liveness contract accidentally.

When the application starts in the Production environment, it emits one structured warning identifying /health, /health/ready, /health/live, and /health/audit-integrity as anonymously mapped routes. The warning does not mean anonymous health probes are inherently unsafe; it is an operational signal reminding the deployment operator to confirm that reverse-proxy, ingress, firewall, or service-mesh routing exposes those endpoints only as intended.

Development does not emit this health-route warning. The diagnostic is startup-only and does not add request-path log noise.

Liveness Semantics

/health/live should stay lightweight. It is intended to answer one question:

Can the application process respond to requests?

Do not add database, cache, authentication provider, external HTTP service, queue, or storage checks to liveness. A temporary downstream dependency failure should not normally cause an orchestrator to restart an otherwise healthy application process.

Readiness Semantics

/health/ready is the place for deployment-readiness checks.

A readiness check should answer:

Should this application instance receive normal traffic?

Only checks tagged ready are included in the readiness endpoint. This keeps dependency-aware readiness separate from process liveness.

Example additional readiness check:

builder.Services
    .AddHealthChecks()
    .AddCheck<CacheHealthCheck>(
        "cache",
        tags: [ApplicationHealthCheckTags.Ready]);

Use readiness for dependencies that should remove an instance from rotation when unavailable, such as required database connectivity or a required local cache. Avoid adding optional integrations unless the application cannot serve useful traffic without them.

Container and Hosting Probe Contract

The Dockerfile intentionally delegates active HTTP health probing to Docker Compose, Kubernetes, load balancers, or hosting infrastructure instead of adding probe-only tools to the runtime image.

Recommended probe paths:

/health/live
/health/ready

A container platform or reverse proxy can use /health/live for liveness and /health/ready for readiness. See Docker Development Workflow and Container Release Publishing for container-specific guidance.

Reverse Proxy and Hosting Use

Health endpoints are intended for infrastructure-level checks from reverse proxies, load balancers, deployment platforms, and monitoring systems.

Typical uses include:

  • Confirming the application process is running.
  • Removing an unhealthy or not-ready instance from load balancing rotation.
  • Supporting container or deployment probes.
  • Providing a stable infrastructure path that avoids normal browser-facing error pages.

Security Headers

The default security header configuration excludes /health:

"ExcludedPathPrefixes": [
  "/health",
  "/metrics"
]

Because the exclusion is prefix-based, /health, /health/ready, /health/live, and /health/audit-integrity are all excluded from the security header middleware, except X-Content-Type-Options: nosniff. Strict-Transport-Security is registered separately and still applies to HTTPS health responses outside Development. This keeps health probe responses small and infrastructure-friendly.

Contract References

HealthCheckTests.cs verifies the generated endpoint contract. PipelineExtensions.cs and Program.cs establish the relationship between the normal application pipeline and health-check endpoint mapping.

Learn the Pattern

For broader secure operational defaults and deployment trust boundaries, see Secure-by-Default ASP.NET Core Configuration and Trust Boundaries and Least Privilege.

Edit this page