Conceptos básicos de despliegue

10 ejemplos para empezar con Contenedores y Despliegue: 7 básicos y 3 intermedios.

Prerrequisitos

uv venv && source .venv/bin/activate
uv pip install "fastapi>=0.115" "uvicorn[standard]>=0.34" "gunicorn>=23.0" "flask>=3.1"

• Python 3.14.0 con FastAPI 0.115+, Flask 3.1 y paquetes de servidor instalados.

Ejemplos básicos

1. Aplicación WSGI mínima (Flask)

Flask expone una llamada WSGI consumida por Gunicorn.

from flask import Flask
 
app = Flask(__name__)
 
@app.get("/health")
def health():
    return {"status": "ok"}

gunicorn -w 2 -b 0.0.0.0:8000 'app:app'

• app:app significa módulo app, variable app
• Múltiples trabajadores -w manejan solicitudes concurrentes (síncronas)
• La ruta de salud es necesaria para balanceadores de carga y Kubernetes

Relacionado: Gunicorn y Uvicorn - ajuste de trabajadores

2. Aplicación ASGI mínima (FastAPI)

Las aplicaciones FastAPI son ASGI; se ejecutan con Uvicorn o un trabajador Gunicorn+Uvicorn.

from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/health")
async def health():
    return {"status": "ok"}

uvicorn app:app --host 0.0.0.0 --port 8000

• ASGI soporta E/S asíncrona y websockets
• Uvicorn es el servidor ASGI de referencia para desarrollo y producción
• Conéctate a 0.0.0.0 en contenedores, no a 127.0.0.1

Relacionado: Gunicorn y Uvicorn - ASGI en producción

3. Puerto controlado por entorno

Lee el puerto del entorno para despliegues 12-factor.

import os
 
PORT = int(os.environ.get("PORT", "8000"))

• Plataformas (Heroku, Fly, ECS) inyectan PORT
• El valor predeterminado ayuda a uvicorn local sin la variable de entorno
• Valida int() y falla rápidamente ante valores inválidos

Relacionado: Configuración y secretos en producción - configuración de entorno

4. Mapa mental del modelo de procesos

Comprende quién acepta las conexiones TCP.

Cliente -> Balanceador de carga -> Maestro de Gunicorn -> procesos trabajadores -> tu aplicación

• El maestro gestiona los trabajadores; los trabajadores ejecutan el código de la aplicación Python
• Un contenedor a menudo ejecuta un maestro de Gunicorn con N trabajadores
• El trabajo intensivo de CPU puede requerir un proceso trabajador de cola separado

Relacionado: Dockerizar Python - punto de entrada del contenedor

5. Servidor de desarrollo vs. producción

Nunca uses los servidores de desarrollo integrados de Flask/FastAPI en producción.

# solo desarrollo
flask --app app run --debug
 
# producción
gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 app:app

• Los servidores de desarrollo carecen de un modelo de trabajadores robusto y endurecimiento de seguridad
• --reload es solo para iteración local
• Producción usa Gunicorn/Uvicorn con registro y apagado gradual

Relacionado: Mejores prácticas de despliegue - lista de verificación de producción

6. Hook de apagado gradual

Procesa las solicitudes en curso al recibir SIGTERM de los orquestadores.

import signal
 
def handle_sigterm(signum, frame):
    print("apagando con gracia")
 
signal.signal(signal.SIGTERM, handle_sigterm)

• Kubernetes envía SIGTERM antes de la eliminación del pod
• Gunicorn/Uvicorn manejan el tiempo de espera gradual; ajusta --graceful-timeout
• Cierra pools de bases de datos en eventos de apagado (ciclo de vida de FastAPI)

Relacionado: Despliegues sin tiempo de inactividad - actualizaciones continuas

7. Archivos estáticos vs. servidor de aplicaciones

Sirve activos estáticos desde CDN o proxy inverso, no desde trabajadores Python.

location /static/ { alias /var/www/static/; }
location / { proxy_pass http://app:8000; }

• Los trabajadores Python son para solicitudes dinámicas
• Whitenoise es aceptable para archivos estáticos pequeños de Django en PaaS
• Descarga la terminación TLS al balanceador de carga o nginx

Relacionado: Kubernetes para aplicaciones Python - ingress

Ejemplos intermedios

8. Ciclo de vida de FastAPI para inicio/apagado

Gestiona conexiones con el contexto de ciclo de vida ASGI.

from contextlib import asynccontextmanager
from fastapi import FastAPI
 
@asynccontextmanager
async def lifespan(app: FastAPI):
    # inicio
    yield
    # limpieza de apagado
 
app = FastAPI(lifespan=lifespan)

• Reemplaza @app.on_event obsoleto con lifespan
• Inicializa el pool de la base de datos al inicio, ciérralo al apagado
• Las pruebas pueden anular lifespan para aislamiento

Relacionado: Salud y preparación - diseño de sondas

9. Realidad de memoria multi-trabajador

Cada trabajador carga una copia completa de tu aplicación y modelos.

gunicorn -w 4 app:app
# 4x coste de importación, 4x RAM de modelo ML si se carga en la importación

• Escala trabajadores hasta que la CPU o la RAM se saturen; luego escala réplicas
• Carga perezosamente modelos pesados por trabajador en la primera solicitud o usa un servicio de inferencia compartido
• Monitoriza RSS por contenedor en producción

Relacionado: Monitorización de rendimiento (APM) - ajuste de producción

10. Comando de punto de entrada del contenedor

Documenta el comando exacto de producción en el CMD del Dockerfile.

CMD ["gunicorn", "-w", "2", "-k", "uvicorn.workers.UvicornWorker", "-b", "0.0.0.0:8000", "app.main:app"]

• La forma de ejecución (array JSON) evita problemas de señales del shell
• Coincide con el comando en el manifiesto de Kubernetes y docker-compose
• Las pruebas de humo de CI ejecutan el mismo punto de entrada contra la imagen de staging

Relacionado: Dockerizar Python - diseño de la imagen

Versiones de la pila: Esta página se escribió 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+.