Graceful Shutdown & Signal Handling

Trate SIGTERM e SIGINT para que servidores HTTP finalizem requisições em andamento, workers em background parem de forma limpa e deploys em rolling do Kubernetes não percam conexões ativas.

Summary

Orquestradores enviam SIGTERM antes de matar um container.

http.Server.Shutdown para de aceitar novas conexões e espera por requisições ativas até um deadline do context.

Goroutines em background precisam de cancelamento explícito via context.Context ou fechamento de canais.

golang.org/x/sync/errgroup coordena múltiplos listeners e workers para encerrarem juntos.

Recipe

Cartão de receita de referência rápida - pronto para copiar e colar.

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)

Quando usar isso:

• Kubernetes Deployments com atualizações em rolling
• Eventos de scale-in de autoscaling
• Desenvolvimento local quando Ctrl+C não deve corromper escritas em andamento
• Serviços com consumidores em background que devem commitar offsets antes de sair
• Processos multi-servidor (HTTP + métricas + gRPC) encerrando em ordem

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)
    }
}

O que isso demonstra:

• signal.NotifyContext cancela o context raiz em SIGTERM
• Dois servidores HTTP encerram com um orçamento de tempo compartilhado
• A goroutine do errgroup espera pelo sinal e então chama Shutdown em cada servidor
• Handlers respeitam o cancelamento de r.Context() durante o drain

Deep Dive

How It Works

• ListenAndServe bloqueia até que Shutdown feche o listener.
• Shutdown marca o servidor como fechado, fecha conexões ociosas e espera por handlers ativos.
• Handlers devem honrar r.Context().Done() para sair prontamente quando clientes desconectam.
• Após o drain HTTP, feche pools de banco de dados, descarregue logs e pare exportadores de trace.

Shutdown Order

Timeout Alignment

Go Notes

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

Gotchas

• Chamar os.Exit sem Shutdown - Perde requisições ativas no deploy; sempre drene primeiro.
• Timeout de shutdown muito curto - Uploads longos falham no meio do stream; alinhe com a duração P99 da requisição.
• Goroutines em background ignoram context - Processo trava além do período de graça e recebe SIGKILL.
• Apenas encerrando um servidor - Listeners de métricas ou debug mantêm o processo vivo inesperadamente.
• Bloqueando Shutdown no main sem goroutine - Não é possível tratar sinal na mesma thread se não for estruturado corretamente.
• Ignorando http.ErrServerClosed - Normal após Shutdown; trate como sucesso, não falha.
• Readiness ainda true durante o shutdown - Mude readiness para false antes do drain para que o LB pare o tráfego novo mais cedo.

Alternatives

FAQs

Related

• Observability Basics - exemplo mínimo de SIGTERM
• Health, Readiness & Liveness Probes - readiness antes do drain
• net/http Best Practices - regras de tier de shutdown
• OpenTelemetry Tracing in Go Services - descarregue spans na saída
• Production Go: Logs, Metrics, Traces, and Signals - sinais operacionais

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).