Graceful Shutdown

A graceful shutdown is a controlled stop. When the process gets a termination signal, it stops taking new connections, completes requests already in progress, closes database connections and then exits, rather than being killed mid-request.

Why it matters

Every deployment, autoscaling event and node replacement stops instances. Without graceful handling, users in the middle of a checkout see errors, uploads get cut off and queued jobs are lost or run twice. It works together with connection draining at the load balancer so that new traffic stops arriving before the process shuts down.

Example

In Kubernetes, the platform sends SIGTERM, waits for the grace period (30 seconds by default) and then sends SIGKILL. A process should handle SIGTERM:

process.on('SIGTERM', () => {
  server.close(() => db.end().then(() => process.exit(0)));
  setTimeout(() => process.exit(1), 25000);
});

server.close stops new connections while existing ones finish. The timer is a safety net inside the grace period.

Common mistakes

• A shell wrapper script as the main process that does not forward the signal to the application.
• A grace period shorter than your longest normal request.
• Failing to mark the instance unready first, so the load balancer keeps sending traffic.

Related

• Connection draining
• Rolling deployment
• Readiness probe
• Rollback

This page is general information written by our editorial team and updated when documentation changes. Servers and providers differ, so test changes safely first. See our editorial policy and disclaimer.