FastAPI no Kubernetes — o deploy de produção que entregamos por padrão

FastAPI atingiu ubiquidade em produção por volta de 2023. O framework em si é excelente. A história de deploy ao redor dele está cheia de padrões que quase funcionam — um único processo uvicorn sob PID 1, shutdown gracioso ausente, sem verificação de OpenAPI no CI, Pydantic v1 ainda pendurado. Cada um deles foi um incidente de cliente em algum momento.

Este é o template de deploy FastAPI que aplicamos em cada novo serviço que gerenciamos no Kubernetes.

Dockerfile + endpoints de healthcheck

FROM python:3.12-slim
WORKDIR /app
COPY requirements.lock.txt ./
RUN pip install --no-cache-dir --require-hashes -r requirements.lock.txt
COPY . .
USER 1000
EXPOSE 8000
CMD ["gunicorn", "app.main:app", "--worker-class", "uvicorn.workers.UvicornWorker", \
     "--workers", "4", "--bind", "0.0.0.0:8000", "--timeout", "30"]

@app.get("/healthz", include_in_schema=False)
async def liveness(): return {"ok": True}
 
@app.get("/ready", include_in_schema=False)
async def readiness(): return {"ok": await db.is_connected()}

Liveness é «o processo está de pé». Readiness é «o processo consegue servir tráfego». Não os confunda — um banco lento deveria tirar um pod da rotação, não reiniciá-lo.

O artigo completo cobre:

• Pydantic v2 (model_config, computed_field, model_validator) — a história da migração
• Escolha de servidor ASGI: Gunicorn + UvicornWorker (padrão), Hypercorn (HTTP/2), Granian (mais novo)
• Verificação de schema OpenAPI no CI — falhar o build se o schema desviou
• Logging estruturado com request ID propagado através das dependências
• Padrões de tarefas em background — fastapi.BackgroundTasks vs Celery vs Arq
• Manifestos Kubernetes: resource requests, readinessProbe, terminationGracePeriodSeconds

Entregamos este template em cada serviço FastAPI gerenciado.