NestJS Health Checks & Graceful Shutdown on Kubernetes: Liveness, Readiness & Zero Dropped Requests

Green pods are not the same as healthy traffic. On Kubernetes, NestJS services need honest liveness and readiness probes — and a graceful shutdown that finishes in-flight HTTP requests and queue jobs before the process exits. Without that, every rolling deploy becomes a small outage your customers feel as 502s and lost webhooks.

This guide covers what each probe should mean in NestJS, how to drain a Terminating pod safely, and how Cyber Infoware kits ship Docker/Kubernetes-ready services so health and shutdown are part of the ship path — not a postmortem fix.

Why deploys drop requests without health discipline

• A pod marked Ready while PostgreSQL is still connecting accepts traffic that immediately fails
• SIGTERM arrives and the process exits before the load balancer stops sending new requests
• Workers die mid-job with no ack — queues redeliver, but customers see duplicate side effects
• Liveness that hits a slow dependency can kill healthy pods during dependency blips

Liveness vs readiness vs startup — keep them distinct

1. Startup — give NestJS time to boot (DI, config, first connections) before other probes begin
2. Liveness — "should Kubernetes restart this process?" Keep it cheap: process up, event loop responsive — not a full DB query if Redis blips are common
3. Readiness — "should this pod receive traffic?" Check dependencies you need to serve: PostgreSQL, Redis, critical config
4. Never use the same expensive check for both liveness and readiness — that turns a dependency outage into a restart storm

What NestJS should expose

• Separate `/health/live` and `/health/ready` (or equivalent) endpoints
• Readiness fails closed when the app is shutting down — so Terminating pods leave the Service endpoints
• Exclude probe paths from aggressive rate limits and auth middleware
• Log probe failures with reason codes operators can act on (db_down, redis_timeout) without dumping secrets

Graceful shutdown checklist for NestJS

• On SIGTERM: mark not Ready first (or stop accepting new work), then wait for the Service to stop routing
• Finish in-flight HTTP requests within a bounded grace period — then force close leftovers
• Stop queue consumers from taking new jobs; allow active jobs to complete or nack for redelivery
• Close DB and Redis pools last — after workers and the HTTP server are quiet
• Set `terminationGracePeriodSeconds` longer than your drain budget, with margin for network lag
• Verify with a deploy: zero spike in 5xx and no lost webhook/job acknowledgements

If Kubernetes can kill your NestJS pod while it is still in the load balancer pool, you do not have zero-downtime deploys — you have lucky timing.

SaaS-specific probe tips

• Do not make readiness depend on every tenant database in a per-tenant DB model — check the control plane / routing DB and shared deps
• Keep billing and webhook receivers Ready only when their queues and signature secrets are loaded
• Alert on Ready pod count dropping during deploys, not only on CrashLoopBackOff
• Pair probes with OpenTelemetry/deploy markers so "green after rollout" means traffic and health, not just Running

What "done" looks like

You roll a NestJS image, old pods leave the Service before they die, new pods take traffic only when Ready, and queues finish work without silent loss. That is the delivery bar modern SaaS buyers assume. Explore packages on cyberinfoware.com/products or contact us to match a kit to your Kubernetes ops goals.