FastAPI en Kubernetes — el despliegue de producción que entregamos por defecto

FastAPI llegó a la ubicuidad en producción alrededor de 2023. El framework en sí es excelente. La historia de despliegue a su alrededor está llena de patrones que casi funcionan — un solo proceso uvicorn bajo PID 1, shutdown gracioso faltante, sin verificación OpenAPI en CI, Pydantic v1 aún colgando. Cada uno ha sido un incidente de cliente en algún momento.

Esta es la plantilla de despliegue FastAPI que aplicamos a cada nuevo servicio que gestionamos en 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 es «el proceso está up». Readiness es «el proceso puede servir tráfico». No los confundas — una base de datos lenta debería sacar un pod de la rotación, no reiniciarlo.

El artículo completo cubre:

• Pydantic v2 (model_config, computed_field, model_validator) — la historia de migración
• Elección de servidor ASGI: Gunicorn + UvicornWorker (default), Hypercorn (HTTP/2), Granian (más nuevo)
• Verificación del esquema OpenAPI en CI — falla el build si el esquema deriva
• Logging estructurado con request ID propagado a través de dependencias
• Patrones de tareas en background — fastapi.BackgroundTasks vs Celery vs Arq
• Manifiestos Kubernetes: resource requests, readinessProbe, terminationGracePeriodSeconds

Entregamos esta plantilla en cada servicio FastAPI gestionado.