Kubernetes Probes no Node.js: health checks corretos

Kubernetes Probes no Node.js informam ao orquestrador se o processo iniciou, continua vivo e está pronto para receber tráfego. Configuradas incorretamente, probes podem reiniciar uma aplicação saudável ou enviar requisições para uma instância incapaz de responder.

Tipos de probe

• startupProbe: protege inicializações lentas;
• livenessProbe: detecta processo travado;
• readinessProbe: controla entrada e saída do tráfego.

Endpoints separados

app.get('/health/live', (req, res) => {
  res.status(200).send('ok');
});

app.get('/health/ready', async (req, res) => {
  const ready = appState.started && !appState.shuttingDown;
  res.status(ready ? 200 : 503).send(ready ? 'ready' : 'not ready');
});

Liveness simples

Liveness não deve depender de todas as integrações externas. Se o banco cair, reiniciar centenas de pods pode piorar a situação. Use liveness para detectar estado interno irrecuperável.

Readiness

Readiness pode considerar inicialização, aquecimento de cache, migração ou capacidade de atender. Ao iniciar shutdown, marque a instância como não pronta antes de fechar o servidor.

Manifesto

startupProbe:
  httpGet:
    path: /health/live
    port: 3000
  periodSeconds: 2
  failureThreshold: 30

livenessProbe:
  httpGet:
    path: /health/live
    port: 3000
  periodSeconds: 10
  timeoutSeconds: 2

readinessProbe:
  httpGet:
    path: /health/ready
    port: 3000
  periodSeconds: 5
  timeoutSeconds: 2

Startup probe

Quando configurada, liveness e readiness aguardam a startup probe ser bem-sucedida. Isso é melhor do que inflar atrasos permanentes para acomodar apenas a inicialização.

Timeouts

Endpoints de probe precisam ser rápidos e não podem aguardar indefinidamente. Evite consultas pesadas e chamadas a várias dependências.

Graceful shutdown

Ao receber SIGTERM, altere readiness para falha, aguarde a remoção dos endpoints e finalize requisições em andamento.

process.on('SIGTERM', async () => {
  appState.shuttingDown = true;
  await sleep(5_000);
  server.close();
});

Consulte Graceful Shutdown no Node.js.

Event loop

Uma rota HTTP pode não responder se o event loop estiver bloqueado, tornando a probe útil para detectar travamento. Porém, CPU alta temporária não significa necessariamente que o processo deve ser reiniciado.

Dependências

Readiness pode verificar acesso essencial ao banco, mas considere cache curto e timeout estrito. Uma dependência opcional não deve retirar o pod do tráfego se existe fallback.

Segurança

Não exponha detalhes, versões, credenciais ou stack traces nos endpoints. Retorne apenas estado técnico mínimo.

Observabilidade

Registre transições de ready para not ready e motivos internos, sem gerar log em cada probe bem-sucedida. Monitore reinícios, falhas e tempo de startup.

Erros comuns

• usar o mesmo check para tudo;
• liveness depender de API externa;
• probe pesada;
• timeout menor que o comportamento real sem medição;
• não alterar readiness no shutdown;
• expor informações sensíveis;
• usar exec com shell inexistente em imagem distroless.

Conclusão

Kubernetes Probes no Node.js devem representar estados distintos: inicialização, vida e prontidão. Mantenha liveness simples, readiness alinhada à capacidade de atendimento e startup adequada ao tempo real de boot.

Consulte Health Checks no Node.js e a documentação oficial de probes do Kubernetes.