Quando uma aplicacao recebe um sinal de encerramento, o comportamento padrao e morrer imediatamente. Se ela estava processando uma requisicao ou gravando dados, esse processo e interrompido no meio, gerando respostas incompletas e possivel corrupcao. Graceful shutdown resolve isso: a aplicacao escuta o sinal, para de aceitar trabalho novo, conclui o que esta em andamento e so entao encerra. Este guia mostra o caminho em quatro passos, com foco em aplicacoes que rodam em containers, onde o sinal SIGTERM e o padrao da orquestracao.
Passo 1: Capture o sinal de encerramento
O primeiro passo e registrar um handler para o sinal SIGTERM (e, em alguns casos, SIGINT). Em Node.js, isso e feito com process.on('SIGTERM', callback). Em Go, usa-se signal.Notify. Em Python, o modulo signal. O handler deve iniciar o processo de shutdown, mas nao encerrar o processo imediatamente.
Erro comum: ignorar o sinal e deixar o processo morrer pelo default. Em Kubernetes, quando um pod e removido, o kubelet envia SIGTERM e aguarda um periodo de tolerancia (default de 30 segundos). Se a aplicacao nao tratar o sinal, o container e morto com SIGKILL depois desse tempo, sem chance de limpeza.
Passo 2: Pare de aceitar novas requisicoes
Assim que o sinal chegar, a aplicacao deve parar de aceitar novas conexoes. Em um servidor HTTP, isso significa fechar o listener. No Node.js com Express, use server.close(). Em Go, server.Shutdown(ctx). Em Python com Flask, o servidor WSGI (como Gunicorn) tem mecanismos proprios.
Dica: em ambientes com load balancer ou service mesh, a aplicacao pode avisar que esta em draining. No Kubernetes, o preStop hook pode adicionar um delay para que o service remova o pod do endpoint list antes de o SIGTERM chegar.
Passo 3: Aguarde as requisicoes em andamento concluirem
O coracao do graceful shutdown e o tempo de espera. A aplicacao precisa saber quantas requisicoes estao ativas e aguardar todas terminarem, ou ate um timeout. No Node.js, server.close() aguarda as conexoes ativas, mas nao as keep-alive. Voce pode rastrear manualmente ou usar server.closeIdleConnections() (Node 18+).
Erro comum: esperar indefinidamente. Se uma requisicao trava, o processo nunca encerra. Defina um timeout global, por exemplo 10 segundos, e ao estourar, force a saida com process.exit(1). Esse timeout deve ser menor que o grace period do orquestrador.
Passo 4: Feche recursos externos e encerre
Depois que as requisicoes terminarem, feche conexoes com banco de dados, filas de mensagens e outros clientes. Isso garante que nenhuma transacao seja interrompida no meio. Por fim, execute o process.exit(0) para indicar saida limpa.
Dica: em aplicacoes com workers de background (como consumidores de fila), o mesmo principio se aplica. Pause o consumo, processe a mensagem atual e so entao feche a conexao.
Checklist do que foi implementado
- Captura do sinal SIGTERM registrada.
- Listener HTTP fechado para novas conexoes.
- Espera ativa por requisicoes em andamento, com timeout.
- Conexoes externas (banco, fila) fechadas.
- Exit code 0 ao final do processo.
- Teste manual: envie
kill -TERM <pid>e observe os logs.
FAQ
O que acontece se o graceful shutdown nao for implementado?
A aplicacao morre imediatamente ao receber o sinal. Requisicoes em andamento sao abandonadas, conexoes de banco podem ficar presas e dados gravados pela metade. Em orquestradores como Kubernetes, o pod e morto com SIGKILL apos o grace period, sem chance de limpeza.
Qual a diferenca entre SIGTERM e SIGKILL?
SIGTERM e um sinal gentil que pode ser capturado e tratado pelo processo. SIGKILL nao pode ser capturado nem ignorado: o kernel encerra o processo imediatamente. O graceful shutdown depende de capturar o SIGTERM e executar a rotina de limpeza antes que o SIGKILL chegue.
O graceful shutdown funciona igual em todas as linguagens?
O conceito e o mesmo, mas a implementacao varia. Node.js usa eventos, Go usa canais, Python usa callbacks. A parte critica e o gerenciamento do tempo de espera e o fechamento dos recursos, que sao especificos de cada runtime e biblioteca.
Como testar o graceful shutdown na minha aplicacao?
Envie o sinal manualmente com kill -TERM <pid> e observe os logs. Verifique se as requisicoes em andamento sao concluidas e se o processo sai com exit code 0. Em Kubernetes, use kubectl delete pod e confira se o container termina sem forcar o SIGKILL.
O que e o grace period do Kubernetes?
E o tempo que o kubelet espera entre o SIGTERM e o SIGKILL. O valor padrao e 30 segundos, configurável via terminationGracePeriodSeconds. O tempo total do seu graceful shutdown deve ser menor que esse periodo para evitar morte abrupta.
Preciso implementar graceful shutdown em aplicacoes sem containers?
Sim. Em processos rodando direto no sistema operacional, o SIGTERM tambem e enviado em situacoes como reboot ou encerramento de sessao. Sem o tratamento, o processo morre sem limpar recursos, o que pode causar corrupcao de arquivos ou conexoes presas.