Mejores Prácticas de Despliegue
Lanzamientos reproducibles, observables y reversibles mantienen las APIs de Python disponibles mientras los equipos publican diariamente. Estas reglas se aplican desde Dockerfiles hasta CI/CD y despliegues en Kubernetes.
Cómo Usar Esta Lista
- Valida antes del primer despliegue en producción y después de cualquier incidente (SEV) que involucre despliegue o configuración.
- Empareja con Canales de CI/CD para una aplicación automatizada.
- Trata los puntos finales de preparación faltantes como un bloqueo de fusión para servicios HTTP.
A - Compilación e Imagen
- Compilación Docker multi-etapa con imagen base reducida. Sin cadena de herramientas de compilación en la capa de tiempo de ejecución.
- Fija Python 3.14 y dependencias con el archivo lock de uv.
uv sync --frozenen CI y Dockerfile. - Ejecuta el contenedor como usuario no root. Rutas escribibles solo donde sea necesario.
-
.dockerignoreexcluye.venv, pruebas, git. Contexto más pequeño y compilaciones más rápidas. - Etiqueta las imágenes con el SHA de git, nunca
:latesten producción. Artefacto inmutable por lanzamiento.
B - Tiempo de Ejecución y Servidores
- Usa Gunicorn+UvicornWorker o equivalente para FastAPI en producción. No el servidor de desarrollo con
--reload. - Documenta el
CMDexacto del contenedor en el repositorio. Mismo comando en el manifiesto de K8s y docker-compose. - Establece solicitudes y límites de CPU/memoria a partir de pruebas de carga. Previene OOMKill y vecinos ruidosos en la planificación.
- Configura tiempos de espera de apagado gradual. Coincide con
terminationGracePeriodSecondsy Gunicorn--graceful-timeout. - Enlaza
0.0.0.0detrás de LB/ingress. TLS termina en el borde, no ad-hoc en el contenedor de la aplicación.
C - Configuración y Secretos
- Valida la configuración con Pydantic 2 al inicio. Falla rápido ante variables de entorno de producción faltantes.
- Inyecta secretos desde SSM/Secrets Manager/K8s Secret. No en capas de imagen o git.
- Separa la configuración por entorno con la misma imagen. Solo las referencias de entorno cambian entre staging/producción.
- Redacta secretos en logs e informes de errores. Usa
SecretStry los depuradores de Sentry. - Planifica la rotación de secretos sin reconstruir. El reinicio gradual recoge nuevos valores.
D - Despliegue y Migraciones
- Actualización gradual con
maxUnavailable: 0para APIs de alta disponibilidad (HA). Aumenta las nuevas instancias (pods) antes de drenar las antiguas. - Las comprobaciones de preparación verifican la base de datos y las dependencias críticas; la vivacidad se mantiene barata. Evita bucles de reinicio ante interrupciones breves.
- Ejecuta migraciones como un Job o fase separada. Expande-contra para cambios de esquema que rompen compatibilidad.
- Prueba de humo
/healthdespués del despliegue en CI/CD. Bloquea la promoción ante fallos. - Documenta el rollback: reimplementa el SHA anterior. Practica el rollback en staging trimestralmente.
E - Observabilidad y Operaciones
- Emite logs estructurados en JSON a stdout. Las plataformas de contenedores los agregan automáticamente.
- Expón métricas de Prometheus o APM en cada servicio. Alarmas de tasa de error y latencia por ruta.
- Rastrea métricas DORA: frecuencia de despliegue, tiempo de entrega, MTTR, tasa de fallos de cambio. Mejora deliberadamente.
- Separa Deployments web y de workers. Escala los workers limitados por CPU de forma independiente.
- Escanea imágenes en CI en busca de CVEs. Reconstruye la imagen base según la cadencia de parches.
Preguntas Frecuentes
¿Cuál es la configuración mínima de producción?
Imagen probada, Gunicorn/Uvicorn, puntos finales de salud, configuración basada en entorno, puerta de prueba CI, rollback de etiqueta con un clic.
¿Cuándo usar Lambda vs K8s?
Lambda para trabajo basado en eventos/picos; K8s para HTTP constante, websockets y plataforma uniforme multi-servicio.
¿Cuántos workers de Gunicorn?
Prueba de carga: comienza cerca del número de CPU para servicios de E/S asíncrona; reduce cuando esté limitado por memoria por worker.
¿Son aceptables los archivos .env alguna vez?
Solo para desarrollo local - nunca en la imagen; producción usa inyección de secretos de plataforma.
¿Cómo manejo archivos estáticos?
CDN o almacenamiento de objetos para escalar; collectstatic en la compilación para Django según sea necesario.
¿Qué pasa con las feature flags?
Desacopla el despliegue de código arriesgado de la exposición: flags desactivadas hasta que se verifique el despliegue.
¿Cómo despliego Django admin de forma segura?
Las mismas reglas de despliegue gradual; las exportaciones de admin de larga duración pueden necesitar un worker separado o ajuste del tiempo de espera.
¿Entornos de vista previa?
El despliegue activado por PR con datos sembrados acelera la revisión antes de la promoción a staging.
¿Cómo encaja el lint de documentación?
Ejecuta npx tsx scripts/lint-docs.ts en pre-build al enviar el sitio de documentación con el monorepo de la aplicación.
¿El mayor anti-patrón de despliegue?
Enviar una migración de base de datos que rompe y un cambio de código de forma atómica: siempre expandir-contraer entre lanzamientos.
Relacionado
- Conceptos Básicos de Despliegue - Fundamentos de WSGI/ASGI
- Despliegues sin Tiempo de Inactividad - graduales y migraciones
- Canales de CI/CD - automatización
- Mejores Prácticas de Observabilidad - señales en producción
- Configuración y Secretos en Producción - configuración 12-factor
Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.