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 --frozen en CI y Dockerfile.
• Ejecuta el contenedor como usuario no root. Rutas escribibles solo donde sea necesario.
• .dockerignore excluye .venv, pruebas, git. Contexto más pequeño y compilaciones más rápidas.
• Etiqueta las imágenes con el SHA de git, nunca :latest en 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 CMD exacto 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 terminationGracePeriodSeconds y Gunicorn --graceful-timeout.
• Enlaza 0.0.0.0 detrá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 SecretStr y 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: 0 para 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 /health despué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

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+.