• Оглавление
  • Зачем нужен graceful shutdown и что он даёт бизнесу
  • Как должен завершаться HTTP‑сервис: пошаговый протокол
  • Пример на Go: сигнал, /ready, слив соединений
  • Пример на Node.js: server.close и контроль сокетов
  • Kubernetes: readiness/liveness, preStop, окна завершения, PDB
  • Балансировщики и Nginx: корректная отписка инстанса и таймауты
  • Долгие соединения: WebSocket, SSE, gRPC — как не зависнуть
  • Фоновые задачи и очереди: Kafka/SQS/cron без потерь и дублей
  • Чек‑лист внедрения и типичные ошибки
  • Мини‑план внедрения за 1–2 спринта

Зачем нужен graceful shutdown и что он даёт бизнесу

Почти каждое падение доступности при релизе — это не «плохой код», а некорректная остановка. Контейнеру прислали SIGTERM — он мгновенно умер, балансировщик ещё шлёт ему трафик, запросы обрываются, очереди теряют подтверждения, клиенты видят 502. Правильное завершение (graceful shutdown) делает обратное: сначала сервис перестаёт брать новый трафик, спокойно доделывает текущие запросы, корректно закрывает соединения и только потом выходит.

Бизнес‑выгоды:

• Релизы без 502/499/504 — меньше брошенных корзин и неуспешных платежей.
• Меньше ночных инцидентов — команда спит, график предсказуем.
• Чистые метрики и алёрты — без «ложных красных» на время выката.
• Уверенность в масштабировании — можно смело добавлять и убирать инстансы по автоскейлингу.

Как должен завершаться HTTP‑сервис: пошаговый протокол

1. Получаем сигнал остановки (SIGTERM/SIGINT) от оркестратора.
2. Немедленно помечаемся «не готов» в readiness‑пробе, чтобы балансировщик перестал слать нам новые запросы.
3. Даём балансировщику время «дослать» старые соединения (deregistration delay / drain time).
4. Запрещаем принимать новые соединения на уровне приложения (stop accepting) и аккуратно закрываем текущее.
5. Завершаем фоновые задачи, подтверждаем/откатываем сообщения из очередей.
6. Флашим метрики/логи (если это важно) и уходим по таймауту.

Ключевая идея — сервис сам управляет своей «готовностью» и даёт облачной обвязке время сделать свою работу.

Пример на Go: сигнал, /ready, слив соединений

Ниже минимальный HTTP‑сервис, который корректно обрабатывает SIGTERM, имеет /ready и даёт до 30 секунд на завершение запросов.

package main

import (
    "context"
    "log"
    "net/http"
    "os"
    "os/signal"
    "sync/atomic"
    "syscall"
    "time"
)

var ready atomic.Bool

func main() {
    mux := http.NewServeMux()

    // Бизнес‑ручка: имитируем работу 200–1500 мс
    mux.HandleFunc("/api", func(w http.ResponseWriter, r *http.Request) {
        time.Sleep(200*time.Millisecond + time.Duration(time.Now().UnixNano()%1300_000_000))
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write([]byte("ok"))
    })

    // Readiness: 200 только когда готовы принимать трафик
    mux.HandleFunc("/ready", func(w http.ResponseWriter, r *http.Request) {
        if !ready.Load() {
            http.Error(w, "not ready", http.StatusServiceUnavailable)
            return
        }
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write([]byte("ready"))
    })

    // Liveness: сервис жив, если процесс жив и цикл событий крутится
    mux.HandleFunc("/live", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write([]byte("live"))
    })

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           mux,
        ReadHeaderTimeout: 5 * time.Second,
        IdleTimeout:       90 * time.Second, // важен для Keep‑Alive
    }

    // Сразу после старта считаем себя неготовыми, пока не поднялись зависимости
    // Здесь можно проверить подключение к БД/кешу и т.п.
    go func() {
        time.Sleep(300 * time.Millisecond)
        ready.Store(true)
        log.Println("service is ready")
    }()

    // Обработка сигналов
    stop := make(chan os.Signal, 1)
    signal.Notify(stop, syscall.SIGINT, syscall.SIGTERM)

    go func() {
        log.Println("listening on :8080")
        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            log.Fatalf("listen: %v", err)
        }
    }()

    <-stop
    log.Println("signal received, starting graceful shutdown")

    // 1) Сразу уходим из готовности — балансировщик перестанет присылать запросы
    ready.Store(false)

    // 2) Дадим LB время отписать нас (обычно 5–30 с)
    drainDelay := 5 * time.Second
    time.Sleep(drainDelay)

    // 3) Аккуратная остановка HTTP‑сервера с таймаутом
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    if err := srv.Shutdown(ctx); err != nil { // останавливает приём новых коннектов и ждёт текущие
        log.Printf("server shutdown error: %v", err)
    }

    log.Println("server exited cleanly")
}

Что важно:

• /ready возвращает 503, как только пришёл SIGTERM — трафик перестаёт приходить.
• Небольшая задержка перед Shutdown даёт балансировщику время «отподписать» инстанс.
• IdleTimeout и корректная обработка Keep‑Alive не оставляют «залипших» коннектов.

Пример на Node.js: server.close и контроль сокетов

В Node нужно явно следить за активными сокетами: server.close перестаёт принимать новые соединения и ждёт существующие, но полезно иметь верхний предел ожидания.

const http = require('http');

let isReady = false;
const sockets = new Set();

const server = http.createServer((req, res) => {
  if (req.url === '/ready') {
    if (!isReady) {
      res.statusCode = 503; return res.end('not ready');
    }
    return res.end('ready');
  }
  if (req.url === '/live') return res.end('live');

  // Имитация работы
  const work = 200 + Math.floor(Math.random() * 1300);
  setTimeout(() => { res.end('ok'); }, work);
});

server.keepAliveTimeout = 90_000;   // для долговечных коннектов
server.headersTimeout    = 95_000;   // чуть больше keepAliveTimeout

server.on('connection', (socket) => {
  sockets.add(socket);
  socket.on('close', () => sockets.delete(socket));
});

server.listen(8080, () => {
  setTimeout(() => { isReady = true; console.log('service is ready'); }, 300);
  console.log('listening on :8080');
});

function shutdown() {
  console.log('signal received, starting graceful shutdown');
  isReady = false; // 1) выходим из готовности

  const drainDelay = 5000; // 5с на отписку от LB
  setTimeout(() => {
    server.close(() => {
      console.log('server closed cleanly');
      process.exit(0);
    });

    // Жёсткий предел ожидания, чтобы не висеть вечно
    const forceKill = setTimeout(() => {
      console.warn('force closing lingering sockets');
      for (const s of sockets) s.destroy();
      process.exit(0);
    }, 30000);
    forceKill.unref();
  }, drainDelay);
}

process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);

Kubernetes: readiness/liveness, preStop, окна завершения, PDB

Главные настройки в манифестах:

• readinessProbe — говорит, можно ли слать трафик. Завязана на /ready.
• livenessProbe — перезапуск контейнера, если он «завис».
• preStop hook — даёт шанс выполнить «/drain» или просто подождать до Shutdown.
• terminationGracePeriodSeconds — окно, в которое Pod должен завершиться.
• RollingUpdate с maxUnavailable=0 — не роняем доступность при выкладке.
• PodDisruptionBudget — защищаемся от одновременной остановки всех Pod.

Пример Deployment с корректными пробами и preStop:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: checkout
spec:
  replicas: 4
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels: { app: checkout }
  template:
    metadata:
      labels: { app: checkout }
    spec:
      terminationGracePeriodSeconds: 60
      containers:
        - name: app
          image: registry.example.com/checkout:1.2.3
          ports:
            - containerPort: 8080
          readinessProbe:
            httpGet: { path: /ready, port: 8080 }
            periodSeconds: 2
            failureThreshold: 2
            successThreshold: 1
            timeoutSeconds: 1
          livenessProbe:
            httpGet: { path: /live, port: 8080 }
            initialDelaySeconds: 5
            periodSeconds: 5
          lifecycle:
            preStop:
              exec:
                # даём LB время «снять» под, затем приложение сна закрывает коннекты
                command: ["/bin/sh", "-c", "sleep 5"]

А для защиты от одновременных остановок:

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: checkout-pdb
spec:
  minAvailable: 3
  selector:
    matchLabels: { app: checkout }

Правило трёх таймеров:

• readiness становится false мгновенно по SIGTERM в приложении.
• preStop sleep должен быть чуть меньше, чем deregistration_delay в балансировщике.
• terminationGracePeriodSeconds должен быть больше суммарного drain + максимум времени обработки запроса.

Балансировщики и Nginx: корректная отписка инстанса и таймауты

Что настроить в LB:

• Deregistration delay / connection draining: 5–30 с. В это время LB перестаёт слать новый трафик и ждёт завершения текущих соединений.
• Health checks должны опираться на /ready (а не /live), чтобы сразу выключать ноду из ротации.
• Таймауты на стороне прокси (idle, read, send) должны быть согласованы с таймаутами приложения.

Пример для AWS ALB/NLB: установите target group deregistration_delay_seconds=10–15. Для GCP — connection draining timeout. Для Nginx как reverse‑proxy — используйте graceful reload и разумные таймауты:

http {
  keepalive_timeout  90s;
  send_timeout       30s;
  proxy_read_timeout 60s;
  proxy_send_timeout 60s;
}

# Грациозный reload без сброса коннектов:
# nginx -s reload

Долгие соединения: WebSocket, SSE, gRPC — как не зависнуть

• Установите максимальный «срок жизни» соединения (max connection age). В gRPC — параметры сервера, для WS/SSE — таймеры на стороне приложения.
• При получении SIGTERM отправьте клиенту «мягкий» сигнал закрытия: для WS — close frame с кодом 1001/1000; для SSE — завершите поток корректно. Предупреждение в UI «соединение перезапускается…» снижает удар по UX.
• Придерживайтесь таймаута завершения (например, 15–30 с), затем принудительно закрывайте оставшиеся соединения.

Фоновые задачи и очереди: Kafka/SQS/cron без потерь и дублей

Релизы часто ломают не HTTP, а воркеры.

Принципы:

• Завершайте цикл получения новых задач сразу после SIGTERM.
• Дайте закончить текущую задачу в рамках grace‑таймаута. Если не успели — откатите/не подтверждайте.
• Коммитьте смещения (Kafka) только после успешной обработки. При остановке — коммит последнего завершённого.
• Заложите идемпотентность обработчиков: повтор возможен.

Эскиз для Kafka на Go с sarama (идея, не привязана к конкретной либе):

// При SIGTERM: закрыть consumer, дождаться onPartitionsRevoked, закоммитить оффсеты и выйти.
// Обработчик должен быть идемпотентен: возможно повторное сообщение после рестарта.

Для SQS/Redis‑очередей:

• Увеличивайте visibility timeout, если задача длинная и вы близки к завершению.
• Удаляйте сообщение из очереди только после успеха.

Cron‑задачи:

• Переведите крон в отдельный Deployment с тем же graceful shutdown.
• Или используйте Kubernetes CronJob: он сам управляет жизненным циклом Pod.

Чек‑лист внедрения и типичные ошибки

Чек‑лист:

• Есть /ready и /live, и они делают разное.
• Приложение по SIGTERM мгновенно делает /ready=503 и прекращает приём новых соединений.
• Есть задержка drain перед остановкой сервера (5–15 с) — под балансировщик.
• terminationGracePeriodSeconds достаточен: drain + макс. время запроса + запас.
• RollingUpdate: maxUnavailable=0, maxSurge=1–2.
• Настроен PDB: не уроните все поды одновременно.
• Таймауты приложения и прокси согласованы.
• Для WS/SSE/gRPC — ограничен срок жизни коннектов и реализовано мягкое закрытие.
• Воркеры очередей умеют останавливать приём и завершать текущую задачу.
• Обработчики задач идемпотентны, смещения/подтверждения корректны.

Типичные ошибки:

• Liveness и readiness указывают на один и тот же эндпоинт.
• readiness всегда 200, даже если БД/кеш упал — под получают трафик и тут же 500.
• Нет drain‑паузы: LB ещё шлёт запросы в «умирающий» инстанс.
• Жёсткое process.exit(0)/os.Exit(0) сразу после SIGTERM — потеря запросов/задач.
• Слишком короткий terminationGracePeriodSeconds: Kubernetes убивает процесс раньше, чем он успел закончить.

Мини‑план внедрения за 1–2 спринта

Спринт 1:

• Добавьте /ready и /live, разведите их смысл.
• Реализуйте обработку SIGTERM в приложении: выход из готовности, drain‑пауза, аккуратное закрытие сервера.
• Настройте readiness/livenessProbe, terminationGracePeriodSeconds и preStop.

Спринт 2:

• Уточните таймауты в балансировщике и прокси.
• Добавьте поддержку мягкого закрытия для WS/SSE/gRPC (если применимо).
• Для воркеров очередей — корректная остановка, подтверждения и идемпотентность.
• Включите PDB и проверьте RollingUpdate стратегию на staging с нагрузочным тестом.

Итог: релизы перестают быть «событием», а становятся рутиной — без 502, без потерянных заказов и без ночных дежурств.