graceful-shutdown

グレースフルシャットダウン

目次

• 概要
• 使用する場面
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

プロセス終了前にすべてのリクエストを完了し、接続を閉じ、リソースを解放できるよう、適切なシャットダウン手順を実装します。

使用する場面

• Kubernetes/Docker のデプロイ
• ローリングアップデートとデプロイ
• サーバーの再起動
• ロードバランサーのドレイン期間
• ダウンタイムなしのデプロイ
• プロセスマネージャー（PM2、systemd）
• 長時間実行されるバックグラウンドジョブ
• データベース接続のクリーンアップ

クイックスタート

最小限の動作例：

import express from "express";
import http from "http";

class GracefulShutdownServer {
  private app: express.Application;
  private server: http.Server;
  private isShuttingDown = false;
  private activeConnections = new Set<any>();
  private shutdownTimeout = 30000; // 30 seconds

  constructor() {
    this.app = express();
    this.server = http.createServer(this.app);
    this.setupMiddleware();
    this.setupRoutes();
    this.setupShutdownHandlers();
  }

  private setupMiddleware(): void {
    // Track active connections
    this.app.use((req, res, next) => {
      if (this.isShuttingDown) {
        res.set("Connection", "close");
        return res.status(503).json({
          error: "Server is shutting down",
// ... (see reference guides for full implementation)

リファレンスガイド

詳細な実装は references/ ディレクトリにあります：

ガイド	内容
Express.js のグレースフルシャットダウン	Express.js のグレースフルシャットダウン
Kubernetes 対応のシャットダウン	Kubernetes 対応のシャットダウン
ワーカープロセスのシャットダウン	ワーカープロセスのシャットダウン
データベース接続プールのシャットダウン	データベース接続プールのシャットダウン
PM2 のグレースフルシャットダウン	PM2 のグレースフルシャットダウン
Python/Flask のグレースフルシャットダウン	Python/Flask のグレースフルシャットダウン

ベストプラクティス

✅ 実施すること

• SIGTERM と SIGINT シグナルを処理する
• 新しいリクエストの受け付けを直ちに停止する
• 処理中のリクエストが完了するまで待機する
• 適切なシャットダウンタイムアウトを設定する
• データベース接続を適切に閉じる
• ログとメトリクスをフラッシュする
• シャットダウン中はヘルスチェックを失敗させる
• シャットダウン手順をテストする
• シャットダウンの進行状況をログに記録する
• コンテナではグレースフルシャットダウンを使用する

❌ 避けること

• シャットダウンシグナルを無視する
• クリーンアップせずにプロセスを強制終了する
• 不合理に長いタイムアウトを設定する
• リソースのクリーンアップを省略する
• 接続を閉じ忘れる
• シャットダウンを無期限にブロックする