Комментарий пользователя
Здравствуйте! Развернули сервис на FastAPI и Uvicorn в Kubernetes. При каждом деплое новой версии или перезапуске подов клиенты получают пачку ошибок 502/504, а в логах Sentry появляются сообщения о внезапно разорванных сетевых соединениях на середине транзакций. Вроде бы настроили завершение процессов, но запросы все равно обрываются. В чем может быть дело и как правильно настроить остановку сервиса?
Ответ специалиста
Добрый день!
Описанная вами проблема — классический сценарий при отсутствии или некорректной настройке Graceful Shutdown в среде Kubernetes. Здесь обычно сходятся сразу две причины:
- Гонка балансировки трафика в Kubernetes: одновременно с отправкой сигнала
SIGTERMв контейнер оркестратор начинает исключать под из эндпоинтов сервиса (активных адресов). Этот процесс занимает некоторое время, в течение которого под уже начал процедуру завершения работы, а балансировщик (Ingress/Service) все еще продолжает направлять ему новые входящие запросы. - Несогласованность таймингов (drain и grace): если оркестратор принудительно гасит процесс сигналом
SIGKILLдо того, как приложение успело дообработать активные (in-flight) запросы и закрыть соединения с базами данных, транзакции рвутся.
Для надежного деплоя без потери данных необходимо скоординировать работу Kubernetes и сервера приложения (Uvicorn/Gunicorn).
Шаг 1. Добавьте preStop-хук и увеличьте terminationGracePeriodSeconds в Kubernetes
Задержка перед отправкой SIGTERM дает балансировщику время обновить список адресов и гарантированно убрать под из маршрутизации до того, как сервер начнет выключаться:
apiVersion: apps/v1
kind: Deployment
metadata:
name: fastapi-api
spec:
template:
spec:
# Выделяем 60 секунд на полный цикл завершения (по умолчанию 30)
terminationGracePeriodSeconds: 60
containers:
- name: api
image: my-app:latest
lifecycle:
preStop:
exec:
# Даем балансировщику 15 секунд на исключение пода из эндпоинтов
command: ["/bin/sh", "-c", "sleep 15"]
Шаг 2. Настройте drain-период в параметрах запуска сервера.
Сервер должен ожидать завершения активных соединений. Для Uvicorn необходимо явно передать параметр --timeout-graceful-shutdown (по умолчанию он равен None, что приводит к мгновенной остановке процессов):
uvicorn main:app --host 0.0.0.0 --port 8000 --timeout-graceful-shutdown 44
Правило соотношения таймингов: grace-период (60с) > sleep в preStop (15с) + drain-период (44с). Это оставляет серверу запас времени на корректное закрытие соединений с БД после завершения всех запросов.
Шаг 3. Закрывайте ресурсы в контекстном менеджере lifespan
В FastAPI управление жизненным циклом организуется через lifespan: код до yield выполняется при старте, а код после yield — строго после завершения обработки всех in-flight запросов:
import logging
from contextlib import asynccontextmanager
from fastapi import FastAPI
from db.path import dispose_db
logger = logging.getLogger(__name__)
@asynccontextmanager
async def lifespan(app: FastAPI):
# Код инициализации при старте
yield
# Выполняется только после того, как in-flight запросы завершены
logger.info("Closing connections...")
await dispose_db()
logger.info("Shutdown completed")
app = FastAPI(lifespan=lifespan)
Благодаря такой схеме балансировщик успевает увести клиентов на другие поды, старые запросы дорабатывают в пределах drain-периода, а соединения с внешними сервисами закрываются без обрывов.