Graceful Shutdown & Signal Handling

Handle SIGTERM and SIGINT so HTTP servers finish in-flight requests, background workers stop cleanly, and Kubernetes rolling deploys do not drop active connections.

Summary

Orchestrators send SIGTERM before killing a container.

http.Server.Shutdown stops accepting new connections and waits for active requests until a context deadline.

Background goroutines need explicit cancel via context.Context or close channels.

golang.org/x/sync/errgroup coordinates multiple listeners and workers shutting down together.

Recipe

Quick-reference recipe card - copy-paste ready.

quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit
ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
defer cancel()
_ = server.Shutdown(ctx)

When to reach for this:

• Kubernetes Deployments with rolling updates
• Autoscaling scale-in events
• Local development when Ctrl+C should not corrupt in-flight writes
• Services with background consumers that must commit offsets before exit
• Multi-server processes (HTTP + metrics + gRPC) shutting down in order

Working Example

package main
 
import (
    "context"
    "errors"
    "log/slog"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"
 
    "golang.org/x/sync/errgroup"
)
 
func main() {
    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer stop()
 
    mux := http.NewServeMux()
    mux.HandleFunc("GET /work", func(w http.ResponseWriter, r *http.Request) {
        select {
        case <-time.After(2 * time.Second):
            w.Write([]byte("done"))
        case <-r.Context().Done():
            return
        }
    })
 
    api := &http.Server{Addr: ":8080", Handler: mux, ReadHeaderTimeout: 5 * time.Second}
    admin := &http.Server{Addr: ":9090", Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("metrics"))
    })}
 
    g, gctx := errgroup.WithContext(ctx)
 
    g.Go(func() error {
        slog.Info("api listening", "addr", api.Addr)
        if err := api.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            return err
        }
        return nil
    })
 
    g.Go(func() error {
        slog.Info("admin listening", "addr", admin.Addr)
        if err := admin.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            return err
        }
        return nil
    })
 
    g.Go(func() error {
        <-gctx.Done()
        slog.Info("shutdown started")
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
        defer cancel()
        if err := api.Shutdown(shutdownCtx); err != nil {
            slog.Error("api shutdown", "err", err)
        }
        if err := admin.Shutdown(shutdownCtx); err != nil {
            slog.Error("admin shutdown", "err", err)
        }
        slog.Info("shutdown complete")
        return nil
    })
 
    if err := g.Wait(); err != nil {
        slog.Error("server error", "err", err)
        os.Exit(1)
    }
}

What this demonstrates:

• signal.NotifyContext cancels root context on SIGTERM
• Two HTTP servers shut down with shared timeout budget
• errgroup goroutine waits for signal then calls Shutdown on each server
• Handlers respect r.Context() cancellation during drain

Deep Dive

How It Works

• ListenAndServe blocks until Shutdown closes the listener.
• Shutdown marks server closed, closes idle connections, and waits for active handlers.
• Handlers should honor r.Context().Done() to exit promptly when clients disconnect.
• After HTTP drain, close database pools, flush logs, and stop trace exporters.

Shutdown Order

Timeout Alignment

Go Notes

// Workers tied to shutdown context
func runWorker(ctx context.Context) error {
    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
            processOneJob(ctx)
        }
    }
}

Gotchas

• Calling os.Exit without Shutdown - Drops active requests on deploy; always drain first.
• Shutdown timeout too short - Long uploads fail mid-stream; align with P99 request duration.
• Background goroutines ignore context - Process hangs past grace period and gets SIGKILL.
• Only shutting down one server - Metrics or debug listeners keep process alive unexpectedly.
• Blocking Shutdown on main without goroutine - Cannot handle signal on same thread if not structured correctly.
• Ignoring http.ErrServerClosed - Normal after Shutdown; treat as success not failure.
• Readiness still true during shutdown - Flip readiness false before drain so LB stops new traffic early.

Alternatives

FAQs

Related

• Observability Basics - minimal SIGTERM example
• Health, Readiness & Liveness Probes - readiness before drain
• net/http Best Practices - shutdown tier rules
• OpenTelemetry Tracing in Go Services - flush spans on exit
• Production Go: Logs, Metrics, Traces, and Signals - operational signals

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).