Как организовать graceful shutdown FastAPI-сервиса в Kubernetes?

Что такое graceful shutdown и зачем он нужен

Graceful shutdown — это механизм, позволяющий сервису завершить работу без потери данных и без прерывания активных запросов. В Kubernetes при обновлении или удалении пода ему отправляется сигнал SIGTERM. Если приложение не обрабатывает этот сигнал, через некоторое время (terminationGracePeriodSeconds) следует SIGKILL, который принудительно завершает процесс. Без graceful shutdown могут быть потеряны данные, оборваны соединения с базами данных или очередями.

Как это работает в FastAPI

FastAPI обычно запускается через Uvicorn, который по умолчанию поддерживает graceful shutdown. При получении SIGTERM Uvicorn перестаёт принимать новые запросы, ожидает завершения текущих (с таймаутом) и затем завершает процесс. Однако, если ваше приложение использует внешние ресурсы (например, пул соединений с PostgreSQL или Redis), их нужно закрывать вручную.

Пример реализации graceful shutdown в FastAPI

import asyncio
from fastapi import FastAPI
from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup: инициализация ресурсов
    app.state.db_pool = await create_db_pool()
    yield
    # Shutdown: закрытие ресурсов
    await app.state.db_pool.close()
    print("Graceful shutdown completed")

app = FastAPI(lifespan=lifespan)

В этом примере используется lifespan-контекст, который позволяет выполнить код при старте и завершении приложения. В блоке после yield происходит закрытие пула соединений.

Настройка Kubernetes для graceful shutdown

В манифесте пода важно настроить terminationGracePeriodSeconds — время, которое Kubernetes ждёт после SIGTERM перед отправкой SIGKILL. Рекомендуется устанавливать его с запасом (например, 30-60 секунд), чтобы приложение успело завершить все запросы. Также стоит настроить liveness и readiness probes, чтобы Kubernetes не убивал под во время завершения.

apiVersion: v1
kind: Pod
metadata:
  name: fastapi-app
spec:
  terminationGracePeriodSeconds: 60
  containers:
  - name: app
    image: myapp:latest
    livenessProbe:
      httpGet:
        path: /health
        port: 8000
      initialDelaySeconds: 5
      periodSeconds: 10
    readinessProbe:
      httpGet:
        path: /ready
        port: 8000
      initialDelaySeconds: 5
      periodSeconds: 5

Вывод

Graceful shutdown обязателен для production-сервисов в Kubernetes, чтобы избежать потери данных и разрыва соединений. FastAPI с Uvicorn предоставляет базовую поддержку, но для корректного закрытия внешних ресурсов нужно использовать lifespan-контекст. Правильная настройка terminationGracePeriodSeconds и readiness probe гарантирует, что под будет удалён только после завершения всех активных запросов.