Nov 18, 20266 min read

Graceful Shutdown for Backend Containers: SIGTERM, Draining and Timeouts

What ECS, Cloud Run and Kubernetes do when they stop a container, how long you get after SIGTERM, how to drain HTTP requests and queue consumers in Node.js and Go, and the PID 1 mistake that skips it all.

Illustration for Graceful Shutdown for Backend Containers: SIGTERM, Draining and Timeouts

Every deploy stops containers, and every scale-in does too, so a backend that does not handle SIGTERM turns routine operations into dropped requests, half-processed queue messages and database connections the server keeps open until they time out.

The fix depends on numbers that differ by platform (10 seconds on Cloud Run, 30 by default on ECS) and on details like which process receives the signal.

This guide covers what each platform does when it stops a container, the drain sequence for HTTP servers and queue consumers, code for Node.js and Go, and how Encore handles shutdown for the parts it manages.

Shutdown windows at a glance

Encore on ECS or Cloud RunECS on FargateCloud RunKubernetes
SignalSIGTERM, handled by the runtimeSIGTERM (or the image's STOPSIGNAL)SIGTERMSIGTERM after any preStop hook
Time before SIGKILLThe platform's windowstopTimeout, default 30 s, max 120 s10 sterminationGracePeriodSeconds, default 30 s
Traffic drainingLoad balancer and runtimeALB deregistration delay, default 300 sCloud Run stops routing to the instanceEndpoint removal, races with SIGTERM
What you writeShutdown hook for your own resourcesSignal handler and drain codeSignal handler and drain codeSignal handler, often a preStop sleep

What each platform does

On ECS, stopping a task is the equivalent of docker stop: the container gets SIGTERM, then SIGKILL once the container's stopTimeout expires, 30 seconds by default and 2 to 120 seconds on Fargate. Behind an ALB, the target is deregistered first and the load balancer stops sending new requests, but in-flight ones keep going until the deregistration delay (300 seconds by default) or until they finish. Fargate Spot interruptions send the same SIGTERM with a two-minute warning.

On Cloud Run, the instance gets SIGTERM and 10 seconds before SIGKILL, and Cloud Run routes new requests elsewhere. Most shutdowns happen on idle instances during scale-in, but Google notes that in exceptional cases the signal arrives while requests are still in flight.

On Kubernetes, the pod is removed from Service endpoints and gets SIGTERM at roughly the same time, so a few requests can still arrive after the signal. A short preStop sleep before the app starts draining is the common fix; it counts against terminationGracePeriodSeconds.

The drain sequence

The order of the steps matters more than the code that runs them, and on SIGTERM it goes like this: stop accepting new work (close the HTTP listener, stop pulling from the queue), let in-flight work finish within a deadline shorter than the platform's window, flush logs, traces and metrics, close database pools and broker connections, then exit 0. Anything that cannot finish in time should be left in a state a retry can pick up, which for queue consumers means not acknowledging the message so it is redelivered.

Node.js

import http from "node:http"; import { Pool } from "pg"; const pool = new Pool(); const server = http.createServer(app); // your Express or Fastify handler server.listen(8080); let shuttingDown = false; process.on("SIGTERM", async () => { if (shuttingDown) return; shuttingDown = true; const deadline = setTimeout(() => process.exit(1), 8_000); // under Cloud Run's 10 s const serverClosed = new Promise<void>((resolve) => { server.close(() => resolve()); // stop accepting; waits for in-flight requests }); server.closeIdleConnections(); // drop idle keep-alive sockets await serverClosed; await stopQueueConsumer(); // stop pulling; unacked messages are redelivered await pool.end(); clearTimeout(deadline); process.exit(0); });

Start the process with CMD ["node", "dist/server.js"] in exec form. With npm start or sh -c, PID 1 is npm or the shell, which may not forward SIGTERM, so the handler above never runs and the container is killed at the timeout; docker run --init or tini also fix it by running a minimal init as PID 1.

Go

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, os.Interrupt) defer stop() srv := &http.Server{Addr: ":8080", Handler: mux} go func() { if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed { log.Fatal(err) } }() <-ctx.Done() shutdownCtx, cancel := context.WithTimeout(context.Background(), 8*time.Second) defer cancel() _ = srv.Shutdown(shutdownCtx) // stops listening, waits for in-flight requests consumer.Stop() // stop pulling messages db.Close()

http.Server.Shutdown closes listeners and idle connections and waits for active requests, returning when they finish or the context expires, as described in the net/http docs.

Graceful shutdown in Encore

Encore

Encore brings infrastructure from code to Go and TypeScript backends, and its runtime owns the HTTP server, database pools, Pub/Sub receivers and trace recorder, so it drains those on shutdown without a signal handler in your code. Per the service struct docs, Encore automatically handles graceful shutdown of all Encore-managed functionality, and a Go service struct can implement Shutdown(force context.Context) for anything else it opened, such as a gRPC client or an in-memory batch. On deploy to your own AWS account, Encore runs services on ECS Fargate or EKS behind an Application Load Balancer with health checks, or on Cloud Run or GKE on GCP.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

package metrics import ( "context" ) //encore:service type Service struct { batch *Batcher // your own buffer of events, flushed to an external API } func initService() (*Service, error) { return &Service{batch: NewBatcher()}, nil } // Shutdown is called by Encore when the instance starts shutting down. // Encore drains its own HTTP server, database pools and Pub/Sub receivers. func (s *Service) Shutdown(force context.Context) { s.batch.FlushUntil(force) // stop flushing when the force context is canceled }

The force context is canceled when the graceful window ends; the docs put that window at typically 5 to 30 seconds depending on the cloud and infrastructure. Shutdown is cooperative, so Shutdown must return promptly once force is done, or the platform kills the process anyway.

A coding agent adding a new external client to a service can add its cleanup to Shutdown in the same change, while the HTTP server, database and subscriptions stay with the runtime.

Best fit: Go or TypeScript backends on ECS or Cloud Run in your own account that want request and message draining handled by the runtime, with one hook for custom resources.

Checklist

Run the app as PID 1 or behind an init, set the drain deadline below the platform's window, stop pulling queue messages before closing the database, and never acknowledge a message whose work did not finish. Then test it: stop a task with traffic running (aws ecs stop-task, or deploy a new Cloud Run revision under load) and check the logs for dropped requests.

Frequently asked questions

How long does a container get after SIGTERM?

On ECS the container gets the task definition's stopTimeout, 30 seconds by default and up to 120 seconds on Fargate, before SIGKILL. Cloud Run gives 10 seconds. Kubernetes uses terminationGracePeriodSeconds, 30 seconds by default, which also has to cover any preStop hook.

Why does my Node.js container ignore SIGTERM?

Usually because the process that receives the signal is not your app. If the container starts with npm start or a shell script, PID 1 is npm or sh, which may not forward SIGTERM, so Node never sees it and the container is killed after the timeout. Start node directly in the CMD exec form, or run with docker run --init or tini.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders