Graceful shutdown: Shutdown(ctx), проводка SIGTERM и почему деплои всё ещё роняют запросы

Что Shutdown(ctx) делает на самом деле

srv.Shutdown(ctx) исполняет точную последовательность: закрыть все листенеры (новые подключения отвергаются), закрыть простаивающие keep-alive-соединения, затем ждать — опросом, — пока активные запросы завершатся. Возвращается он, когда сервер полностью дренирован, либо когда истёк ctx — что раньше. По истечении он возвращает ctx.Err(), но не убивает насильно соединения в полёте; для жёсткой остановки после льготного периода добавьте srv.Close(). Тем временем заблокированный ListenAndServe немедленно возвращает http.ErrServerClosed — ожидаемое значение, не ошибка:

srv := &http.Server{Addr: ":8080", Handler: mux}

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

<-shutdownSignal // см. следующий раздел

shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil {
	log.Printf("дренаж не завершён: %v", err) // ctx истёк с запросами в полёте
	srv.Close()                                // жёстко закрыть отставших
}

Две детали, о которых спрашивают сеньоров. Первая — порядок: Shutdown обязан выполняться в другой горутине, нежели ListenAndServe, потому что последний заблокирован обслуживанием. Вторая — дедлайн дренажа это число-политика: не меньше вашего самого медленного легитимного запроса и не больше того, что позволяет платформа, — Kubernetes шлёт SIGKILL по истечении terminationGracePeriodSeconds (по умолчанию 30 с), а SIGKILL не ведёт переговоров.

Проводка сигнала: signal.NotifyContext

О своей смерти процесс узнаёт из сигнала — SIGTERM от Kubernetes/systemd, SIGINT от человеческого Ctrl-C. С Go 1.16 идиоматический мост от сигнала к отмене — одна строка:

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, os.Interrupt)
defer stop()

// ... запуск сервера ...

<-ctx.Done() // блокируется до SIGTERM/SIGINT
stop()       // вернуть дефолтную обработку: ВТОРОЙ сигнал убивает сразу

NotifyContext возвращает контекст, отменяемый первым подходящим сигналом. stop() после Done() — осознанный ход эксплуатации: он снимает обработчик, и второй Ctrl-C минует ваш дренаж и убивает процесс — аварийный люк для зависшего shutdown. Без него нетерпеливый оператор, молотящий Ctrl-C, становится заложником вашего 30-секундного дренажа. Ещё один острый край: пока вы дренируете, хендлеры в полёте продолжают работать — если они проверяют глобальный флаг «выключаемся» или вы слишком рано отменяете их базовый контекст, вы превращаете аккуратный дренаж в самострел из 500-х. Дренаж значит дать им закончить, с их собственными дедлайнами как границей.

Чего Shutdown не покрывает

Прежде чем считать логику выключения завершённой, спроси себя: есть ли в этом сервисе веб-сокеты или долгоживущие стримы? Если да — одного Shutdown недостаточно.

Shutdown ждёт соединения в обычном HTTP-цикле запроса. Два класса трафика явно вне его:

• Hijacked-соединения — всё, что забрало сырое TCP-соединение через http.Hijacker, то есть каждый веб-сокет. После hijack net/http больше не отслеживает состояние соединения; Shutdown его ни ждёт, ни закрывает.
• Долгоживущие стримы, которые сами не заканчиваются — SSE-хендлер в цикле for это активный запрос, и голый Shutdown будет ждать его до дедлайна дренажа, на каждом деплое, пока вы не скажете ему сворачиваться.

Крючок для обоих — srv.RegisterOnShutdown(f): каждая зарегистрированная функция запускается (в своей горутине), когда начинается Shutdown. Используйте его, чтобы разослать «закрываемся» websocket-сессиям, отменить контекст стримов и дать им мгновение на close frame:

srv.RegisterOnShutdown(func() {
	hub.CloseAll(1 * time.Second) // close frames веб-сокетам, затем сброс
	streamCancel()                // циклы SSE делают select на этом ctx и выходят
})

Без этого деплой либо рвёт каждый веб-сокет на полукадре (клиенты видят abnormal closure, дальше шторм реконнектов), либо подвешивает дренаж, пока SIGKILL не сделает разрыв за вас — и тогда умирают и HTTP-запросы в полёте, ради которых Shutdown и затевался.

Kubernetes: сначала остановить трафик, потом сервер

В кластере Shutdown — второй шаг танца, и исполнение его первым даёт 502-е из приёма-крючка. Когда под входит в Terminating, две вещи происходят параллельно: kubelet шлёт SIGTERM (после preStop), а контроллер эндпоинтов начинает удалять под из Endpoints — но ingress-ы и правила kube-proxy сходятся с лагом в секунды. Закройте листенер в этот лаг — и отфутболите живой трафик. Надёжная последовательность:

• Сразу завалить readiness по SIGTERM (перевернуть флаг, который читает ваш хендлер /readyz). Readiness управляет членством в балансировке; liveness — нет: проваленный liveness просто перезапустит вас.
• Переждать распространение — preStop-хук со sleep 5 (или сон в процессе перед Shutdown) покрывает типичную сходимость эндпоинтов; кластерам с медленными ingress-контроллерами нужно больше.
• Затем Shutdown(ctx) с дедлайном, влезающим в terminationGracePeriodSeconds, с запасом: грейс 30 с, preStop 5 с, дренаж ≤ 20 с, буфер 5 с.

Числа, которые стоит помнить: SIGKILL безусловен в конце льготного периода; отказ новым соединениям во время распространения виден как 502/503 на ingress в объёме примерно (лаг распространения × частота запросов) на деплой — при 1 000 rps и 3 секундах лага это ~3 000 упавших запросов на под, ровно разница между «деплоя никто не заметил» и постмортемом.