Zero-Downtime Deployment for Node.js

By Khimananda Oli | Last reviewed: August 2026

Dropped requests during releases are rarely a platform failure; they are usually an application lifecycle failure. Achieving zero-downtime deployment for Node.js requires coordinating three distinct layers: the application’s signal handling, the process manager’s restart strategy, and the load balancer’s health checks. If any one of these is misconfigured, users will see 502 Bad Gateway errors regardless of how sophisticated your infrastructure is. This guide breaks down the exact implementation required to make deployments invisible.

How do you implement graceful shutdown in Node.js?

The foundation of zero-downtime deployment for Node.js is the application's ability to stop accepting new work while finishing existing work. Node.js does not do this automatically. When a container orchestrator or process manager sends a SIGTERM signal, the default behavior is immediate termination, which severs active TCP connections and drops in-flight requests.

Catching signals and draining connections

You must explicitly listen for termination signals and coordinate the shutdown sequence. The following pattern works for Express, Fastify, and native HTTP servers. It stops the server from accepting new connections, waits for active requests to complete, and then closes database pools before exiting.

const server = app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});

const gracefulShutdown = async (signal) => {
  console.log(`${signal} received. Starting graceful shutdown...`);
  
  // Stop accepting new connections immediately
  server.close(async (err) => {
    if (err) {
      console.error('Error during server close:', err);
      process.exit(1);
    }
    
    console.log('HTTP server closed. Draining database connections...');
    
    // Close database pools, message queues, Redis clients
    try {
      await dbPool.end();
      await redisClient.quit();
      console.log('All resources drained. Exiting cleanly.');
      process.exit(0);
    } catch (cleanupErr) {
      console.error('Cleanup failed:', cleanupErr);
      process.exit(1);
    }
  });
  
  // Force exit if graceful shutdown takes too long
  setTimeout(() => {
    console.error('Forced shutdown: graceful timeout exceeded');
    process.exit(1);
  }, 25000); // Must be less than K8s terminationGracePeriodSeconds
};

process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
process.on('SIGINT', () => gracefulShutdown('SIGINT'));

A common mistake is setting the forced-shutdown timeout longer than your orchestrator’s kill grace period. In Kubernetes, if terminationGracePeriodSeconds is 30 and your app waits 35 seconds, Kubernetes sends SIGKILL at second 30, bypassing your cleanup entirely. Always set the application timeout to at least 5 seconds less than the infrastructure limit.

Handling long-lived connections

If your Node.js application serves WebSockets, SSE streams, or long-polling endpoints, server.close() alone is insufficient because it only stops new HTTP requests but leaves existing sockets open indefinitely. You must track active sockets and destroy them after a reasonable drain period, optionally sending a close frame to allow clients to reconnect gracefully.

• Track all socket connections in a Set on the connection event
• Remove sockets from the Set on the close event
• During shutdown, iterate remaining sockets and call socket.destroy() after allowing in-flight messages to flush
• For WebSocket servers, send a close code 1001 (Going Away) before destroying

For teams managing complex stateful connections, understanding the underlying runtime behavior is critical. My guide on installing and configuring Node.js on Ubuntu covers runtime-level tuning that complements application-level shutdown logic.

How do rolling updates prevent downtime in Kubernetes?

Graceful shutdown handles the application layer, but the orchestration layer determines whether traffic reaches a dying instance. In Kubernetes, the default RollingUpdate strategy replaces pods incrementally, but the default parameters are often too aggressive for production Node.js workloads.

Configuring safe rollout parameters

The two critical fields are maxUnavailable and maxSurge. For true zero-downtime, maxUnavailable must be 0, ensuring capacity never drops below the desired replica count during deployment.

spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 1
  template:
    spec:
      terminationGracePeriodSeconds: 30
      containers:
      - name: node-app
        readinessProbe:
          httpGet:
            path: /healthz/ready
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 5
          failureThreshold: 3
        livenessProbe:
          httpGet:
            path: /healthz/live
            port: 3000
          initialDelaySeconds: 10
          periodSeconds: 10

With maxSurge: 1, Kubernetes creates one new pod before terminating an old one. With maxUnavailable: 0, it will never terminate an old pod until the new one passes its readiness probe. This guarantees full capacity throughout the transition.

Why readiness probes matter more than liveness probes

A frequent cause of "zero-downtime" failures is confusing liveness and readiness. The liveness probe determines if a container should be restarted; the readiness probe determines if it should receive traffic. During deployment, Kubernetes adds the pod to the Service endpoints only after the readiness probe succeeds. If your readiness endpoint returns 200 before the application is fully initialized (database connected, caches warmed), traffic arrives prematurely and fails.

Your readiness check must verify actual dependency health, not just HTTP responsiveness. See my article on the four golden signals of monitoring for guidance on what constitutes a meaningful health signal versus a superficial heartbeat.

How do you compare deployment strategies for Node.js?

Rolling updates are the default, but they are not always the right choice. Understanding the trade-offs between strategies helps you match the approach to your application’s risk profile and architectural constraints.

For most Node.js web applications, rolling updates with proper configuration provide the best balance. Blue-green becomes necessary when database schema changes are incompatible between versions, requiring two separate databases or careful migration sequencing. I cover these patterns in depth in blue-green and canary deploys on Kubernetes.

When rolling updates fail silently

Even with perfect configuration, rolling updates can produce brief error spikes if your load balancer has stale endpoint caches. In AWS EKS, the kube-proxy iptables rules may take several seconds to propagate after a pod becomes ready. During this window, some traffic may still route to terminating pods. Mitigations include:

1. Setting preStop hooks with a 5-second sleep to allow endpoint propagation before SIGTERM
2. Using Cilium or eBPF-based networking for faster endpoint updates (see Cilium eBPF networking for Kubernetes)
3. Implementing client-side retry logic with exponential backoff for transient 502/503 responses

How do you handle database migrations during zero-downtime deploys?

Application code is only half the problem. Database schema changes are the most common source of deployment-related outages in Node.js systems. A rolling update assumes old and new code can coexist, which means your database schema must support both versions simultaneously.

The expand-contract pattern

Never rename or drop columns in a single deployment. Instead, use a three-phase approach:

• Expand: Add the new column as nullable. Deploy new code that writes to both old and new columns but reads from the old column.
• Migrate: Run a background job to backfill the new column for existing rows. Deploy code that reads from the new column with fallback to the old.
• Contract: Remove the old column and the dual-write logic in a subsequent deployment.

This pattern ensures every intermediate state is valid for both running versions. For PostgreSQL-specific implementation details, including lock-safe DDL operations, refer to PostgreSQL administration essentials.

Connection pool management during restarts

Node.js applications typically use connection pools (pg-pool, mysql2/promise). During graceful shutdown, you must drain the pool before exiting. If you don’t, in-flight queries fail mid-execution when the process dies. The pool.end() method waits for active queries to complete and prevents new ones from being checked out. Pair this with the HTTP server drain described earlier to ensure the entire request chain completes cleanly.

Conclusion

Zero-downtime deployment for Node.js is not a feature you enable—it is a contract you enforce across three layers. Your application must drain connections on SIGTERM. Your orchestrator must maintain capacity during transitions with correct probe configuration. Your database migrations must tolerate version coexistence. Missing any one of these breaks the chain and introduces the very downtime you are trying to eliminate.

Audit your current deployment against each layer described here. Start with the graceful shutdown implementation, as it is the most commonly missing piece and the fastest to fix. Then verify your Kubernetes rollout parameters and readiness probe logic. Finally, review your migration strategy for backward compatibility. If your team needs help designing or auditing a production-grade deployment pipeline, reach out to discuss your specific architecture.