DEV Community: Franchesco Romero

Pooling contra una t3.micro, el día que se reventó...RDS Proxy es la salida?

Franchesco Romero — Mon, 15 Jun 2026 03:53:30 +0000

Cómo un backend de FastAPI + asyncpg comparte un solo Postgres chiquito con sus propios trabajadores en segundo plano y un segundo servicio, por qué el techo de conexiones, no el CPU, es lo que de verdad le pone tope a nuestro autoescalado, la caída en el cambio de hora que nos enseñó la cuenta, y una mirada honesta a RDS Proxy como la válvula de escape (incluyendo la trampa de asyncpg que lo puede dejar sin hacer nada).

TL;DR

Ajuste	Valor	Por qué
Driver	`postgresql+asyncpg`	asíncrono hasta el fondo
`pool_size` / `max_overflow`	8 / 12 (20 por proceso)	subido desde 3/5 después de una caída
`pool_pre_ping`	`True`	mata los sockets muertos tras un reinicio de RDS / inactividad
`pool_recycle`	`1800` s	techo duro que el pre-ping no puede cubrir
Tope de conexiones de RDS	~87 (t3.micro, menos las reservadas)	la verdadera restricción de todo
Pruebas	`NullPool`	sin pooling entre event loops en pytest

La lección que replanteó todo el problema: en un RDS chico, tu cuenta máxima
de tareas la fija max_connections, no el CPU ni la memoria. Un autoescalado
que ignora el presupuesto de conexiones va a escalar directito hacia
QueuePool limit reached, o peor, FATAL: too many connections del mismo
Postgres.

El pool, y la cuenta escondida adentro de él

engine = create_async_engine(
    settings.DATABASE_URL,
    connect_args={"ssl": "prefer"},   # negocia TLS en RDS, texto plano en local
    pool_pre_ping=True,
    pool_size=8,
    max_overflow=12,                  # 8 + 12 = 20 conexiones por proceso
    pool_recycle=1800,
)

Veinte conexiones por proceso se ven modestas hasta que las multiplicas por
cada capa entre ellas y la base de datos:

  pool_size + max_overflow         = 20   por proceso de Python
  × 2 trabajadores de uvicorn      = 40   por tarea de Fargate
  × 2 durante un despliegue rolling = 80  (tarea vieja drenando + tarea nueva arrancando)
  + servicio de inteligencia (3 + 7) = 10 sobre la misma base de datos
  + alembic / ad-hoc / psql        ≈  unas pocas
  ----------------------------------------
  ≈ 87  ← el techo de la t3.micro, con ~0 de margen

Ese es el presupuesto entero, agotado, con una sola tarea de backend. El
tope de conexiones es por qué el backend no puede simplemente desiredCount: 5
— cinco tareas querrían 200 conexiones contra una base de datos que reparte

El tamaño del pool no es un ajuste de afinación de rendimiento aquí; es un ajuste de racionamiento.

Una sutileza que muerde: los trabajadores en segundo plano corren dentro del
proceso. main.py los lanza como tareas de asyncio dentro del mismo proceso
de uvicorn, así que jalan del mismo pool de 20 conexiones que los manejadores
de peticiones HTTP. No hay un pool de trabajadores aparte que dimensionar de
manera independiente, el ciclo del cron y la petición a la API compiten por
ranuras idénticas.

El día que se reventó

QueuePool limit of size 3 overflow 5 reached, connection timed out

El 2026-05-27 el pool estaba en 3/5, 8 conexiones por proceso. En el cambio
de hora, cuatro trabajadores de cron (ama, challenge, marketplace,
daily_token_digest) despertaron todos en el :00, cada uno abriendo una
sesión, mientras el tráfico normal de peticiones también jalaba del pool. Ocho
ranuras, muchos más de ocho prestatarios concurrentes, y las escrituras de
latido empezaron a vencerse por tiempo.

Dos cosas estaban mal, y solo una era "el pool está muy chico":

El pool de verdad estaba muy apretado para la carga combinada de peticiones + trabajadores. 3/5 no dejaba holgura para una estampida de planificadores que, por diseño, se disparan todos en la misma frontera del cron.
Los trabajadores no tenían jitter. Que todo se dispare exactamente en el :00 convierte trabajos independientes en una estampida sincronizada. (Escalonar los desfases del tick es la mitad más barata de la solución; este post trata de la mitad del pool.)

La solución fue subir el pool a 8/12 (20/proceso), elegido porque la cuenta
de conexiones de arriba decía que 20/proceso es el valor más grande que todavía
cabe en dos tareas debajo de 87 durante un despliegue. No es un número redondo;
es el número más grande que el techo permitía.

Mitigaciones que no son dimensionar

Dimensionar te mantiene debajo del tope. Otros tres ajustes evitan que las
conexiones que sí tienes se queden viejas o se fuguen:

pool_pre_ping=True,   # un SELECT 1 barato antes de entregar una conexión; reconecta si está muerta
pool_recycle=1800,    # cierra a la fuerza + reabre tras 30 min pase lo que pase

pool_pre_ping importa porque un proceso de larga vida (un ciclo de
trabajador, un manejador de WebSocket) puede quedarse sentado sobre una
conexión a través de un reinicio de RDS o de un timeout de inactividad de
NAT/firewall. Sin el pre-ping, la primera consulta después de que el socket
muere lanza excepción; con él, SQLAlchemy reconecta calladito. pool_recycle
es el respaldo que el pre-ping no puede dar, algunas conexiones muertas se ven
vivas para un SELECT 1 hasta que de verdad las usas, así que le ponemos tope
directo a la edad de la conexión.

Y en las pruebas, nada de pool:

# el conftest amarra la fábrica de sesiones a un engine con NullPool
engine = create_async_engine(TEST_DATABASE_URL, poolclass=NullPool)

Las conexiones agrupadas no sobreviven a que las pasen entre los event loops
por prueba que crea pytest-asyncio; NullPool abre y cierra una conexión por
cada checkout, lo cual es correcto (aunque más lento) para las pruebas y
esquiva una clase de errores de "atado a un loop distinto".

El hilo trampa

Como la siguiente caída de esta clase es invisible hasta que ya no lo es, la
cadena de la falla está conectada directo a una alarma:

// infra: convierte la cadena exacta del error en una métrica + alarma de CloudWatch
new logs.MetricFilter(this, "DbPoolExhaustedMetricFilter", {
  logGroup,
  filterPattern: logs.FilterPattern.literal('"QueuePool limit of size"'),
  metricName: "DbPoolExhausted",
  metricValue: "1",
});
// Alarma: ≥3 en 15 min → "el pool sigue muy chico; considera subir el RDS
// (t3.micro→small) ANTES de volver a subir pool_size, tope de RDS ≈87 conexiones"

El texto de la alarma codifica el árbol de decisión a propósito: cuando se
dispara, no vuelves a echar mano de pool_size, te quedaste sin
presupuesto de conexiones, así que el movimiento es una base de datos más
grande (o un proxy). Esa es la restricción alrededor de la que gira todo este
post.

El techo de verdad: el autoescalado está atado a las conexiones

Aquí está el problema estratégico. El backend autoescala por CPU
(scaleOnCpuUtilization). Pero el escalado por CPU y el presupuesto de
conexiones están en conflicto directo: en el momento en que la presión de CPU
nos escala de 1 tarea a 2, las conexiones brincan de ~40 a ~80; una tercera
tarea rebasaría 87 y Postgres empezaría a rechazar conexiones con
FATAL: too many connections, una caída causada por la cosa que debía
prevenirla.

Así que maxTasks está fijado en silencio por max_connections, no por la
carga. No podemos de verdad usar escalado horizontal para los picos de
tráfico, porque la base de datos no puede emitir las conexiones que las tareas
nuevas demandan. Subir la clase de la instancia de RDS compra margen lineal
(t3.small ≈ 2× las conexiones) pero cuesta dinero y solo mueve el muro. Lo
que quita el muro en lugar de moverlo es un proxy de conexiones.

RDS Proxy: la válvula de escape, y la trampa de asyncpg

RDS Proxy se sienta entre la app y Postgres y multiplexa: cientos de
conexiones de cliente comparten un pool chiquito de conexiones reales al
backend. La app abre conexiones a sus anchas; el proxy mantiene la cuenta real
de conexiones a la base de datos baja y estable. Eso desacopla la cuenta de
tareas de max_connections, el autoescalado por fin puede escalar por CPU sin
el muro de conexiones, y una estampida de trabajadores le presta del proxy en
lugar de a la base de datos.

Eso es el discurso de venta. Aquí está la parte que el discurso se calla, y la
razón por la que esto es una solución "posible" y no una ya publicada:

asyncpg + prepared statements = fijado de conexión. RDS Proxy solo puede
multiplexar cuando una sesión está "limpia". En el momento en que una sesión
hace algo con estado de conexión, un prepared statement, un SET, un advisory
lock, una tabla temporal, un LISTEN a nivel de sesión, el proxy fija ese
cliente a una sola conexión de backend por el resto de su vida y deja de
multiplexarlo. Y asyncpg, por default, cachea prepared statements para cada
consulta que corre. Tal como viene, asyncpg sobre RDS Proxy fija casi todo, y
pagaste por un proxy que se comporta como un paso directo, más un salto de
latencia.

Las mitigaciones, en orden de cuánto duelen:

# Deshabilita el caché de prepared statements de asyncpg para que RDS Proxy pueda multiplexar.
engine = create_async_engine(
    settings.DATABASE_URL,
    connect_args={
        "ssl": "require",                 # RDS Proxy exige TLS
        "statement_cache_size": 0,        # sin caché de prepared statements
        "prepared_statement_cache_size": 0,
    },
    poolclass=NullPool,   # deja que el PROXY haga el pool; el pooling del lado de la app ya es redundante
)

statement_cache_size=0 impide que asyncpg cachee prepared statements, que es lo que mantiene las sesiones multiplexables. Costo: un pequeño sobrecosto por consulta de volver a preparar, normalmente un buen trato a cambio de conseguir multiplexar siquiera.
Audita los otros disparadores de fijado. Nuestro conftest de CI usa pg_advisory_lock para montar la base de datos template, y algunos flujos usan estado a nivel de sesión, cada uno es un fijado. Detrás de un proxy quieres esos acotados con fuerza o movidos a nivel de transacción (pg_advisory_xact_lock) para que el fijado se libere al hacer commit.
Deja que el proxy sea dueño del pool. Con RDS Proxy haciendo la multiplexación, el pool_size del lado de la app se vuelve doble-pooling; NullPool (o un pool diminuto) en la app y deja que el proxy racione.

La economía del proxy

RDS Proxy no es de capa gratuita. Se cobra por vCPU de la instancia de la
base de datos, más o menos $0.015 / vCPU-hora. Para una t3.micro de 2 vCPU
eso son ≈ $0.03/hr ≈ $21–22/mes, sobre un stack cuya premisa entera es
la Capa Gratuita de AWS. Así que la comparación de verdad es de tres vías:

Opción	$/mes (delta)	Qué te compra	Qué te cuesta
Quedarte en 8/12 sobre t3.micro	$0	nada nuevo	el muro de conexiones se queda; sin escalado horizontal real
Subir t3.micro → t3.small	~$13	~2× conexiones (~170)	mueve el muro, no lo quita; sigue siendo finito
Agregar RDS Proxy	~$21	quita el muro; autoescalado fiel al CPU; suavizado de failover	un salto de latencia; reconfigurar asyncpg; rompe la Capa Gratuita

La lectura honesta: a nuestra escala actual el muro todavía no aprieta. Una
tarea cabe, el subidón a 8/12 absorbió la estampida de trabajadores, y la
alarma no se ha disparado desde entonces. RDS Proxy se gana sus $21 el día que
de verdad necesitemos una segunda y tercera tarea para el tráfico, no antes.
Comprarlo ahora sería pagar una mensualidad para resolver un problema que
todavía no tenemos, y heredar la auditoría de fijado de asyncpg sin beneficio
presente. El disparador para adoptarlo es concreto: la alarma de escalado por
CPU y la alarma de presupuesto de conexiones disparándose en la misma
ventana, ese es el momento en que el CPU quiere más tareas y las conexiones
no las pueden suministrar, y el proxy es lo único que resuelve la
contradicción.

Lo que te diría

Encuentra tu techo real primero. SELECT * FROM pg_settings WHERE name = 'max_connections'; luego réstale las ranuras reservadas. Cada decisión de pooling es río abajo de ese único número.
El tamaño del pool es un ajuste de racionamiento en un RDS chico, no un ajuste de rendimiento. Dimensiónalo desde el presupuesto de conexiones (por-proceso × trabajadores × tareas × traslape-de-despliegue), no desde un benchmark.
Los trabajadores dentro del proceso comparten el pool web. Si tus planificadores se disparan todos en la misma frontera del cron, son una estampida sincronizada contra el pool de peticiones. Agrega jitter; dimensiona para el pico.
pre_ping + recycle no son opcionales para procesos asíncronos de larga vida detrás de un NAT/firewall o enfrente de una base de datos que se puede reiniciar.
RDS Proxy quita el muro de conexiones, pero con asyncpg, pon statement_cache_size=0 y audita tus advisory locks, o fija y no hace nada. Mide la tasa de fijado (DatabaseConnectionsCurrentlySessionPinned) antes de cantar victoria.
Compra el proxy cuando el muro apriete, no antes. La señal es el autoescalado por CPU y el agotamiento de conexiones peleándose en la misma ventana de 15 minutos.

Si te llevas una sola cosa: en un Postgres administrado chico, las conexiones
— no el CPU, son la unidad de escalado. Dimensiona tu pool desde ese
presupuesto, alarma sobre la cadena exacta de agotamiento, y trata a RDS Proxy
como la cosa que compras el día que el muro de conexiones empieza a costarte
tareas que de verdad necesitas.

500 portadas distintas de un solo modelo de $0.04: arte de portada con IA, consistente con la marca, en un generador económico

Franchesco Romero — Mon, 15 Jun 2026 00:59:08 +0000

La lección de cabecera: en un modelo económico, la calidad no la consigues escribiendo un mejor prompt único, la consigues decidiendo en qué es bueno el modelo, haciendo el resto tú mismo, y diseñando la variedad como una característica del producto en lugar de esperar que la semilla la entregue.

Arquitectura

Admin (SPA) ──POST /blog/generate-image──▶ FastAPI (Fargate, us-east-1)
                                              │
                              boto3 bedrock-runtime (us-west-2)
                                              │
                                   Stable Image Core ──▶ PNG en base64 (2016×1152)
                                              │
                       Pillow: composición opcional del lockup de marca
                                              │
                          redimensionar → WebP (1200×630) → S3 → CloudFront

Una sola petición sincrónica. Sin cola, sin GPU, sin hospedar el modelo.
El endpoint es un orquestador delgado: construye un prompt, llama a
Bedrock, opcionalmente superpone el logo, y le entrega los bytes a la
pipeline de imágenes que ya existía (que quita los metadatos, redimensiona, y convierte a WebP).

La decisión arquitectónica más importante de todas es lo que no está aquí: sin modelo con ajuste fino, sin LoRA, sin grupo de autoescalado de GPU. La consistencia de marca se compra por completo con un envoltorio de prompt y un post-proceso. Eso mantiene el costo marginal de una portada en unos centavos y el costo operativo en cero, que es justo el punto para arte editorial de bajo volumen.

Fase 0, el bug del paso directo

La primera versión hizo lo obvio: tomar el texto y mandarlo al
modelo.

# NO LO HAGAS, esto es el punto de partida para ejemplificar
body = {"prompt": admin_text, "mode": "text-to-image"}

El agente interno de autoría, mientras tanto, envolvía cada prompt en unestilo de la casa fijo. Así que las portadas hechas por el agente eran fieles a la marca y las tecleadas a mano eran un terreno sin reglas misma plataforma, dos identidades visuales. La solución es un envoltorio.

Fase 1, un estilo de la casa es un envoltorio de prompt más un prompt negativo

def _styled_cover_prompt(raw: str) -> str:
    return (
        "Wide editorial illustration for a community blog post. "
        f"Theme: {raw.strip()}. "
        "Modern flat-vector art style with subtle gradients, a warm "
        "purple and teal palette, optimistic mood. Abstract metaphor, "
        "no people in close-up, no readable text anywhere. "
        "Clean 16:9 hero composition."
    )

NEGATIVE = "text, words, watermark, logo, signature, low quality, blurry, frame, border"

El prompt negativo importa tanto como el positivo. text, words está
haciendo trabajo de verdad: es la forma más barata de impedir que el
modelo garabatee letras falsas por todo el arte. Nos vamos a apoyar fuerte en eso en un momento.

Este es el estilo de la casa "plano". Luego quisimos un segundo pictórico, dorado y oscuro, para contenido gamificado / de torneo. Ahí fue donde el modelo económico empezó a mostrar sus limites.

Fase 2, nunca dejes que el modelo escriba texto; superpón el logo tú mismo

Todo modelo de difusión de esta gama renderiza el texto como
pseudo glifos garabateados. El arte de referencia que perseguíamos tenía un wordmark; el nuestro salió como MYBRAND → MYBARND. Dos opciones: pelear con el modelo, o dejar de pedirle que haga tipografía.

Dejamos de pedírselo. El prompt positivo dice no readable text anywhere, el prompt negativo prohíbe text, logo, y el lockup de marca real y transparente, wordmark incluido, se superpone encima con Pillow después de generar.

El pegado ingenuo falla: un logo dorado sobre una pintura cargada de
dorado se desvanece. La solución es un respaldo oscuro difuminado detrás
del lockup, luego el lockup, abajo a la derecha:

def overlay_brand(image_bytes: bytes) -> bytes:
    base = Image.open(io.BytesIO(image_bytes)).convert("RGBA")
    logo = Image.open(LOGO_PATH).convert("RGBA")
    target_w = int(base.width * 0.22)
    logo = logo.resize((target_w, int(logo.height * target_w / logo.width)))
    x = base.width - logo.width - int(base.width * 0.035)
    y = base.height - logo.height - int(base.height * 0.035)
    base.alpha_composite(_soft_dark_ellipse(base.size, logo, x, y))  # respaldo de contraste
    base.alpha_composite(logo, (x, y))
    return _to_png(base.convert("RGB"))

Wordmark nítido, legible sobre cualquier arte, cero tipografía generada. Este es el principio general para modelos económicos: cualquier cosa que tenga que ser exacta al píxel, texto, logos, layout, lo haces en código determinista, no en el prompt.

Fase 3, Core fusiona sujetos; diseña alrededor de eso

Pedimos "un grifo de frente a un dragón". Core regresó una sola criatura con partes de grifo y de dragón fusionadas. Este es un modo de falla conocido de los modelos chicos: dos sujetos independientes en un mismo cuadro se mezclan.

Dos mitigaciones, las dos baratas:

Prompt negativo: fused creature, merged animals, two-headed, hybrid, extra limbs, extra heads.

Componer alrededor de arquetipos conocidos. Un consejo alrededor de una mesa redonda, un grupo de cuatro aventureros, figuras frente a un portal esas son composiciones que el modelo ha visto miles de veces y monta correctamente, multitud y todo. Un duelo libre de dos bestias distintas no lo es. Convertimos las cosas que queríamos retratar (comunidad, colaboración) en arquetipos que el modelo de verdad puede renderizar.

La regla general: no pelees contra los ajustes composicionales del modelo elige sujetos o temas que se adecuen a ellos.

El callejón sin salida que vale la pena documentar: fusión cálido + frío

Intentamos reproducir una referencia que fusionaba una taberna medieval acogedora con interfaces holográficas cian, cálido y frío, fantasía y tecnología, en un mismo cuadro. Catorce generaciones a través de cuatro estrategias de prompt después, el veredicto fue concluyente:

La tecnología enterrada en una descripción cálida → Core soltaba la
tecnología por completo (taberna pura).

La tecnología al frente → Core inundaba el cuadro de pantallas cian (sala de servidores pura).

Equilibrado, con cuentas explícitas ("dos o tres hologramas") → revertía a uno o al otro, dependiendo de la semilla.

Core no puede sostener dos estéticas fuertes y opuestas en tensión. Un modelo más fuerte (la referencia salió de uno) sí puede; Core no. Anotamos el hallazgo y seguimos adelante en lugar de quemar más generaciones contra un techo del modelo. El movimiento de ingeniería honesto en una gama económica es saber cuándo pegaste contra el muro y dejar de pagar por darle de topes, la alternativa (componer los hologramas nosotros mismos de manera procedural) era real pero no valía la pena para el valor.

Fases 4–6, diseñar la variedad, porque la semilla no lo va a hacer

Este era el problema de producto de verdad. Con el envoltorio "épico"
pesado puesto, prompts distintos producían imágenes casi idénticas. Dos
temas opuestos, "trabajo remoto asíncrono entre zonas horarias" y
"depurar una caída de producción a las 3am", los dos renderizaban al
mismo guerrero dorado con una espada en llamas. El andamio de estilo
(elementos de héroe en dorado bruñido, ambiente heroico ceremonial,
heráldica de gremio) era tan dominante que el modelo se aferraba a él e ignoraba el tema. La semilla aleatoria no ayudaba: el prompt restringe la salida mucho más de lo que la semilla la perturba.

Tres palancas, cada una medida contra la anterior:

4a. Encabeza con el tema; degrada el estilo a un tratamiento. Pon el sujeto primero, aplica el look como un acabado en lugar de como palabras clave que dictan el sujeto. De repente "trabajo remoto" renderizaba a un desarrollador frente a un mapamundi brillante y "depurar a las 3am" renderizaba a un ingeniero en un cuarto de control oscuro. Fidelidad al tema: arreglada. Pero cada portada seguía siendo dorado cálido sobre fondo oscuro.

4b. Rota la paleta. La paleta fija única era el mayor motor de
mismidad. Un conjunto rotatorio, teal/brasa/azul acero/violeta/esmeralda/carmesí, cada uno conservando el dorado como hilo conductor, rompió el monocromo. El color y el ambiente ahora variaban por generación.

4c. Rota el escenario. Los temas de mi blog son casi sinónimos, así que aun con la rotación de
paleta, todavía se montaban igual. La solución que funcionó: meter el sujeto en un escenario distinto y fiel a la marca cada vez, biblioteca, fragua, pico de montaña, observatorio, mercado. Tres temas sinónimos de carrera luego renderizaron como una biblioteca, una fragua, y un observatorio.

def _epic_cover_prompt(raw, motif="champion", composition=None, palette=None, setting=None):
    scene = MOTIFS.get(motif, "")
    if scene:                                  # un motivo ES el sujeto
        subject = f"{scene}, evoking {raw.strip()}"
    else:                                      # si no: el tema encabeza, metido en un escenario
        subject = f"{raw.strip()}, {setting or random.choice(SETTINGS)}"
    comp = composition or random.choice(COMPOSITIONS)
    pal  = palette or random.choice(PALETTES)
    return f"{subject}. {comp}. Rendered as painterly key-art, ... a rich {pal} palette ..."

La variedad es combinatoria y del lado del servidor: 10 escenarios × 7 paletas × 8 composiciones ≈ 560 encuadres distintos, elegidos al azar por llamada, antes de que la semilla siquiera entre. La variedad dejó de ser algo que esperábamos que el modelo proveyera y se volvió un espacio de parámetros que poseemos.

Límite honesto: para exactamente el mismo tema, Core todavía tiende a
montar el sujeto igual, los modificadores de composición son débiles
contra una escena fuertemente implicada. La variedad de verdad viene de temas distintos + paleta + escenario + semilla, no de volver a tirar un mismo prompt.

Fase 6, un lente de campaña. Un encuadre de campaña tipo RPG se mapea sobre cada tema: aprender = misiones, roles = clases, crecimiento = subir de nivel, comunidad = el grupo. Es un tercer estilo junto a los otros (no reemplazamos los que funcionan), reutilizando la misma maquinaria de rotación con escenas de RPG, un tablero de misiones, un grupo de clases, un árbol de habilidades. Mismo motor, narrativa más rica, más variedad gratis.

La economía

A bajo volumen editorial, el modelo de API por imagen gana de manera
decisiva. Las cifras son precio de lista al momento de escribir (us-west-2) y se van a mover, trátalas como proporciones, no como cotizaciones.

Opción	Costo unitario	Costo fijo	Operación
Bedrock Stable Image Core	~$0.04 / imagen	$0	ninguna
Bedrock Stable Image Ultra	~$0.14 / imagen	$0	ninguna
SDXL autoalojado (g5.xlarge)	~$0 marginal	~$1.00 / hora-GPU siempre encendido o dolor de arranque en frío	AMI, escalado, parchado
Google Imagen (Vertex)	~$0.04 / imagen	$0	ninguna, pero una segunda nube
Midjourney	n/a (suscripción)	$10–60 / mes	sin API sancionada

Un blog que genera un puñado de portadas al día cuesta centavos al mes en Core. Para llegar al punto de equilibrio contra una sola g5.xlarge siempre encendida (~$720/mes) tendrías que generar ~18,000 portadas al mes. Yo genero quizás 100. La cuenta del autoalojado solo se voltea a una escala que nunca vamos a alcanzar para arte editorial, e incluso entonces te apuntaste a AMIs, fijado de drivers, y un autoescalador. El modelo más barato que pasa la barra de calidad, llamado por imagen, es la respuesta correcta aquí, y reconocer eso temprano nos ahorró un flujo de trabajo completo de operación de GPU.

La trampa de región

Los modelos de imágenes de Bedrock no están en cada región, y el modelo que quieres acota la región que llamas. El backend corre en us-east-1; Stable Image Core se aprovisionó en us-west-2. Así que el
cliente está fijado a otra región a propósito:

client = boto3.client("bedrock-runtime", region_name="us-west-2")  # NO la región de la app

Tres consecuencias que vale la pena saber antes de armar la arquitectura alrededor de esto:

La disponibilidad es por modelo, por región. "Bedrock está en mi región" no es "este modelo está en mi región". Revisa el modelo, no el servicio.

Las llamadas a otra región agregan latencia y cruzan una frontera de
datos. Para arte de portada de dispara-y-olvida eso está bien; para
cualquier cosa sensible a la latencia o a la residencia no lo está, y
puede que necesites aprovisionar el modelo en la región de tu app o elegir otro.

El acceso al modelo es una concesión explícita. Habilitar un modelo de Bedrock es un paso de consola por cuenta/región, y el IAM tiene que permitir bedrock:InvokeModel sobre ese ARN del modelo. Un ARN con comodín sobre el modelo base nos ahorró re-editar la política en cada cambio de modelo.

Lo que un modelo económico no puede hacer (medido, no adivinado)

Tipografía. Nunca. Superpón el texto y los logos tú mismo.

Dos estéticas opuestas en un cuadro (cálido/frío, fantasía/tecnología). Se colapsa a una. Elige un carril o superpón.

Escenas libres de varios sujetos. Dos sujetos distintos se fusionan. Usa arquetipos que el modelo ya monta (mesas, grupos, portales).

Variedad composicional por tema bajo demanda. Una escena fuertemente
implicada se monta igual sin importar las pistas de cámara. Diseña la
variedad a través de paleta/escenario/semilla en lugar de esperarla de un solo prompt.

Ninguno de estos fue un motivo de descarte. Cada uno se volvió una
restricción de diseño que empujó el trabajo fuera del modelo y hacia
código que controlamos, que es justo donde quieres que vivan las partes deterministas de una marca de todos modos.

Lo que te diría

Decide el trabajo del modelo, luego recupera el resto. El texto, los
logos, el layout, y la variedad exacta de marca son deterministas; hazlos en código. Deja que el modelo pinte.

Un estilo de la casa es un envoltorio de prompt + un prompt negativo, no un ajuste fino. Para bajo volumen, ese es todo el presupuesto de
consistencia de marca que necesitas.

La variedad es un espacio de parámetros que posees, no una semilla a la que le cruzas los dedos. Rota los ejes que no definen la marca (paleta, escenario, cámara); fija el que sí (aquí, el dorado).

Pon precio a la API por imagen contra una GPU con honestidad. Por debajo de decenas de miles de imágenes al mes, la API gana en costo y en operación.

Si te llevas una sola cosa: en un modelo de imágenes económico, la calidad y la variedad no son cosas que pides en un prompt, son cosas que diseñas alrededor de los límites conocidos del modelo. El prompt es la parte más chica.

SEO en 2026, parte 2: la captura rankea — ahora haz que convierta

Franchesco Romero — Sat, 13 Jun 2026 23:50:05 +0000

El post anterior terminó donde terminan la mayoría de los posts de "ya hicimos SEO": la página es indexable.

Dos cosas se rompen justo después de esa línea de meta, y ninguna aparece en un puntaje de Lighthouse:

La captura rankea pero no convierte nada. El HTML que el rastreador indexó y el HTML al que aterriza un humano sin sesión, tiene el contenido pero ninguna llamada a la acción, porque la llamada a la acción vive en el paquete de JavaScript que el rastreador nunca corrió. Rankeaste para la búsqueda y luego no dijiste nada.
El siguiente despliegue des indexa la página durante unos minutos. Una SPA con hash de contenido que borra sus fragmentos viejos al desplegar le entrega a cada pestaña abierta y a cada re rastreo a media propagación, un 404 sobre un módulo que todavía espera. La página que rankeaba ayer hoy lanza Failed to fetch dynamically imported module.

TL;DR

Capa	Antes (fin de la parte 1)	Después
CTA en un reporte indexado	renderizado solo por la SPA — ausente de la captura que lee el rastreador y del primer pintado sin sesión	renderizado en el servidor dentro de la captura, derivado de los datos de la propia página, indexable
Texto del CTA / enlaces de destino	fijos en el código → un re-despliegue para cambiar una palabra	configuración en tiempo de ejecución en una bolsa de ajustes JSONB; editable desde el admin, sin re-despliegue; los pre-renderizados se refrescan al guardar
CTA por audiencia	una sola variante	anónimo → unirse; autenticado → enlaces directos al siguiente paso
Despliegue de assets	`aws s3 sync --delete` — los fragmentos viejos con hash se borran en el instante en que aterriza el paquete nuevo	sync aditivo (sin `--delete`); los fragmentos viejos + nuevos coexisten; una pestaña abierta sigue funcionando
Limpieza del paquete viejo	implícita (el delete)	regla explícita de ciclo de vida de S3 — `assets/` expira 30 días después de que un paquete deja de servirse
Invalidación de CloudFront	`"/*"` (desperdicio; los assets son inmutables)	solo `"/index.html"` — el único objeto que cambia un despliegue
Falla al cargar un fragmento	la pantalla roja de error de React Router	`vite:preloadError` → una sola recarga acotada hacia el paquete fresco

El hilo conductor: una captura pre-renderizada es necesaria pero no
suficiente. La parte 1 hizo que la captura existiera. La parte 2 hace
que haga su trabajo y que sobreviva al siguiente git push.

El punto de partida

La fase 6 de la parte 1 nos dejó con un parchador de HTML por ruta: para
cada reporte público, renderiza su markdown a HTML sanitizado del lado
del servidor, lo inyecta dentro del <div id="root"> de la cáscara de la
SPA, parcha el <title> / description / canonical, y agrega el JSON-LD de
Article. Los rastreadores leen el HTML inyectado; la SPA en vivo hidrata
encima de él al montarse.

myapp/backend/app/services/report_seo.py   # markdown → HTML + JSON-LD, inyectado en la cáscara
myapp/backend/app/services/prerender.py     # parche genérico del head + inyección en #root
myapp/backend/app/jobs/render_reports.py    # itera los reportes publicados, escribe un index.html por ruta

Funcionó. Los reportes rankearon. Luego vimos qué recibía de verdad el visitante que rankeaba, y qué le hacía el siguiente despliegue.

Fase 1: la trampa del CTA solo-en-la-SPA

La página de reporte es un imán de tráfico orgánico buenísimo: una tabla de datos que la gente busca por nombre. Así que agregamos un bloque de conversión al final, "así es como puedes actuar sobre esto", como un componente de React en la ruta del reporte. Lo publicamos, se veía increíble en el navegador.

Luego: le haces curl a la URL pública como la ve un rastreador.

curl -s https://myapp.example/reports/<slug> | grep -c "Quieres llegar"
# 0

El CTA no estaba en ningún lado del HTML entregado. Obvio en
retrospectiva — el pre-renderizado (report_seo.py) renderiza el cuerpo
del markdown dentro de la captura; el CTA era un componente de React,
montado solo después de que carga el paquete. Entonces:

El rastreador indexó el cuerpo del reporte y nunca vio el CTA. La captura que cacheó para los motores de respuestas de IA es un callejón sin salida.
El humano sin sesión — la mayoría del tráfico orgánico, vio el CTA un instante tarde (después de la hidratación), y si rebotaba durante la carga del JS, nunca.

Un CTA que solo existe del lado del cliente es un CTA que no existe para exactamente la audiencia que una captura está hecha para servir. La solución es renderizarlo dentro de la captura, igual que el cuerpo — pero una cadena estática pegada en cada reporte es débil. La versión interesante está derivada de los datos de la propia página.

Fase 2: un CTA construido con los datos de la propia página

Cada reporte ya calcula un agregado ordenado antes de escribirse, las filas de las que el reporte trata. Habíamos estado tirando esa
estructura después de generar la prosa. En lugar de eso, conserva el
top-N y persístelo junto al reporte (una columna JSONB key_findings sin usar ya estaba en el modelo, sin migración):

# myapp/backend/app/agents/report/generator.py (extracto)
def _top_findings(rows: list[dict], limit: int = 3) -> list[dict]:
    """Top-N de filas para el CTA de conversión. Deduplicado por categoría
    canónica para que el CTA muestre variedad, no la misma tres veces.
    Persistido en ``Report.key_findings`` y leído por el pre renderizado ypor la SPA.
    """
    valid = [r for r in rows if r.get("value")]
    valid.sort(key=lambda r: r["value"], reverse=True)
    seen, top = set(), []
    for r in valid:
        cat = canonical_category(r["category"])
        if cat in seen:
            continue
        seen.add(cat)
        top.append({"category": cat, "label": label_for(cat),
                    "region": r["region"], "value": r["value"]})
        if len(top) >= limit:
            break
    return top

Luego el pre renderizado crece un bloque de CTA, inyectado en la captura entre el cuerpo y el footer, pura construcción de cadenas, sin navegador:

# myapp/backend/app/services/report_seo.py (extracto)
def _render_cta(cta_config: dict | None, findings: list[dict] | None) -> str:
    if not cta_config or not cta_config.get("enabled", True):
        return ""
    hook = ""
    if findings:
        t = findings[0]
        hook = (
            '<p class="cta-hook">This month, '
            f"<strong>{escape(t['label'])}</strong> leads in "
            f"{escape(region_name(t['region']))} at "
            f"<strong>${int(t['value']):,}</strong>.</p>"
        )
    items = "".join(
        f'<li><a href="{escape(s["route"])}">{escape(s["label"])}</a>'
        + (f" — {escape(s['blurb'])}" if s.get("blurb") else "")
        + "</li>"
        for s in cta_config.get("services", []) if s.get("label")
    )
    return (
        '<aside class="report-cta">'
        f"{hook}"
        f"<h2>{escape(cta_config['headline'])}</h2>"
        f"<p>{escape(cta_config['subcopy'])}</p>"
        f"<ul>{items}</ul>"
        f'<p><a class="btn" href="{escape(cta_config['join_route'])}">'
        f"{escape(cta_config['join_label'])}</a></p>"
        "</aside>"
    )

La línea del gancho, "This month, X leads at $N" ,cambia por reporte y por mes, calculada desde los datos para los que el reporte ya rankea. El rastreador la indexa. El visitante sin sesión la ve en el primer pintado.

Ahora curl regresa 1.

Las pruebas amarran la forma, todas puras (sin base de datos, sin red):
test_report_page_renders_indexable_cta (el gancho + un enlace de
servicio real + el botón de unirse, todos aterrizan dentro del
<div id="root">), test_report_page_cta_disabled_renders_nothing,
test_report_page_cta_without_top_data_still_shows_block (un reporte
heredado sin key_findings igual recibe la propuesta de valor, nada más sin gancho), y test_report_page_no_cta_config_is_backward_compatible (el
pre renderizado llamado a la antigua, sin argumento de CTA, igual
renderiza).

Fase 3: editable sin re despliegue

Un CTA fijo en el código significa un despliegue para arreglar una errata.
Peor, los enlaces a los que apunta el CTA son decisiones de producto que cambian más rápido que el código. Así que el texto, las rutas de destino, y el interruptor de encendido/apagado viven en una configuración de tiempo de ejecución la misma bolsa de ajustes JSONB por agente que el resto del admin ya usaba.

# myapp/backend/app/services/report_cta_config.py (extracto)
DEFAULTS = {
    "enabled": True,
    "headline": "Want to get there?",
    "subcopy": "Here's how to close the gap:",
    "join_label": "Join", "join_route": "/register",
    "services": [ ... ],   # [{key, label, route, blurb}, ...]
}

async def resolve_cta_config(db) -> CtaConfig:
    row = await _load(db)                      # una sola búsqueda por PK
    overrides = dict(row.config_json or {}) if row else {}
    return CtaConfig(**{k: overrides.get(k, v) for k, v in DEFAULTS.items()})

El endpoint GET es público — es texto y rutas internas, sin secretos, así que la SPA y el pre renderizado leen la misma configuración resuelta.
El PATCH está protegido para admin y validado. La única regla que vale la pena imponer en la orilla: cada enlace es una ruta interna.

def _clean_route(key, raw):
    value = _clean_str(key, raw)
    if not value.startswith("/"):
        raise HTTPException(400, detail=f"{key} must be an internal route (/...)")
    return value

Sin ese chequeo, "edita el CTA" se vuelve "pega un https:// en
cualquier lado de tus páginas indexadas de mayor tráfico", un punto de apoyo de redirección abierta / enlace fuera del sitio en exactamente las superficies en las que más confían los rastreadores.

Pruebas:
test_validate_cta_config_rejects_external_route,
test_cta_config_patch_merges_and_persists (el PATCH se fusiona sobre los
defaults, no aplasta las llaves que no tocó), test_cta_config_reset,
test_cta_config_defaults_when_unset.

Un detalle de cableado que importa para el SEO: un cambio de configuración tiene que refrescar las capturas, o el rastreador sigue viendo el CTA viejo. El CTA está en cada reporte, así que el PATCH del admin dispara un re renderizado en segundo plano de todas las páginas de reporte publicadas no solo la que se está editando.

# myapp/backend/app/api/v1/admin_reports.py (extracto)
@router.patch("/reports/cta-config")
async def update_cta(body, background, _admin = Depends(require_admin)):
    result = await client.update_cta_config(body.config)
    background.add_task(prerender_publish.refresh_all_reports)  # re-captura todos
    return result

Fase 4: el espejo en la SPA, anónimo vs autenticado

El CTA de la captura es la variante anónima — eso es lo que son un
rastreador y un visitante sin sesión. Pero una vez que la SPA hidrata para un miembro con sesión, el mismo bloque debe hacer algo distinto: no "unirse", sino enlaces directos al siguiente paso. Misma configuración, dos renderizados.

// myapp/frontend/src/components/report/ReportCTA.tsx (extracto)
export default function ReportCTA({ topFindings }: Props) {
  const { data: cfg } = useReportCtaConfig();
  const { isAuthenticated } = useAuth();
  if (!cfg || !cfg.enabled) return null;

  const top = topFindings?.[0] ?? null;
  return (
    <aside className="report-cta">
      {top && (
        <p>This month, <strong>{top.label}</strong> leads in{" "}
          {regionName(top.region)} at <strong>${top.value.toLocaleString()}</strong>.</p>
      )}
      <h2>{cfg.headline}</h2>
      <ul>
        {cfg.services.map((s) =>
          isAuthenticated
            ? <li key={s.key}><Link to={s.route}>{s.label}</Link>{s.blurb && ` — ${s.blurb}`}</li>
            : <li key={s.key}><span>{s.label}</span>{s.blurb && ` — ${s.blurb}`}</li>,
        )}
      </ul>
      {isAuthenticated
        ? <Link className="btn" to={cfg.services[0]?.route}>Continue</Link>
        : <Link className="btn" to={cfg.join_route}>{cfg.join_label}</Link>}
    </aside>
  );
}

El componente lee topFindings directo de la carga del reporte (el mismo key_findings que usó el pre-renderizado), sin una segunda petición, sin recalcular del lado del cliente. Las pruebas cubren los tres estados: anónimo muestra el botón de unirse y los servicios como texto plano; autenticado muestra los servicios como enlaces más una acción primaria de "continuar"; la configuración deshabilitada no renderiza nada.

Eso cierra el hueco de conversión. La otra falla estaba esperando en el CI.

Fase 5: el despliegue que des indexa tu página

Esta la atrapamos con el monitoreo de usuarios reales de la parte 1. El recolector de Web Vitals de la fase 5 del primer post también muestrea los errores no atrapados, y después de cada despliegue de frontend había una ráfaga chica y confiable en el canal de errores:

TypeError: Failed to fetch dynamically imported module:
https://myapp.example/assets/ReportPage-BuE6Rmpx.js

Siempre un fragmento de ruta, siempre en los minutos justo después de un despliegue, siempre un hash que ya no existía. La causa raíz era una sola bandera en el despliegue:

# antes — myapp/.github/workflows/deploy-frontend.yml
aws s3 sync frontend/dist s3://$BUCKET --cache-control "...immutable" --delete

--delete quita cada objeto que no está en el dist/ nuevo, incluyendo los fragmentos con hash de la compilación anterior. Secuencia:

Un visitante carga la app. Su pestaña guarda un index.html que referencia ReportPage-BuE6Rmpx.js.
Aterriza un despliegue. Compilación nueva → ReportPage-OTHERHASH.js. El sync borra ReportPage-BuE6Rmpx.js.
El visitante hace clic hacia una ruta diferida → la SPA importa el fragmento que todavía recuerda → 404 → Failed to fetch dynamically imported module → la pantalla roja de error de React Router.

Y no son solo las pestañas abiertas: un rastreador que vuelve a pedir la URL en vivo durante la ventana de propagación de CloudFront puede hidratar contra un paquete reemplazado a medias. La página que rankeaba está, por esos minutos, rota.

Los headers de caché ya estaban bien — los assets con hash immutable por un año, el index.html en no-cache. El bug era puramente que los assets viejos desaparecían. Los paquetes con hash de contenido están direccionados por contenido: el viejo y el nuevo pueden y deben coexistir.

Solución 1, la cura: desplegar los assets de manera aditiva. Quita el --delete.

# después — aditivo: los fragmentos con hash viejos + nuevos coexisten
aws s3 sync frontend/dist s3://$BUCKET --cache-control "...immutable"

Solución 2, la limpieza: una regla de ciclo de vida de S3 para que "nunca borrar" no signifique "acumular por siempre". Los paquetes
reemplazados envejecen 30 días después de que dejan de servirse mucho después de cualquier sesión en vivo, lo bastante corto como para no amontonarse.

// myapp/infra/lib/frontend-stack.ts (extracto)
new s3.Bucket(this, "SpaBucket", {
  // ...
  lifecycleRules: [{
    id: "expire-old-build-assets",
    prefix: "assets/",                       // solo el paquete con hash
    expiration: cdk.Duration.days(30),
  }],
});

Solución 3, el recorte de costo: angostar la invalidación.
index.html es el único objeto que cambia un despliegue (está en
no-cache, así que la orilla lo revalida). Los assets con hash son
inmutables, invalidar /* pagaba por desalojar entradas de caché que nunca pueden quedar viejas.

# antes: --paths "/*"      # desperdicio; los assets son inmutables
# después:
aws cloudfront create-invalidation --distribution-id "$ID" --paths "/index.html"

Prueba de que funcionó, directo del bucket después del primer despliegue aditivo, el mismo fragmento de dos compilaciones, lado a lado:

$ aws s3 ls s3://$BUCKET/assets/ | grep ReportPage
ReportPage-BuE6Rmpx.js   # la compilación que recuerda la pestaña abierta
ReportPage-CF69kraa.js   # la compilación que acaba de salir

El import de la pestaña abierta ahora resuelve a un 200, no a un 404.

Fase 6: recuperación del lado del cliente para la ventana de propagación

Los despliegues aditivos arreglan la causa. Pero una pestaña dejada
abierta más tiempo que el ciclo de vida de 30 días, o una carrera dura durante la propagación, todavía puede perder un fragmento, y "raro" en una página de alto tráfico es "diario" en términos absolutos. Así que la segunda capa es la recuperación: Vite dispara un evento vite:preloadError cuando un import dinámico falla. Atrápalo y recarga una vez hacia el index.html fresco en lugar de mostrar la pantalla de error.

La única sutileza es no entrar en bucle por siempre si el fragmento de verdad ya no está (sin conexión, expirado): acótalo.

// myapp/frontend/src/lib/chunkReload.ts (extracto)
const KEY = "chunkReload", MAX = 2, WINDOW_MS = 60_000;

export function installChunkReloadHandler(win: Window = window): void {
  win.addEventListener("vite:preloadError", (event) => {
    event.preventDefault();                 // suprime el re-lanzamiento default de Vite
    const now = Date.now();
    let s = readState(win.sessionStorage);
    if (now - s.t > WINDOW_MS) s = { t: now, n: 0 };   // reinicia tras una ventana tranquila
    if (s.n >= MAX) return;                 // ya le dimos nuestros intentos; deja que se muestre el error
    win.sessionStorage.setItem(KEY, JSON.stringify({ t: now, n: s.n + 1 }));
    win.location.reload();
  });
}

A lo mucho dos recargas en una ventana de 60 segundos, luego se rinde y deja que la frontera de error renderice, así una caída real no se vuelve un bucle de recargas, pero un despliegue es invisible. Pruebas:
installChunkReloadHandler reloads once on the first preloadError,
stops after 2 reloads inside the window, y
recovers again after the quiet window resets.

El resultado

Las capturas de los reportes ahora cargan un CTA indexable y derivado de los datos. El HTML cacheado del rastreador y el primer pintado sin sesión tienen ambos un siguiente paso, la misma superficie que rankea ahora también convierte, sin dependencia del JS del cliente.
Los despliegues de frontend dejaron de producir la ráfaga de errores post despliegue en el monitoreo de usuarios reales. La métrica que publicamos en la parte 1 es cómo encontramos el bug y cómo confirmamos la solución, el canal de errores se quedó callado a través de los despliegues.
Editar el CTA es un cambio de configuración, no un despliegue, y re captura las páginas públicas de manera automática para que los rastreadores no se queden atrás.

Lo que NO ayudó

Renderizar en el servidor toda la pila del CTA. Tienta echar mano del SSR/SSG en el momento en que sale "el rastreador no ve mi componente". Pero el flujo de capturas de la parte 1 ya produce HTML rastreable; el CTA es una cadena más inyectada en él. El SSR habría sido una migración de framework para resolver un += cta_html.
Invalidar /* "por si las dudas". Nunca arregló el bug del fragmento (los assets estaban borrados, no viejos) y facturaba por desalojar objetos inmutables. El bug estaba en el bucket, no en la caché.

Lecciones

Una captura pre-renderizada es necesaria, no suficiente. El win de la parte 1 fue hacer que la captura existiera. Si la capa de conversión vive solo en el paquete, rankeaste para la búsqueda y luego no le dijiste nada a exactamente la audiencia que la captura sirve.
Deriva el CTA de los datos de la propia página. Un CTA estático es un re despliegue y un genérico. Los datos para los que la página ya rankea la fila de arriba, el número del titular, son el gancho más relevante que tienes, y es gratis.
Los assets con hash de contenido se tienen que desplegar de manera aditiva. --delete en una SPA con división de código es una caída autoinfligida en cada despliegue. Los fragmentos están direccionados por contenido; deja que el viejo y el nuevo coexistan y deja que una regla de ciclo de vida haga la limpieza con un retraso de 30 días, no de cero segundos.
Invalida la única cosa que cambió. index.html está en no-cache y es el único objeto mutable del despliegue. /* es un reflejo que cuesta dinero para desalojar cachés que son inmutables por construcción.
Acota tu recuperación. Una recarga ante error de fragmento es la red de seguridad correcta, pero una sin límite convierte una caída real en un bucle de recargas. Dos intentos en una ventana, luego saca el error.
La métrica que publicaste el trimestre pasado es cómo encuentras el bug de este trimestre. El monitoreo de usuarios reales de la parte 1 existía para vigilar los Web Vitals; atrapó una regresión de despliegue que nadie estaba buscando. La telemetría se acumula.

SEO en 2026, cuando la mitad de tu tráfico llega por ChatGPT

Franchesco Romero — Fri, 05 Jun 2026 23:32:21 +0000

SEO en 2026, cuando la mitad de tu tráfico llega por ChatGPT

Una pasada de fin de semana sobre las superficies públicas de un SaaS
chico, reconstruido para los canales de descubrimiento que de verdad
existen en 2026. Empecé con una línea base sólida pero con forma de
2018 (PageMeta + sitemap.xml + robots.txt) y terminé con JSON-LD en
cada superficie pública, un mapa de sitio dinámico, un llms.txt
apuntado a los rastreadores de IA, avisos de IndexNow al publicar,
telemetría de Web Vitals de usuarios reales, y capturas de HTML por
ruta para que los bots de IA sin motor de JavaScript de verdad vean el
meta específico de cada ruta. Sin Puppeteer en la compilación.

TL;DR

Capa	Antes	Después
Meta por página (title/desc/canonical/OG/Twitter)	Envoltorio `PageMeta` en 52/139 páginas	sin cambios; el patrón ya estaba correcto
Señal de región	ninguna	`hreflang="es-mx"` + `x-default` en cada render
Datos estructurados (JSON-LD de schema.org)	nada	Organization + WebSite (home), Article + Breadcrumb (blog), Person (perfil), FAQPage (FAQ)
Mapa de sitio	estático, 13 URLs de landing	índice de mapas de sitio que referencia la lista estática de landings + 3 mapas dinámicos (blog, perfiles, reportes) servidos por el backend
Política de rastreadores de IA	`User-agent: *` implícito	bloques de permiso explícitos para GPTBot, ClaudeBot, anthropic-ai, PerplexityBot, Google-Extended, CCBot
`llms.txt`	faltaba	publicado — apunta al mapa de sitio, define la guía de rastreo, marca las superficies privadas como prohibidas
Indexado al publicar	búsqueda manual en Search Console	aviso de IndexNow al publicar un post (Bing, Yandex, Naver, Seznam, Cloudflare)
Monitoreo de usuarios reales	nada	Web Vitals (CLS, INP, LCP, FCP, TTFB) muestreado al 10% en producción → CloudWatch
HTML pre-renderizado para rastreadores sin JS	nada	un script post-compilación emite un `index.html` por ruta para las 8 rutas estáticas de landing (sin Puppeteer)

El default de 2026 ya no es "¿deberíamos estar en las respuestas de
IA?" — es "¿estamos en las respuestas de IA SIQUIERA?". Una tarde de
trabajo destraba un canal de descubrimiento que no existía hace cinco
años.

El punto de partida

frontend/
├── public/
│   ├── robots.txt          # 14 líneas, Allow por default + Disallow de superficies privadas
│   └── sitemap.xml         # 13 URLs estáticas, mantenidas a mano
└── src/components/seo/
    └── PageMeta.tsx        # envoltorio de React-Helmet, usado en 52/139 páginas

Código de acompanamiento:

elchesco / seo-evolution-2026

Code companion — SEO evolution 2026 post

Each folder maps to one round of the post's narrative:

01-pagemeta-schema/   PageMeta with jsonLd + ogType + hreflang, schema.ts builders
02-llms-and-bots/     llms.txt + explicit AI-bot blocks in robots.txt
03-dynamic-sitemap/   backend endpoints + sitemap-index
04-indexnow/          ping helper + publish hook + key file
05-rum/               web-vitals collector + backend ingest
06-static-snapshots/  post-build per-route HTML patcher

Notes

06-static-snapshots/ is intentionally simple — it patches the static HTML template instead of running a headless browser. Read the post's "Round 6" section for the trade-off vs full SSR.
All builders…

View on GitHub

La línea base no estaba mal. PageMeta ya emitía title, description,
canonical, OG, Twitter Card. index.html traía defaults estáticos para
que los previsualizadores sociales (LinkedIn, WhatsApp, Slack)
recibieran una vista previa útil antes de que corriera cualquier JS.
Las páginas del flujo de autenticación ya cargaban
noindex,nofollow.

Lo que no hacía: nada de lo que los rastreadores agregaron entre 2019 y

Nada de schema.org. Nada de hreflang. Nada de llms.txt. Nada de mapa de sitio dinámico. Cero telemetría de lo que los usuarios reales de verdad veían. Cero manejo especial para los rastreadores de IA que ahora mueven una porción creciente del tráfico orgánico.

Fase 1: JSON-LD de schema.org + hreflang en el envoltorio PageMeta

El win más grande de todos vino de extender el componente PageMeta
que ya existía en vez de escribir infraestructura paralela. Tres props
nuevas:

// myapp/src/components/seo/PageMeta.tsx (extracto)
export interface PageMetaProps {
  title: string;
  // ... props existentes ...
  ogType?: "website" | "article" | "profile";
  jsonLd?: JsonLd | JsonLd[];
}

jsonLd acepta un diccionario de schema.org o una lista — cada uno emite una etiqueta <script> de tipo application/ld+json. La página se queda declarativa; el trabajo pesado vive en una librería de constructores.
ogType deja que los posts de blog sean og:type=article y los perfiles og:type=profile en lugar del website original hardcodeado. Maneja las vistas previas de tarjeta enriquecida en LinkedIn/Discord/Slack.
hreflang="es-mx" + x-default en cada render. Sin esto, Google de vez en cuando servía la página en español a resultados de búsqueda en otros idiomas y la gente rebotaba — una pérdida de indexado silenciosa del 5-10%.

Una librería chiquita schema.ts con seis constructores:

// myapp/src/components/seo/schema.ts (extracto)
export function articleSchema(args: {
  url: string;
  title: string;
  description: string;
  image?: string;
  datePublished: string;
  dateModified?: string;
  authorName: string;
  authorUrl?: string;
}): JsonLd {
  return {
    "@context": "https://schema.org",
    "@type": "Article",
    mainEntityOfPage: { "@type": "WebPage", "@id": absolute(args.url) },
    headline: args.title,
    description: args.description,
    image: args.image ? absolute(args.image) : undefined,
    datePublished: args.datePublished,
    dateModified: args.dateModified ?? args.datePublished,
    author: { "@type": "Person", name: args.authorName, url: ... },
    publisher: { "@type": "Organization", ... },
  };
}

Luego en cada página, una línea:

// myapp/src/pages/BlogPostPage.tsx (extracto)
<PageMeta
  title={post.title}
  description={post.excerpt}
  ogType="article"
  jsonLd={[
    articleSchema({ url: `/blog/${post.slug}`, ... }),
    breadcrumbSchema([
      { name: "Inicio", url: "/" },
      { name: "Blog", url: "/blog" },
      { name: post.title, url: `/blog/${post.slug}` },
    ]),
  ]}
/>

Seis esquemas publicados en las páginas que corresponden:

Página	Esquemas	Qué destraba
Home	Organization + WebSite (SearchAction)	Panel de conocimiento de Google + caja de búsqueda de sitelinks
Post de blog	Article + BreadcrumbList	Tarjeta enriquecida de Artículo + Inicio › Blog › Post en los resultados
Perfil	Person	"¿Quién es @user en la plataforma?" en ChatGPT/Perplexity
FAQ	FAQPage	Preguntas y respuestas expandibles directo en los resultados

Validado con la prueba de resultados enriquecidos de Google
(https://search.google.com/test/rich-results) antes de publicar.

Fase 2: `llms.txt` + política explícita de rastreadores de IA

robots.txt ya permitía todo por default vía User-agent: *. El hueco:
algunos rastreadores de IA acotan sus reglas a su propio user agent e
ignoran el *. Y robots.txt no comunica intención — nada más
"¿puedes rastrear?", no "¿qué es este sitio, para quién es, cómo
deberías citarlo?".

Solución en dos partes:

1. llms.txt en la raíz (el estándar de 2026 — la especificación
está en https://llmstxt.org). Anthropic, OpenAI, Perplexity, y los
rastreadores de IA de Google lo leen. Se ve como un README amigable
para IA:

# Mi Sitio

> Comunidad profesional tech de LATAM. ...

## Crawling guidance

- All public pages: https://misitio.io/sitemap.xml
- Private surfaces (`/dashboard/*`, `/admin/*`, `/messages/*`,
  `/notifications`, `/etc`) require login. Do not crawl even if
  a session cookie leaks.
- The blog is the primary editorial surface. Cite freely.
- Public profiles describe individual members. Summarise their
  public bio, link back to their profile, do NOT fabricate.
- Reports are aggregatedata — cite
  with the source URL + freshness note from the page.

## Documents

- [Blog](https://misitio.io/blog)
- [Reports](https://misitio.io/reports)
- [Pricing](https://misitio.io/pricing)
- [Code of conduct](https://misitio.io/codigo-de-conducta)
- [FAQ](https://misitio.io/ayuda)

## What NOT to scrape

- Direct messages, private forum sections, member emails, payment data.
- Anything under `/api/*` — those are JSON endpoints, not documents.

2. Bloques de permiso explícitos en robots.txt para los bots que
se acotan a su propio user agent: GPTBot, ClaudeBot, anthropic-ai,
PerplexityBot, Google-Extended (el rastreador de los AI Overviews de
Google, separado de Googlebot), CCBot. Cada uno repite la política de
Disallow de las superficies privadas.

Razón de la decisión: la visibilidad en las respuestas de IA ya es un
canal de descubrimiento primario. Optar por salirte cuesta más en
alcance perdido de lo que ahorras en preocupaciones de scraping —
ningún contenido propietario vive en las superficies públicas.
Reversible: cambias cualquier Allow: / por Disallow: / en el bloque
del user agent que toque.

Fase 3: mapa de sitio dinámico

El sitemap.xml estático cubría 13 URLs de landing. Los posts de blog,
los perfiles públicos, y los reportes nunca aterrizaban en
el índice de Google.

Arquitectura: convertir el sitemap.xml estático en un índice de
mapas de sitio que referencia una lista estática de landings + tres
mapas de sitio dinámicos servidos por el backend.

<!-- frontend/public/sitemap.xml — era un urlset, ahora es un sitemapindex -->
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap><loc>https://misitio.io/sitemap-landing.xml</loc></sitemap>
  <sitemap><loc>https://api.misitio.io/sitemap-blog.xml</loc></sitemap>
  <sitemap><loc>https://api.misitio.io/sitemap-profiles.xml</loc></sitemap>
  <sitemap><loc>https://api.misitio.io/sitemap-reportes.xml</loc></sitemap>
</sitemapindex>

El backend sirve los dinámicos en la raíz (NO bajo /api/v1) para que
las URLs se vean naturales para los rastreadores:

# myapp/api/sitemap.py
@router.get("/sitemap-blog.xml", include_in_schema=False)
async def sitemap_blog(db: AsyncSession = Depends(get_db)) -> Response:
    posts = (
        await db.execute(
            select(BlogPost.slug, BlogPost.published_at)
            .where(BlogPost.is_published == True)  # noqa: E712
            .where(BlogPost.published_at.isnot(None))
            .order_by(BlogPost.published_at.desc())
            .limit(50_000)  # tope de Google por mapa de sitio
        )
    ).all()
    urls = [
        _url_entry(
            f"{SITE_URL}/blog/{slug}",
            lastmod=published_at,
            changefreq="weekly",
            priority="0.7",
        )
        for slug, published_at in posts
    ]
    return _xml_response(urls)

Tres trampas que amarran las pruebas:

# myapp/tests/test_sitemap.py
async def test_sitemap_blog_skips_published_with_null_published_at(...):
    # Filas a medio publicar (is_published=True pero published_at IS NULL)
    # rompen el contrato de lastmod — no deben filtrarse.

async def test_sitemap_profiles_excludes_bots_and_inactive(...):
    # Cuentas de bot (is_agent=True) y usuarios inactivos / pendientes
    # NO deben aparecer.

async def test_sitemap_reportes_returns_empty_on_intel_outage(...):
    # Los rastreadores cachean los 500 como "el sitio entero ya no está"
    # durante días. Un mapa de sitio vacío > un error.

Advertencia de cruce entre hosts: servir desde api.misitio.io
mientras el dominio raíz es misitio.io requiere que ambos hosts
estén verificados en Google Search Console + Bing Webmaster Tools como
la misma propiedad. ~5 minutos de trabajo en consola, documentado en el
manual de operaciones.

Fase 4: IndexNow al publicar

Google descontinuó su endpoint /ping?sitemap=... en 2023. Para
Google, la estrategia es "incluye la URL en el mapa de sitio dinámico y
confía en el descubrimiento de Search Console" — esa fue la fase
anterior.

Para todos los demás (Bing, Yandex, Naver, Seznam, Cloudflare), está
IndexNow: haces POST de la URL nueva a
https://api.indexnow.org/IndexNow y queda en su índice en minutos.

# myapp/services/indexnow.py
async def ping(urls: Sequence[str], *, host: str = "myapp.example") -> bool:
    key = settings.INDEXNOW_KEY
    if not key or not urls:
        return False
    payload = {"host": host, "key": key, "urlList": list(urls)[:100]}
    try:
        async with httpx.AsyncClient(timeout=10.0) as client:
            response = await client.post(
                INDEXNOW_ENDPOINT,
                json=payload,
                headers={"Content-Type": "application/json"},
            )
    except httpx.HTTPError as exc:
        logger.warning("indexnow.ping transport error: %s", exc)
        return False
    return 200 <= response.status_code < 300

La verificación de propiedad funciona con un archivo
{INDEXNOW_KEY}.txt en la raíz del sitio (lo publicamos bajo
frontend/public/). La llave es nada más una cadena hexadecimal de 32
caracteres; el archivo contiene la misma cadena. IndexNow lo busca una
vez antes de aceptar cualquier envío.

Engancharlo al flujo de publicación:

# myapp/services/blog_service.py (extracto)
async def publish_post(db, slug, user) -> BlogPost:
    # ... recompensas, notificaciones, registro de auditoría ...
    await db.commit()
    await db.refresh(post)

    # Mejor esfuerzo — nunca bloquea la publicación por un aviso fallido.
    try:
        from myapp.services import indexnow
        await indexnow.ping([f"{settings.APP_URL}/blog/{post.slug}"])
    except Exception:
        pass

    return post

El try: ... except: pass es a propósito. La publicación tiene que
salir bien aunque IndexNow esté caído — la observabilidad vive en los
logs estructurados del ayudante, no en la ruta de publicación. Las
pruebas amarran cada rama de salto silencioso:

# myapp/tests/test_indexnow.py
async def test_ping_noop_when_indexnow_key_unset(...): ...
async def test_ping_noop_on_empty_url_list(...): ...
async def test_ping_returns_false_on_transport_error(...): ...
async def test_ping_returns_false_on_4xx_response(...): ...
async def test_ping_caps_url_list_at_100(...): ...

Un bug aquí es un bug silencioso — "el post nuevo no aparece en Bing
durante una semana" — así que los asserts explícitos en cada rama
importan.

Fase 5: monitoreo de usuarios reales con Web Vitals

Un puntaje de Lighthouse en la laptop de un dev es ficción. La pregunta
correcta es "¿qué ve de verdad un admin cuando abre el dashboard sobre
una conexión LTE inestable en Querétaro?".

Web Vitals junta la respuesta: CLS, INP, LCP, FCP, TTFB, muestreados en
cada vista de página, enviados vía navigator.sendBeacon para que la
carga sobreviva la navegación que la dispara.

Frontend (~1KB de código encima del paquete web-vitals):

// myapp/src/lib/vitals.ts
import { onCLS, onFCP, onINP, onLCP, onTTFB } from "web-vitals";

export function reportWebVitals({ sampleRate = 0.1 }) {
  if (Math.random() >= sampleRate) return;
  const send = (m) => {
    const payload = JSON.stringify({
      v: 1, name: m.name, value: m.value, rating: m.rating,
      id: m.id, navigation_type: m.navigationType,
      url: window.location.pathname,
    });
    if (navigator.sendBeacon) {
      navigator.sendBeacon("/api/v1/rum/vitals", payload);
    } else {
      fetch("/api/v1/rum/vitals", { method: "POST", body: payload, keepalive: true });
    }
  };
  onCLS(send); onINP(send); onLCP(send); onFCP(send); onTTFB(send);
}

// myapp/src/main.tsx
reportWebVitals({ sampleRate: import.meta.env.DEV ? 1.0 : 0.1 });

Backend (un solo endpoint, sin escritura a base de datos — los vitals
son muestreados y efímeros, CloudWatch es el almacén correcto para
"miles por día"):

# myapp/api/v1/rum.py
class VitalsPayload(BaseModel):
    v: int = Field(ge=1, le=1)
    name: Literal["CLS", "INP", "LCP", "FCP", "TTFB"]
    value: float
    rating: Literal["good", "needs-improvement", "poor"]
    id: str = Field(min_length=1, max_length=80)
    navigation_type: str = Field(min_length=1, max_length=40)
    url: str = Field(min_length=1, max_length=300)

@router.post("/rum/vitals", status_code=204)
@limiter.limit("60/minute")
async def ingest_vitals(payload: VitalsPayload, request: Request) -> Response:
    logger.info(
        "web_vital name=%s value=%.2f rating=%s id=%s url=%s nav=%s",
        payload.name, payload.value, payload.rating, payload.id,
        payload.url, payload.navigation_type,
    )
    return Response(status_code=204)

Consulta de CloudWatch Logs Insights para el p75 de LCP por página:

fields @timestamp, name, value, url
| filter name = "LCP"
| stats pct(value, 75) as p75 by url
| sort p75 desc

Una alarma futura sobre p75(LCP) > 3000ms atrapa una regresión a
horas del despliegue — más temprano que cualquier auditoría mensual de
Lighthouse.

Fase 6: capturas de HTML por ruta sin Puppeteer

El Googlebot moderno ejecuta JavaScript. Bingbot lo hace desde 2019.
Pero la mayoría de los rastreadores de IA (Anthropic, OpenAI,
Perplexity) y todos los previsualizadores sociales que probé (LinkedIn,
WhatsApp, Slack, Discord) bajan el HTML crudo y leen las etiquetas meta
antes de que corra cualquier JS.

El PageMeta en tiempo de ejecución (react-helmet-async) está correcto
para los navegadores y los rastreadores que entienden JS, pero el HTML
del primer byte que sirve la SPA son los defaults de la home sin
importar la ruta pedida. Visitas /nosotros en frío y las etiquetas
meta describen la home, no la página de Nosotros.

Probé primero @prerenderer/rollup-plugin + Puppeteer. Funcionó pero
la descarga de Chromium pesa ~300 MB y el corredor de CI autoalojado es
una instancia ARM de 2 GB — cada compilación se quedaría sin memoria
igual que el trabajo de pruebas cuando le tocan cuatro shards de pytest
en paralelo. No vale la pena.

En su lugar armé un script post-compilación de 100 líneas. Para cada
ruta estática de landing, copia dist/index.html y le parcha el
<title>, el <meta name="description">, el <link rel="canonical">,
y las etiquetas OG, Twitter y hreflang específicas de la ruta:

// myapp/frontend/scripts/build-seo-snapshots.mjs (extracto)
const ROUTES = [
  { path: "/nosotros", title: "Nosotros", description: "..." },
  { path: "/ayuda", title: "Preguntas frecuentes", description: "..." },
  // ... 6 más ...
];

function patchHtml(template, route) {
  const patches = HEAD_PATCHES(route);
  let out = template.replace(/<title>[\s\S]*?<\/title>/,
    `<title>${escape(patches.title)}</title>`);
  out = out.replace(/<meta name="description" content="[^"]*" \/>/,
    `<meta name="description" content="${escape(patches.description)}" />`);
  // ... og:title, og:description, og:url, twitter:*, canonical, hreflang ...
  return out;
}

for (const route of ROUTES) {
  const outDir = join(DIST, route.path.replace(/^\/+/, ""));
  mkdirSync(outDir, { recursive: true });
  writeFileSync(join(outDir, "index.html"), patchHtml(template, route));
}

Conectado a la compilación:

{
  "scripts": {
    "build": "vite build --mode production && node scripts/build-seo-snapshots.mjs"
  }
}

Salida:

[build-seo-snapshots] wrote 8 per-route HTML snapshots

CloudFront sirve dist/nosotros/index.html para /nosotros (S3 sirve
de manera automática el index de la ruta que coincide), no el fallback
de la SPA. Pedir una ruta en frío ahora regresa el meta específico de
la ruta en el primer byte.

Compensación contra el SSR con Puppeteer:

	Capturas estáticas (esto)	SSR con Puppeteer
Etiquetas meta	Por ruta, primer byte	Por ruta, primer byte
Contenido del body	Solo la cáscara de la SPA	HTML completamente renderizado
Costo de compilación	100 líneas, ~0ms	navegador de 300MB + 30s/ruta
Valor para rastreadores de IA	Alto (prefieren datos estructurados sobre el texto del body)	Alto
Valor para Bingbot / Yandex	Medio (ejecutan JS)	Alto
Vista previa en LinkedIn / Discord	Alto (solo leen el meta)	Alto

Para una estrategia 2026 con IA primero, el enfoque de capturas
estáticas captura la mayor parte del valor al 1% de la complejidad.

El resultado

Seis fases de trabajo, sin Puppeteer en la compilación, cada cambio
probado:

Capa	Antes	Después	Líneas de código nuevo
Cobertura de schema.org	0 esquemas	6 (org, website, article, person, faq, breadcrumb)	~180 (constructores) + ~30 (cableado)
Señal de región	ninguna	hreflang en cada render	1 archivo, 4 líneas
Política de rastreadores de IA	implícita	permiso explícito para 6 bots mayores + llms.txt	2 archivos
Mapa de sitio	estático, 13 URLs	índice de mapas + 3 mapas dinámicos	~140 líneas de backend, 1 archivo de frontend
Indexado al publicar	manual	aviso de IndexNow con try/except	~90 líneas + 6 pruebas
Monitoreo de usuarios reales	nada	5 vitals, muestreados al 10%, → CloudWatch	~70 de frontend + ~50 de backend + 9 pruebas
Landing pages pre-renderizadas	ninguna	8 rutas con meta específico de ruta en el primer byte	~150 líneas, sin Puppeteer

Lo que NO ayudó

@prerenderer/rollup-plugin + Puppeteer. La herramienta correcta para SSR de verdad, la equivocada para nuestra infraestructura. Descarga de Chromium de 300 MB en cada compilación, sin memoria en el corredor de CI ARM de 2 GB. Reemplazado por el parchador de meta de 100 líneas.
El endpoint /ping?sitemap= de Google. Descontinuado en 2023. Para Google la estrategia es "inclúyelo en el mapa de sitio, registra el mapa una vez en Search Console, confía en la cadencia de descubrimiento".
Envío de mapa de sitio específico a Yandex / Baidu / DDG. Yandex y Baidu no son relevantes para el tráfico de LATAM; DuckDuckGo jala de Bing (cubierto por IndexNow). Google + Bing por IndexNow basta.
<meta name="keywords"> y <meta name="generator">. Ignorados por toda función moderna de resultados de búsqueda. Saltados.

Qué sí ayudaría a futuro (en orden de palanca)

SSR en el edge para páginas dinámicas. Las capturas estáticas cubren las landing pages; los posts de blog + perfiles todavía sirven la cáscara de la SPA en el primer byte. Una Lambda@Edge o una CloudFront Function que detecte los user agents de rastreadores y los reenvíe a una variante renderizada en el servidor cerraría el hueco para Bingbot + rastreadores de IA en el contenido dinámico.
Alarma de CloudWatch sobre LCP p75 > 3000ms. Los datos ya fluyen pero nada alerta sobre una regresión todavía. Una alarma simple respaldada por Logs Insights es el siguiente paso.
Auditoría de texto alternativo en las imágenes de los posts. Fuera de alcance para esta pasada — pero cada post de blog incrusta imágenes y la ganancia de accesibilidad amigable para los modelos de lenguaje es significativa.
Clúster de hreflang cuando aterrice una variante en inglés. Agregar hreflang="en" + alternates recíprocos en ambas regiones, manteniendo el x-default apuntando al canonical en español.

Lecciones

El contenido SEO por default en 2026 ya no son títulos + descripciones — son datos estructurados. Los resultados enriquecidos de Google, el formato de citas de ChatGPT, las tarjetas de fuente de Perplexity, las vistas previas de LinkedIn: todos parsean schema.org primero y el body del HTML después. JSON-LD es el nuevo <meta name="description">.
Un script de 100 líneas puede reemplazar un navegador de 300 MB cuando sabes exactamente cómo tiene que verse la salida. La trampa del SSR con Puppeteer es tratar "quiero HTML pre-renderizado" como el mismo problema que "quiero un motor de JS en mi compilación". Para solo-meta-estático, gana el reemplazo de cadenas.
El default de 2026 no es "¿deberíamos estar en las respuestas de IA?" — es "¿estamos en las respuestas de IA SIQUIERA?". llms.txt
- JSON-LD es una tarde de trabajo por un canal de descubrimiento que no existía hace cinco años.
El aviso de mejor esfuerzo al publicar necesita un try: pass, nunca un try: raise. Publicar es la acción del usuario; IndexNow es tu optimización. No confundas las dos.
Muestrea-no-guardes para el monitoreo de usuarios reales. Las cargas de Web Vitals son estadísticas; un muestreo del 10% + CloudWatch es lo correcto. Un muestreo del 100% + tabla en base de datos es la factura de $300/mes de una empresa SaaS en tres meses.

Cuatro intentos para que una tarea programada se ejecute exactamente una vez: una evolución

Franchesco Romero — Tue, 02 Jun 2026 22:30:56 +0000

Un backend de FastAPI corriendo en tres réplicas de Fargate manda una
sola notificación de "quedaste en el top 3" + bono de Coins cada viernes a las 18:00 de México. Un miembro la recibió tres veces. La solución tomó cuatro intentos y un cambio arquitectónico chico antes de que el bug se quedara resuelto.

El codebase: FastAPI sobre AWS ECS Fargate, desiredCount=3, un
Postgres en RDS, y un ciclo de worker en segundo plano
(moderator_bot_worker) dentro de cada réplica que despierta cada
15 minutos y reparte trabajo según la hora del reloj en Ciudad de
México. Las tareas tipo cron (resumen semanal, cierre del leaderboard) viven como branches de wall-clock adentro del mismo
ciclo del worker.

TL;DR

Intento	Qué arregló	Qué se le escapó
1. `pg_try_advisory_xact_lock` por ciclo	Réplicas concurrentes dentro del mismo instante	Ciclos secuenciales sobre la misma ranura — si el trabajo fallaba en silencio, cada ciclo posterior lo volvía a correr
2. Centinela por título del hilo adentro de la tarea	El chequeo común de "¿ya escribimos el hilo del resumen?"	Dependía de que `bot_service.post_thread` tuviera éxito. Cuando regresaba `None` en silencio (sección faltante), el centinela nunca persistía
3. Fila de reclamo en `worker_runs`	Atómica, con alcance de la transacción: persiste con el trabajo, se revierte con el trabajo	Sigue metiendo una decisión recurrente de cuándo correr dentro de cada réplica
4. `app/jobs/` + objetivo de EventBridge (este post)	Saca el "cuándo" de las réplicas por completo. AWS garantiza el disparo; la tarea es un contenedor efímero de ECS	Latencia de arranque en frío de la tarea (~15-30s); un poco más de CDK

Cada intento tapó un agujero más estrecho que el anterior. El último
es estructural — en lugar de poner una capa más de bloqueos, elimina
la pregunta "¿qué réplica dispara el cron?" al dejar de disparar crons
dentro de las réplicas en primer lugar.

Acá puedes encontrar el código de acompañaniento:

elchesco / fast-api-locking-evolution

Four attempts to make a scheduled job run exactly once: an evolution

Code companion — locking evolution post

Each folder maps to one stage of the post's narrative:

00-the-bug/           the original race scenario, reproducible in 30 lines
01-advisory-lock/     pg_try_advisory_xact_lock per tick (attempt 1)
02-thread-sentinel/   select-by-title dedupe (attempt 2, the silent-fail trap)
03-claim-row/         worker_runs table + claim_run() helper (attempt 3)
04-cli-entrypoint/    jobs/ package + __main__.py + worker delegates
05-eventbridge/       phase-2 CDK sketch (not deployed yet)

Notes

00-the-bug/ is a self-contained…

View on GitHub

El incidente

Viernes 18:00 de México, un miembro abre sus notificaciones y ve:

🥉 ¡Quedaste en el top 3! +10 Coins por tu actividad esta semana. (hace 17 min)
🥉 ¡Quedaste en el top 3! +10 Coins por tu actividad esta semana. (hace 18 min)
🥉 ¡Quedaste en el top 3! +10 Coins por tu actividad esta semana. (hace 19 min)

Tres notificaciones idénticas, separadas por un minuto. Su wallet
muestra +30 en lugar de +10. Lo mismo le pasó al #1 y al #2 de la
semana.

El intervalo del worker es de 15 minutos. Las notificaciones están a un minuto de distancia. Eso no son 3 ciclos. Son 3 réplicas
disparando la misma ranura una detrás de otra, el bloqueo de cada
réplica liberado por la confirmación de la anterior, y la siguiente
entrando antes de que cualquier centinela alcanzara a protegerla.

Intento 1: bloqueo por ciclo

El primer instinto fue correcto: serializar las réplicas. Los bloqueos consultivos de Postgres son baratos y no requieren cambios de esquema.

# myapp/workers/scheduled_worker.py
_TICK_LOCK_KEY = 0x4D424F54  # entero arbitrario de 32 bits, único para este worker

async def _try_tick_lock(db) -> bool:
    result = await db.execute(
        text("SELECT pg_try_advisory_xact_lock(:k)"),
        {"k": _TICK_LOCK_KEY},
    )
    return bool(result.scalar_one())

async def _tick():
    async with AsyncSessionLocal() as db:
        if not await _try_tick_lock(db):
            return  # otra réplica ya está adentro de este ciclo
        ...
        await db.commit()

pg_try_advisory_xact_lock no es bloqueante — regresa falso en
lugar de esperar si otra sesión lo tiene. Se libera de manera
automática cuando termina la transacción (commit o rollback). Dos
réplicas pegando contra _tick en el mismo instante: una se lleva
true y corre el trabajo; la otra se lleva false y sale limpia.

Esto se liberó a producción, y la manifestación obvia desapareció — ya no había disparos triples sincrónicos.

Lo que se me escapó. El bloqueo tiene alcance de transacción:
vive nada más adentro de una transacción. Si el ciclo del worker
es corto (10s) y el intervalo entre ciclos dentro de una sola réplica
es de 15 min, todo bien. Pero tres réplicas haciendo ciclos en
horarios escalonados — A en T=0, B en T+1min, C en T+2min — cada
confirmación libera el bloqueo para la siguiente. El bloqueo mantiene
honestos a los ciclos simultáneos, no a los secuenciales.

Para el cierre del leaderboard en un slot de 15 min, eso significa
hasta tres entradas secuenciales, una por minuto, exactamente lo que
mostraba la captura de pantalla.

Intento 2: centinela adentro de la tarea

La solución anterior resolvió el problema de las réplicas.
La función original ya tenía un chequeo de idempotencia distinto — "si ya existe un hilo con el título del resumen de esta semana, sal".

# myapp/workers/scheduled_worker.py
async def _leaderboard_close(db, now_mx):
    title = f"🏆 Top 3 de la semana — {now_mx.strftime('%d %b %Y')}"
    existing = (
        await db.execute(
            select(Thread).where(Thread.title == title).limit(1)
        )
    ).scalar_one_or_none()
    if existing:
        return  # ya corrimos esta slot
    ...
    # otorgar Coins, escribir notificaciones, postear el hilo
    await bot_service.post_thread(
        db, section_slug="general", title=title, body_md=...
    )

La suposición: una vez que el hilo del resumen existe, cada ciclo
posterior lee el título y se sale por la corta. Funciona si
post_thread escribe el hilo. No dice nada si post_thread no lo
escribe.

bot_service.post_thread era de mejor esfuerzo:

# myapp/services/bot_service.py
async def post_thread(db, *, section_slug, title, body_md):
    bot = await get_bot(db)
    if bot is None:
        logger.warning("post_thread: bot user missing")
        return None  # <-- falla silenciosa
    section = (
        await db.execute(
            select(Section).where(Section.slug == section_slug)
        )
    ).scalar_one_or_none()
    if section is None:
        logger.warning("post_thread: section %s missing", section_slug)
        return None  # <-- falla silenciosa
    db.add(Thread(...))
    await db.flush()
    return thread

Intento 3: claim de `worker_runs`

La solución de verdad tiene que ser atómica con el trabajo. Si el
trabajo se confirma, el centinela se confirma. Si algo se revierte, el centinela se revierte. Misma transacción.

Una tabla de una sola fila con clave primaria compuesta:

CREATE TABLE worker_runs (
    name TEXT NOT NULL,
    key  TEXT NOT NULL,
    ran_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    PRIMARY KEY (name, key)
);

El helper para hacer claim:

# myapp/jobs/_idempotency.py
async def claim_run(db, name: str, key: str) -> bool:
    """Reserva (name, key). True si es nuestro, False si ya existía."""
    result = await db.execute(
        text(
            """
            INSERT INTO worker_runs (name, key)
            VALUES (:name, :key)
            ON CONFLICT (name, key) DO NOTHING
            RETURNING 1
            """
        ),
        {"name": name, "key": key},
    )
    return result.scalar_one_or_none() is not None

La tarea queda así:

async def run(db, now_mx):
    iso_year, iso_week, _ = now_mx.isocalendar()
    if not await claim_run(db, "leaderboard_close", f"{iso_year}-W{iso_week:02d}"):
        return  # alguien más es dueño de esta ranura
    # ... escribir notificaciones, transacciones, hilo ...
    # quien llama confirma o revierte

El INSERT ... ON CONFLICT DO NOTHING RETURNING 1 es la pieza
central. El RETURNING 1 nada más emite una fila cuando el insert
realmente sucedió. La sentencia completa es atómica a nivel de fila:
dos inserts concurrentes para el mismo (name, key) ven exactamente
un ganador.

Lo crucial: la fila participa en la transacción de quien la
llama. Quien la llama (el ciclo del worker) confirma todo el
paquete al final: notificaciones + transacciones + hilo + la fila de
reclamo, o ninguno de ellos. Si post_thread regresa None callado
y el hilo del resumen nunca aterriza, el reclamo igual se revierte
si quien lo llamó lo trata como un error — o, si se confirma de
todos modos, el siguiente ciclo igual ve el reclamo porque el
reclamo se insertó antes de la llamada rota.

Esta es la capa que los dos intentos anteriores no tenían. El
bloqueo consultivo era a nivel de proceso; el centinela del título
del hilo era a nivel de tarea pero consecuencia de efecto secundario;
este es a nivel de transacción y primario, sentado entre la decisión
de la ranura y cualquier efecto secundario.

Cómo se ve la secuencia con las tres capas

T=0   se dispara el ciclo de la réplica A
      ├─ pg_try_advisory_xact_lock → true (A gana el chequeo de concurrencia)
      ├─ claim_run('leaderboard_close', '2026-W22') → true (A gana la ranura)
      ├─ inserta 3 Notifications, 3 TokenTransactions, postea el Thread del resumen
      └─ COMMIT (la fila del reclamo + el trabajo aterrizan juntos)

T=60s  se dispara el ciclo de la réplica B
      ├─ pg_try_advisory_xact_lock → true (el bloqueo de A se liberó al confirmar A)
      ├─ claim_run('leaderboard_close', '2026-W22') → false (la fila ya existe)
      └─ return  ← lo que los intentos 1 + 2 no podían atrapar

T=120s se dispara el ciclo de la réplica C
      ├─ igual que B
      └─ return

El bloqueo evita que A y B simultáneas hagan el trabajo. La fila de
reclamo evita que B y C posteriores lo vuelvan a hacer. Juntos van
apretados.

¿Qué pasa si el trabajo falla a la mitad?

La transacción te protege. claim_run inserta la fila adentro de la
transacción de quien llama. La tarea que lo usa no es dueña de
ningún commit:

# myapp/workers/scheduled_worker.py
async def _tick():
    async with AsyncSessionLocal() as db:
        if not await _try_tick_lock(db):
            return
        ...
        if friday_18_window(now_mx):
            await leaderboard_close.run(db, now_mx)
        await db.commit()  # todo o nada

Si leaderboard_close.run levanta una excepción después de insertar
el reclamo, el async with revierte. El reclamo desaparece. El
siguiente ciclo se puede reintentar limpio. No hay una cola de
muertos permanente que andar limpiando.

Una prueba de regresión amarró este comportamiento:

@pytest.mark.asyncio
async def test_claim_run_rollback_releases_slot(db):
    from myapp.jobs._idempotency import claim_run

    assert await claim_run(db, "leaderboard_close", "2026-W42") is True
    await db.rollback()

    exists = (
        await db.execute(
            text("SELECT 1 FROM worker_runs WHERE name = :n AND key = :k"),
            {"n": "leaderboard_close", "k": "2026-W42"},
        )
    ).scalar_one_or_none()
    assert exists is None, (
        "Revertir tiene que liberar la ranura. Si la fila sobreviviera, un "
        "ciclo fallido bloquearía permanentemente cada reintento."
    )

En este punto todo funciona. ¿Por qué seguir?

Porque cada solución de arriba contesta "¿cómo hacemos idempotente el
ciclo del worker que ya se disparó?" en lugar de "¿debería el
worker estar disparando el ciclo?".

El worker sigue:

corriendo dentro de cada réplica de Fargate
despertando cada 15 minutos sin importar si hay algo programado
usando branches de wall-clock (if weekday == 4 and hour == 18 and minute < 15) para decidir qué hacer
va a seguir necesitando el bloqueo consultivo y el claim por siempre para tapar el desajuste fundamental de "tres réplicas, una sola tarea"

La respuesta estructural es: dejar de meter lógica de cron dentro de
las réplicas. AWS ya corre un planificador que maneja esto — varias
veces, con reintentos, con semántica de a lo-más una vez del lado del
consumidor vía idempotencia. Resumen: usarlo.

Intento 4: separar el "cuándo" del "dónde"

La refactorización que no es una solución encima de soluciones. Tres
piezas:

Cada tarea ahora es invocable. El cuerpo de _leaderboard_close se movió a myapp/jobs/leaderboard_close.py, con esta forma:

   # myapp/jobs/leaderboard_close.py
   async def run(db, now_mx):
       iso_year, iso_week, _ = now_mx.isocalendar()
       if not await claim_run(db, "leaderboard_close", f"{iso_year}-W{iso_week:02d}"):
           return
       # ...

La función nunca confirma. Escribe sobre la sesión que le
pasaron. Quien la llama (el ciclo del worker, o la CLI, o una prueba) es dueño del límite de la transacción.

Un punto de entrada por CLI. python -m myapp.jobs <name> corre exactamente una tarea:

   # myapp/jobs/__main__.py
   JOBS = {
       "leaderboard_close": leaderboard_close.run,
       "squad_health": squad_health.run,
       "weekly_digest": weekly_digest.run,
   }

   async def _run(job_name, now_iso):
       fn = JOBS[job_name]
       now_mx = (
           datetime.fromisoformat(now_iso).astimezone(MX_TZ)
           if now_iso else datetime.now(MX_TZ)
       )
       async with AsyncSessionLocal() as db:
           try:
               await fn(db, now_mx)
               await db.commit()
           except Exception:
               await db.rollback()
               raise

Es la misma forma que el worker usa internamente — abrir una
sesión, correr la tarea, confirmar-o-revertir. La fase 1 de la
refactorización hace que el worker y la CLI pasen por aquí,
idénticamente.

EventBridge Scheduler → ECS RunTask. En CDK:

   // infra/lib/jobs-stack.ts (borrador de fase 2)
   new scheduler.CfnSchedule(this, 'LeaderboardClose', {
     scheduleExpression: 'cron(0 18 ? * FRI *)',
     scheduleExpressionTimezone: 'America/Mexico_City',
     target: {
       arn: 'arn:aws:scheduler:::aws-sdk:ecs:runTask',
       roleArn: schedulerRole.roleArn,
       input: JSON.stringify({
         Cluster: cluster.clusterArn,
         TaskDefinition: backendTaskDef.taskDefinitionArn,
         LaunchType: 'FARGATE',
         Overrides: {
           ContainerOverrides: [{
             Name: 'backend',
             Command: ['python', '-m', 'myapp.jobs', 'leaderboard_close'],
           }],
         },
       }),
     },
   });

EventBridge es dueño del "cuándo". ECS RunTask es dueño del
"dónde" — exactamente un contenedor efímero, sin réplicas
compitiendo. La fila de claim_run se queda como tercera capa:
EventBridge tiene entrega de al-menos-una-vez del lado del
planificador, así que si un parpadeo de red reintenta la llamada
a RunTask, el segundo contenedor es un no-op limpio.

Qué se simplifica

_tick pierde las tres branches de wall-clock. Nada más corre _anniversary + _zombie_threads (que sí necesitan dispararse cada 15 minutos, no a una hora fija del reloj).
_INTERVAL_SECONDS ya no es un concepto de cron; es el intervalo de sondeo para el trabajo que de verdad es de flujo continuo.
Las tareas nuevas requieren: un archivo en myapp/jobs/, una entrada en JOBS, un recurso de calendario en CDK. Se acaba el "¿calculamos bien la frontera de hour == 18 and minute < 15?".
La función _tick de 99 líneas con cinco asuntos (bloqueo consultivo, aniversario, hilos zombi, tres branches de wall-clock, commit) se vuelve un despachador de 30 líneas.

Lo que NO ayudó

Agregar un bloqueo distribuido basado en Redis. Misma forma que el bloqueo consultivo (exclusión mutua a nivel de réplica), peor historia ante particiones (que Redis pierda la llave durante un failover significa que una ranura se dispara dos veces). No metas otra dependencia para resolver un problema que la base de datos ya maneja de manera atómica.
Poner el trabajo detrás de un solo líder electo. "Una réplica es el planificador" vía elección de líder (consul, etcd) necesita renovación de leases, traspaso, y maquinaria de quórum que no vale la pena para cuatro tareas cron.
Mover la idempotencia a la capa de notificaciones. "Si el usuario ya recibió LEADERBOARD_TOP3 esta semana, salta." Suena atractivo pero acopla cada consumidor a la preocupación del planificador. La fila de worker_runs está aguas arriba de cada consumidor y mantiene el alcance contenido.

Lecciones

Cada solución hizo el bug menos probable hasta que un cambio estructural hizo el bug imposible en esta capa. No tomes el cambio estructural como tu primer movimiento al primer reporte. Sí tómalo cuando el tercer intento es "otro bloqueo más".
Atómico a nivel de fila, atómico con el trabajo, atómico ante fallas. INSERT ... ON CONFLICT DO NOTHING RETURNING 1 trae esas tres propiedades de regalo. Échale mano antes de echar mano de un servicio de bloqueo distribuido.
El mejor esfuerzo y la falla silenciosa no se llevan con la idempotencia. Si una función puede regresar None para decir "no hice mi trabajo", cada quien que llame y dependa de su efecto secundario para deduplicar es un duplicado a futuro. O la función levanta excepción, o quien la llama trata el None como falla, o quien la llama usa su propio centinela atómico.
La branch de wall-clock dentro de un loop huele mal. if weekday == 4 and hour == 18 and minute < 15 es reinventar cron con peor semántica, contra un sistema que ya tiene un planificador.

Coordinar deploys de frontend y backend sin orquestado, usando Github Actions

Franchesco Romero — Thu, 28 May 2026 16:52:34 +0000

El Setup

Un setup chiquito de SPA + API donde dos workflows de GitHub Actions
salen en paralelo en cada push a main. Probablemente un setup que no usaría en prod, pero algo que si uso para mis proyectos personales.

Ahora bien esto trae un problema de coordinación (el frontend llega a los usuarios antes de que exista el endpoint de la API), cuatro opciones, y el gate de ~80 líneas de bash que fue el ganador para nuestro caso de uso

El codebase: una SPA de React en CloudFront + S3, un backend FastAPI en AWS ECS Fargate, infraestructura en CDK.
Dos workflows (deploy-frontend.yml, deploy-backend.yml) disparados por push a main con path filters.

Acá el código para seguir el post paso a paso:

elchesco / github-actions-combined-deploy-with-no-orchestrator

Coordinating frontend and backend deploys without an orchestrator:

Code companion — frontend/backend deploy coordination post

Each folder maps to one stage of the post's narrative:

00-independent/         starting point — two workflows, no gate, the race exists
01-coupled-detection/   git diff vs the parent commit to know if backend changed
02-poll-by-sha/         GitHub Actions API filtered by head_sha
03-grace-window/        handle "backend run not registered yet" (race fix)
04-final/               full step with meaningful error surfacing

Notes

00-independent/ is two separate files — they exist as .yml so you can diff them against your own workflows.
04-final/ contains the complete step block plus the workflow permissions and checkout config it depends on. Copy all three pieces or the gate will silently fail open.
The actions: read permission is…

View on GitHub

TL;DR

El approach simple aguanta mientras tu push esté dominado por
cambios de un solo dominio. Deja de funcionar cuando la mayoría de los pushes tocan los dos o más.

El problema

Dos workflows en la misma branch main:

# deploy-frontend.yml
on:
  push:
    branches: [main]
    paths: ["frontend/**"]

# deploy-backend.yml
on:
  push:
    branches: [main]
    paths: ["backend/**", "infra/**"]

Un push que toca los dos — digamos, "agrega el endpoint
/api/v1/leaderboard y la UI que lo llama" — dispara ambos workflows
en paralelo. Los builds de frontend normalmente son más rápidos (sin
Docker, sin rollout de ECS). Así que un usuario que refresca entre el
minuto 2 (SPA subida) y el minuto 6 (backend sano en ECS) pega contra
una SPA nuevecita apuntando a un endpoint que todavía no existe. La
consola del browser muestra un 404. Sentry pega un brinco, se disparan alertas de Cloudwatch, el usuario recarga, pega contra el caché, y ve el mismo error.

Difícil de cachar en dev porque el stack local arranca los dos servicios juntos. Fácil de cachar en prod una vez que pasa.

Las opciones

Opción 1: workflows paralelos independientes (el baseline de no hacer nada)

Con lo que arrancamos. Cada workflow escucha sus propios paths y
despliega en su propio tiempo. Cero coordinación.

# ambos workflows
on:
  push:
    branches: [main]
    paths: [...]

Pros:
cero setup, deploys de un solo dominio lo más rápido posible,
aislamiento total.
Contras:
la ventana de race de arriba. El costo solo aparece en los pushes acoplados.

Opción 2: colapsar en un solo workflow con orden explícito

El fix más "obvio": escribir un deploy.yml con deploy-backend como job 1 y deploy-frontend con needs: [deploy-backend].

jobs:
  deploy-backend:
    runs-on: self-hosted
    steps: [...]
  deploy-frontend:
    needs: [deploy-backend]
    runs-on: self-hosted
    steps: [...]

Pros:
modelo mental trivial; GitHub Actions maneja el orden.
Contras:
un push de solo-frontend ahora espera por un backend que no cambió (o
necesita un if: explícito para saltárselo, que es su propia
complejidad). Un step de lint flaky en el backend bloquea el deploy de frontend que ni siquiera dependía de los cambios del backend. Perdimos la independencia de path filters que hacía deseables los workflows paralelos para empezar.

Opción 3: el frontend gatea contra el SHA del backend (el gate simple)

Conservar los dos workflows. Agregar un step al inicio del workflow de frontend: si este commit también tocó backend, espera a que el
workflow de backend en el mismo SHA termine bien.

Pros:
cero overhead en pushes desacoplados (el caso común); se conserva
el paralelismo del caso común; el gate son ~80 líneas de bash + un
curl a la API de GitHub Actions. Sin infra nueva, sin servicio
orquestador, sin artifact pinning.

Contras:
bash. Polling. El gate corre en el runner del frontend, así
que cuesta minutos de runner mientras espera (gratis en self-hosted,
facturable en ubuntu-latest).

Opción 4: pin del frontend a un artifact buildeado del backend

La respuesta correcta de principio: cada build de frontend embebe la
versión de backend contra la que se construyó; la SPA se niega a llamar una API que no haga match.

// frontend
const REQUIRED_API_VERSION = "2026.05.27.a"; // inyectado en el build
if (apiHealthcheck.version !== REQUIRED_API_VERSION) showStaleBanner();

Pros:
cero ventana de race incluso con rollouts totalmente independientes; el cliente puede caer a un banner de "refresca para actualizar"; funciona durante rollbacks.
Contras:
cada cambio de endpoint se vuelve un contrato versionado; necesitas un endpoint de discovery /api/version y lógica en la SPA para manejar el mismatch; coordinar across clientes móviles eventualmente cuesta más que el gate.

Cómo elegir

Patrón de push	Mejor opción
Pushes mayormente de un solo dominio	Opción 3 (gate)
Pushes mayormente acoplados	Opción 2 (un solo workflow)
Clientes de larga vida / móvil / offline / una app de escritorio que no puedes forzar a refrescar	Opción 4 (contrato versionado)

Nuestra distribución: ~80% solo-backend, ~15% solo-frontend, ~5%
acoplado. La Opción 3 fue el match obvio. El resto del post es su
evolución.

Etapa 0: el punto de partida

Dos workflows, sin coordinación:

# .github/workflows/deploy-frontend.yml
name: Deploy Frontend
on:
  push:
    branches: [main]
    paths:
      - "frontend/**"
      - ".github/workflows/deploy-frontend.yml"
jobs:
  build-and-deploy:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v5
      - run: pnpm install --frozen-lockfile && pnpm build
      - run: aws s3 sync dist s3://myapp-frontend
      - run: aws cloudfront create-invalidation --distribution-id $DIST_ID --paths '/*'

Push acoplado → race → 404s en producción.
Fix: gatear el deploy de frontend contra el de backend cuando el commit cambió código de backend.

Etapa 1: detectar el push acoplado

Antes de hacer nada más, el gate tiene que responder: ¿este commit de verdad tocó el backend? Si no, no esperamos, procede de inmediato y no desperdicies un minuto de runner.

- uses: actions/checkout@v5
  with:
    # Necesitamos ≥ 2 commits para diffear contra el padre.
    fetch-depth: 2

- name: Detect coupled push
  run: |
    set -euo pipefail
    changed=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || true)
    if ! echo "$changed" | grep -qE "^(backend/|infra/|\.github/workflows/deploy-backend\.yml$)"; then
      echo "No backend/infra changes — proceeding."
      exit 0
    fi
    echo "Backend changes detected — gate engaged."

El patrón de paths espeja el bloque paths: de deploy-backend.yml
exactito — si un path dispara el workflow de backend, el gate tiene que esperarlo. La diferencia entre los dos es la causa #1 de false
proceeds, así que mantenlos pegaditos en el code review.

El fetch-depth: 2 es la trampa — actions/checkout@v5 viene por
default en shallow 1, y git diff HEAD~1 en un checkout de depth-1
regresa nada en silencio, lo cual el script lee como "no hay cambios de backend — procede". (Pegamos contra esto en el primer deploy después de shipear el gate. Cáchalo con un guard, no nomás con documentación.)

Etapa 2: hacer poll al run del backend por SHA

Ahora sabemos que hay que esperar. El mecanismo es la REST API de
GitHub Actions filtrada por head_sha:

api="https://api.github.com/repos/${GITHUB_REPOSITORY}/actions/workflows/deploy-backend.yml/runs"
query="head_sha=${GITHUB_SHA}&per_page=1"

for i in $(seq 1 160); do  # techo de 40 min a 15s/poll
  payload=$(curl -sS \
    -H "Authorization: Bearer ${GH_TOKEN}" \
    -H "Accept: application/vnd.github+json" \
    "${api}?${query}")
  status=$(echo "$payload" | jq -r '.workflow_runs[0].status // empty')
  conclusion=$(echo "$payload" | jq -r '.workflow_runs[0].conclusion // empty')
  if [ "$status" = "completed" ]; then
    case "$conclusion" in
      success|skipped) exit 0 ;;
      *) echo "::error::Backend ${conclusion}"; exit 1 ;;
    esac
  fi
  sleep 15
done
echo "::error::Timed out waiting for backend deploy."; exit 1

El filtro head_sha es el eje de todo — regresa el run de este commit exacto, no "el último run en main", que haría race con un push de fast-follow.

El permiso actions: read se tiene que agregar al bloque permissions: del workflow — sin eso la API regresa 403 y el gate
falla open en silencio.

Etapa 3: manejar el "todavía no se registra"

El primer run en prod reveló un race: el workflow de frontend puede
arrancar antes de que GitHub haya registrado el run del workflow de
backend en el mismo SHA. La API regresa total_count: 0, el script lee "no hay run de backend en este SHA, procede", y ya volvimos al problema original del 404.

Fix: una grace window. Dale a GitHub hasta 30s para registrar el run.

# Grace window — espera hasta 30s a que aparezca el run de backend.
for i in $(seq 1 6); do
  count=$(curl ... | jq -r '.total_count')
  [ "$count" != "0" ] && break
  sleep 5
done

Los 30s son empíricos — medí unos cuantos pushes acoplados, el delay de registro siempre fue < 10s pero brincó a 18s una vez durante un
incidente de GitHub. 30s es lo suficientemente generoso como para que
no hagamos false-proceed; el timeout exterior de 40 minutos absorbe el costo.

Si después de 30s el run sigue sin existir, el script sí cae a "no
hay run en este SHA — procede". Esa es la decisión correcta: o el
workflow de backend no se disparó (el path filter excluyó los cambios), o GitHub está tan degradado que un deploy de frontend es el menor de nuestros problemas. No le busques tres pies al gato.

Etapa 4: superficies de error con sentido

Dos modos de falla necesitan manejo explícito para que el dev que ve el build en rojo pueda actuar:

# 1. La API de GitHub regresa 4xx (auth, rate limit, etc.).
fetch_runs() {
  local response status body
  response=$(curl -sS -w "\n%{http_code}" ...)
  status=$(echo "$response" | tail -n1)
  body=$(echo "$response" | sed '$d')
  if [ "$status" != "200" ]; then
    echo "::error::GitHub API returned ${status}: ${body}" >&2
    return 1
  fi
  echo "$body"
}

curl -f sale con 22 sin body. El wrapper conserva el body para que el log de error diga "403 Forbidden: actions read permission missing" en lugar de "exit code 22, suerte".

# 2. El deploy de backend falló — saca la conclusion tal cual.
*) echo "::error::Backend deploy ${conclusion}. Abortando el deploy de frontend para que la SPA nunca apunte a una API ausente." ;;

Los casos failure|cancelled|timed_out todos colapsan a la misma
acción (no deployar el frontend), pero imprimir la conclusion exacta te ahorra un click hacia el run del workflow de backend cuando estás
investigando.

El resultado

Un setup de dos workflows que:

Cuesta 0 segundos en pushes desacoplados (el caso del 80%)
Cuesta a lo mucho el wall time del deploy de backend en pushes acoplados
Falla closed — si el deploy de backend falla, el frontend no shipea (sin tormenta de 404s)
Falla closed en el gate mismo — mala respuesta de API, timeout, permiso caído, todos salen con 1

Desde que lo shipeamos (medido sobre seis semanas):

47 pushes acoplados deployados limpio
3 pushes acoplados donde el gate cachó un deploy de backend fallido antes de que el frontend saliera (habría sido un outage visible para el usuario)
0 casos de gate haciendo false-proceed

Lo que NO ayudó

Intentar detectar "cambios de endpoint de API" desde el diff. Un cambio en un campo de schema de Pydantic basta), y los false negatives aquí son peores que los false positives. El check de path por git-diff es suficientemente bueno.
Cancel-in-progress en el workflow de frontend. Se ve atractivo matar el deploy de frontend en vuelo si llega un push nuevo — pero el cancel pasa a media S3-sync, dejando el bundle a medio subir. Combinado con un caché stale de CloudFront esto es peor que el race condition original. Lo dejamos en cancel-in-progress: false.

Qué sí ayudaría a futuro

Mover la lógica del gate a un action reutilizable (actions/wait-for-workflow@v1). Las ~80 líneas de bash funcionan pero están medio copy-pasteadas entre proyectos.
Sacar el conteo de pushes acoplados a un dashboard.** Si el ratio se va del 5% hacia el 30%, el gate simple deja de ser la herramienta correcta.
Hacer el deploy de backend más rápido para que la espera sea más corta cuando sí se active.

Lecciones

Los path filters definen qué cosas tus workflows acuerdan que los disparan. Mantenlos juntos y revísalos juntos.
El filtro head_sha en la API de Actions es lo más útil de todo esto. Existe, es estable, está documentado, y convierte "¿en cuál run estoy esperando?" de un problema difícil a un solo query.

Bajándole todos los minutos posibles al CI del backend con mas de 1000 tests

Franchesco Romero — Tue, 26 May 2026 05:11:47 +0000

Esta es la historia de muchas horas de trabajo en un hoyo continuo tratando de elegir optimizaciones entre package managers, caches, paralelismo, optimizaciones de PostgreSQL advisory locks, y el golpe de realidad de darme cuenta que el cuello de botella no era nada de lo que había estado optimizando, si no algo que no había analizado.

Antes de empezar aca esta el código disponible en Github para seguir paso a paso:

elchesco / improve-ci-times

improve-ci-times

Code companion — backend CI optimisation post

Stand-alone, copy-pasteable files for every code block in docs/blog-backend-ci-optimization.md.

Each folder maps to one round of the blog narrative:

00-starting-point/   the test job, Dockerfile, conftest before any work
01-uv/               drop pip for uv (Dockerfile + CI snippet)
02-buildkit/         BuildKit cache mounts + setup-buildx + --push
03-xdist-traps/      per-worker DB + DATABASE_URL alignment
04-template-db/      Postgres template DB + pg_advisory_lock
                     (plus the filelock dead-end as documentation)
05-diagnostic/       the measurement step that broke the assumption
06-final/            final shape — 4 matrix shards, no xdist, cumulative
                     Dockerfile + complete conftest

Notes

The xdist code (03, 04) is still present in 06-final/conftest.py for local pytest -n N runs even though the CI dropped xdist in favour of serial matrix shards.
04-template-db/filelock-attempt-DEAD-END.py is kept around…

View on GitHub

El punto de partida

El codebase:

un backend FastAPI (~50 routers, ~45 modelos SQLAlchemy)
1826 tests, desplegado vía GitHub Actions a AWS ECS Fargate en arm64.
El CI corre en un self-hosted spot runner (4X concurrencia, en Graviton).

En un inicio comenzamos con un paralelismo tradicional, nada del otro mundo, solo dos shards vía pytest-split.

# .github/workflows/deploy-backend.yml — inicial
- run: cd backend && pip install --cache-dir "$RUNNER_TEMP/pip-cache" -r requirements-dev.txt

- name: Tests (shard ${{ matrix.shard }}/2)
  run: |
    cd backend
    pytest tests/ \
      --splits 2 --group ${{ matrix.shard }} \
      --cov=app --cov-report= \
      -v

docker build estándar. Y usando pip para todo.

# backend/Dockerfile — inicial
FROM python:3.11-slim AS base
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq-dev gcc curl \
    && rm -rf /var/lib/apt/lists/*
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

Intento no. 1: instalar dependencias más rápido con `uv`

uv es el reemplazo más sencillo que existe de pip creado por Astral, normalmente de 10x hasta 100× más rápido para resolver e instalar paquetes. La migración es bastante sencilla ya que son dos
líneas en el Dockerfile y listo:

# Pin vía la imagen multi-stage oficial para que el binario sea reproducible
COPY --from=ghcr.io/astral-sh/uv:0.5.11 /uv /uvx /usr/local/bin/
RUN uv pip install --system --no-cache-dir -r requirements.txt

requirements.txt y requirements-dev.txt quedan exactamente iguales, uv pip los lee nativo. No hay que migrar forzosamente a pyproject.toml.

Y en CI, le implementamos la action correspondiente:

- uses: astral-sh/setup-uv@v6
  with:
    version: "0.5.11"
    enable-cache: true
    cache-suffix: "shard-${{ matrix.shard }}"
- run: cd backend && uv pip install --system -r requirements-dev.txt

En este caso el cache-suffix por shard replica el workaround del --cache-dir por shard que teníamos con pip — sin él, los dos shards que caen en el mismo runner self-hosted se pelean por el mismo tarball y uno de los dos se muere con tar exit code 2.

La comparativa, en números:

$ time uv pip install -r requirements.txt
...
uv pip install -r requirements.txt  1.23s user 1.59s system 51% cpu 5.509 total

5.5s contra ~60s con pip y casi 80s en el runner.

Intento no. 2: BuildKit cache mounts en el Dockerfile

El layer cache de Docker solo ayuda cuando el COPY no invalida las
layers de abajo. Cualquier cambio en requirements.txt re construye
todo lo que sigue. Los BuildKit cache mounts ayudan a persistir el contenido entre builds sin importar la invalidación de layers:

# backend/Dockerfile — con cache mounts
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update \
    && apt-get upgrade -y \
    && apt-get install -y --no-install-recommends \
        libpq-dev gcc curl

COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv pip install --system -r requirements.txt

Algo importante a mencionar:

Quitar el rm -rf /var/lib/apt/lists. Ya que servía para reducir el tamaño de la imagen, pero con cache mounts BuildKit es dueño de esos paths y los limpia entre builds sin hacer nada.
sharing=locked serializa lecturas concurrentes. Sin eso, dos builds en paralelo en el mismo runner pueden corromper el caché.

El runner que en este caso es self-hosted trae el builder legacy de Docker por default, y en el primer push después del commit de cache mounts se rompió con:

the --mount option requires BuildKit. Refer to
https://docs.docker.com/go/buildkit/ to learn how to build images with
BuildKit enabled

Lo arreglamos, de lo más fácil: instalar buildx y alias de docker build a docker buildx build:

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
    install: true

El install: true es la opción necesaria. Sin eso, docker build sigue usando el builder legacy.

Buildx no carga al daemon local por default, así que el step de
docker push que ya teníamos también dejó de funcionar. Cambiamos a
--push directo:

- run: |
    cd backend
    docker build \
      --cache-from $IMAGE:latest \
      --cache-to type=inline \
      -t $IMAGE:sha-$TAG \
      -t $IMAGE:latest \
      --push \
      .

El --cache-to type=inline mete la metadata del layer cache dentro
de la imagen, cojn estoel --cache-from del siguiente build lo jala de regreso el ECR.

El primer build todavía viene con el costo de instalación de las dependencias y paquetes; los builds siguientes con los mismos requirements se lo brincan. Pasando de ~40s a ~10s en cache hits.

Intento no. 3: la trampa de `pytest-xdist`

El instinto es pensar que entre mas shards, podemos ahorrarnos mas tiempo, es decir 2 shards × 4 workers = 8 procesos en paralelo.

# backend/requirements-dev.txt
pytest-xdist==3.6.1

# .github/workflows/deploy-backend.yml
pytest tests/ \
  --splits 2 --group ${{ matrix.shard }} \
  -n 4 --dist worksteal \
  --cov=app --cov-report= \
  -v

Pero, es aquí es donde empieza el dilema.

Trampa 1: `DROP SCHEMA` entre workers

En mi configuración el conftest remueve y recrea el schema al inicio de cada session:

@pytest_asyncio.fixture(scope="session", autouse=True)
async def setup_db():
    async with test_engine.begin() as conn:
        await conn.execute(sa.text("DROP SCHEMA public CASCADE"))
        await conn.execute(sa.text("CREATE SCHEMA public"))
    async with test_engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)

scope="session" significa una vez por session de pytest. Con
pytest-xdist, cada worker es su propia session.

Los cuatro workers apuntando a la misma DB myapp_test se la pasan removiendo el schema de los demás y en ocasiones nos quedamos a media corrida.

Fix: una DB por worker, con un sufijo de PYTEST_XDIST_WORKER:

def _suffix_dburl(url: str, worker: str) -> str:
    if "?" in url:
        url_part, _, query = url.partition("?")
        query = f"?{query}"
    else:
        url_part, query = url, ""
    if "/" not in url_part.split("@", 1)[-1]:
        return url
    prefix, dbname = url_part.rsplit("/", 1)
    return f"{prefix}/{dbname}_{worker}{query}"

_XDIST_WORKER = os.environ.get("PYTEST_XDIST_WORKER")
if _XDIST_WORKER:
    for key in ("DATABASE_URL", "TEST_DATABASE_URL"):
        if val := os.environ.get(key):
            os.environ[key] = _suffix_dburl(val, _XDIST_WORKER)

Con esto el worker gw0 agarra myapp_test_gw0, gw1 agarra _gw1, y así de manera secuencial.

Trampa 2: `max_locks_per_transaction`

Primera corrida con -n auto (10 workers en el runner self-hosted):

================== 31 passed, 11 warnings, 8 errors in 14.73s ==================

DROP SCHEMA CASCADE sobre ~50 tablas toma un relation-level lock por cada una.

10 workers x 50 = 500 locks.

El default de PostgreSQL para max_locks_per_transaction es 64.

Como lo arreglamos, bajamos el limite/cap a 4 workers por shard en vez de auto. 4 x 2 shards = 8 procesos paralelos.

Trampa 3: la divergencia del `DATABASE_URL`

Después de limitar a los workers, un test empezó a fallar en CI:

test_comp_expiry_worker_skips_stripe_managed
  sqlalchemy.exc.ProgrammingError: relation "subscriptions" does not
  exist

¿Por qué? El test invoca un background worker:

async def test_comp_expiry_worker_skips_stripe_managed(client, db, admin):
    member = await _seed_user(db, tier="TEST")
    sub = await _seed_sub(db, member, tier="TEST", ...)
    await db.commit()

    from app.workers.comp_expiry_worker import expire_comp_subscriptions
    await expire_comp_subscriptions()  # ← abre su propio AsyncSessionLocal

Fix: alinear DATABASE_URL con TEST_DATABASE_URL antes de que
app.main importe lo que sea:

# backend/tests/conftest.py — top del archivo, antes de importar app.main
_test_db = os.environ.get("TEST_DATABASE_URL")
if _test_db:
    os.environ["DATABASE_URL"] = _test_db

_XDIST_WORKER = os.environ.get("PYTEST_XDIST_WORKER")
if _XDIST_WORKER:
    for key in ("DATABASE_URL", "TEST_DATABASE_URL"):
        if val := os.environ.get(key):
            os.environ[key] = _suffix_dburl(val, _XDIST_WORKER)

from app.main import app  # ← engine construido con la URL correcta desde el inicio

Intento no. 4: template database de PostgreSQL

Cada worker todavía usa un DROP SCHEMA + CREATE TABLE × 50 al
inicio de la session.

En el runner ARM eso son ~5 segundos por worker.

PostgreSQL tiene un truco: CREATE DATABASE ... TEMPLATE
clona una DB vía copia a nivel de archivo en ~100ms en lugar de
ejecutar todo el SQL.

Construyes el schema una vez en una DB template dedicada, y luego cada worker la clona:

# backend/tests/conftest.py
TEMPLATE_DB_NAME = "myapp_test_template"
_TEMPLATE_LOCK_ID = 7321456789012345  # int arbitrario 

async def _ensure_template_db(admin_url: str, template_url: str) -> None:
    admin_engine = create_async_engine(
        admin_url, isolation_level="AUTOCOMMIT", poolclass=NullPool
    )
    try:
        async with admin_engine.connect() as conn:
            exists = (await conn.execute(
                sa.text("SELECT 1 FROM pg_database WHERE datname = :n"),
                {"n": TEMPLATE_DB_NAME},
            )).scalar_one_or_none()
            if not exists:
                await conn.execute(
                    sa.text(f'CREATE DATABASE "{TEMPLATE_DB_NAME}"')
                )
    finally:
        await admin_engine.dispose()

    tmpl_engine = create_async_engine(template_url, poolclass=NullPool)
    try:
        async with tmpl_engine.connect() as conn:
            has_schema = (await conn.execute(sa.text(
                "SELECT 1 FROM information_schema.tables "
                "WHERE table_schema = 'public' AND table_name = 'users' "
                "LIMIT 1"
            ))).scalar_one_or_none()
        if not has_schema:
            async with tmpl_engine.begin() as conn:
                await conn.run_sync(Base.metadata.create_all)
    finally:
        await tmpl_engine.dispose()


async def _clone_template_to(admin_url: str, dbname: str) -> None:
    admin_engine = create_async_engine(
        admin_url, isolation_level="AUTOCOMMIT", poolclass=NullPool
    )
    try:
        async with admin_engine.connect() as conn:
            # Matar conexiones stale para que el DROP no se bloquee
            await conn.execute(sa.text(
                "SELECT pg_terminate_backend(pid) FROM pg_stat_activity "
                "WHERE datname = :n AND pid <> pg_backend_pid()"
            ), {"n": dbname})
            await conn.execute(sa.text(f'DROP DATABASE IF EXISTS "{dbname}"'))
            await conn.execute(sa.text(
                f'CREATE DATABASE "{dbname}" TEMPLATE "{TEMPLATE_DB_NAME}"'
            ))
    finally:
        await admin_engine.dispose()

Trampa 4: `filelock` se cuelga

Los workers se pelean por crear el template. El primer intento usaba
filelock:

# No hagas esto
import filelock
lock = filelock.FileLock("/tmp/myapp_test_template.lock", timeout=120)
await asyncio.to_thread(lock.acquire)

Los workers consistentemente se quedan colgados y llegan a el timeout de 120s.

Con un cambio a un advisory lock de PostgreSQL, se soluciona. Es el mismo recurso compartido que ya necesitamos, se auto libera al cerrar la conexión:

async def _setup_db_via_template() -> None:
    split = _split_db_url(TEST_DATABASE_URL)
    if split is None:
        return
    prefix, dbname = split
    admin_url = f"{prefix}/postgres"
    template_url = f"{prefix}/{TEMPLATE_DB_NAME}"

    admin_engine = create_async_engine(
        admin_url, isolation_level="AUTOCOMMIT", poolclass=NullPool
    )
    try:
        async with admin_engine.connect() as conn:
            # Bloquea hasta conseguirlo; se auto-libera al cerrar la conexión
            await conn.execute(
                sa.text("SELECT pg_advisory_lock(:id)"),
                {"id": _TEMPLATE_LOCK_ID},
            )
            try:
                await _ensure_template_db(admin_url, template_url)
            finally:
                await conn.execute(
                    sa.text("SELECT pg_advisory_unlock(:id)"),
                    {"id": _TEMPLATE_LOCK_ID},
                )
    finally:
        await admin_engine.dispose()

    await _clone_template_to(admin_url, dbname)

El primer worker que agarra el lock construye el template (~5s); los demás esperan y luego clonan en ~100ms cada uno.

Después de todo esto tenemos DB por worker, alineación de DATABASE_URL, template clones, advisory locks — corriendo un smoke local de 7 archivos, notamos la diferencia:

88 passed, 5 warnings in 12.28s

Bajó de ~2 minutos con el setup inicial a unos cuantos segundos.

Intento no. 5: la medición que rompió el supuesto

El wall time por shard seguía como en 7 minutos.
El CI total en 11m una mejora modesta sobre el baseline inicial, pero no la bajada dramática que sugería el smoke local.

Hora de medir en serio.
Agregué un step diagnóstico que corre una vez y reporta tiempos:

- name: Diagnose pytest startup cost
  if: matrix.shard == 1
  run: |
    cd backend
    echo "::group::A — solo collection de pytest, sin coverage"
    time pytest tests/ --co -q --no-header --no-cov
    echo "::endgroup::"
    echo "::group::B — solo collection de pytest CON coverage"
    time pytest tests/ --co -q --no-header --cov=app --cov-report=
    echo "::endgroup::"
    echo "::group::C — corrida chiquita serial, sin coverage, sin xdist"
    time pytest tests/test_critical.py -q --no-header --no-cov
    echo "::endgroup::"

Los resultados en el runner ARM self-hosted fueron:

A — solo collection, sin coverage          real    0m18.909s
B — solo collection CON coverage           real    0m23.810s
C — corrida chica serial, sin nada         real    0m21.481s

La observación clave, hacer collection de 1826 tests y
correr un solo archivo chico sin coverage tardan lo mismo.

O sea, el costo no es la collection.
No es coverage (solo 5s de diferencia).
No es la ejecución de los tests.
Es el startup de pytest + el import del conftest.
Específicamente el from app.main import app en el conftest que jala ~45 modelos, ~50 routers, middleware, settings, todo de un jalón. Veinte segundos de cold import en este runner.

Cada vez.

Con xdist, cada uno de los 4 workers paga este costo de 20s
independiente.

Ahí estaban los ~80s perdidos.

Round 6: soltar `xdist`, irse a 4 shards

Si cada proceso de pytest usa 20s fijos de startup, la optimización
más barata es usarlo menos veces.
2 shards X 4 workers de xdist = 10 startups de pytest (2 controllers + 8 workers).
4 shards X 1 proceso serial = 4 startups de pytest.

test:
  runs-on: ${{ inputs.runner || 'self-hosted' }}
  needs: lint
  strategy:
    fail-fast: false
    matrix:
      shard: [1, 2, 3, 4]
  services:
    postgres:
      image: postgres:15
      env: { POSTGRES_DB: myapp_test, POSTGRES_USER: appuser, POSTGRES_PASSWORD: testpass }
      options: >-
        --health-cmd pg_isready --health-interval 10s
        --health-timeout 5s --health-retries 5
      ports: ["5432"]
  steps:
    - uses: actions/checkout@v5
    - uses: actions/setup-python@v6
      with: { python-version: "3.11" }
    - uses: astral-sh/setup-uv@v6
      with:
        version: "0.5.11"
        enable-cache: true
        cache-suffix: "shard-${{ matrix.shard }}"
    - run: cd backend && uv pip install --system -r requirements-dev.txt
    - name: Tests (shard ${{ matrix.shard }}/4)
      env:
        DATABASE_URL: postgresql://someappuser:sometestpass@localhost:${{ job.services.postgres.ports[5432] }}/myapp_test
        TEST_DATABASE_URL: postgresql+asyncpg://someappuser:sometestpass@localhost:${{ job.services.postgres.ports[5432] }}/myapp_test
        SECRET_KEY: ci-test-secret-key-32bytes-minimum-length
        ENV: test
        COVERAGE_FILE: .coverage.${{ matrix.shard }}
      run: |
        cd backend
        pytest tests/ \
          --splits 4 --group ${{ matrix.shard }} \
          --cov=app --cov-report= \
          -q --no-header

Cada shard corre ~450 tests en serial con un solo proceso de pytest.

Sin fan-out de xdist, sin re-import de conftest por worker, sin temas de CPU en los cold imports.

El runner self-hosted anuncia 4X de concurrencia disponible, así que los cuatro shards corren en paralelo.

El coverage se extiende a cuatro archivos:

coverage:
  needs: test
  steps:
    - uses: actions/checkout@v5
    - uses: actions/setup-python@v6
      with: { python-version: "3.11" }
    - uses: astral-sh/setup-uv@v6
      with: { version: "0.5.11" }
    - run: uv pip install --system coverage==7.6.1
    - uses: actions/download-artifact@v5
      with:
        pattern: coverage-*
        path: backend/
        merge-multiple: true
    - run: |
        cd backend
        coverage combine .coverage.1 .coverage.2 .coverage.3 .coverage.4
        coverage report --fail-under=60

También quité el -v y lo cambié por -q --no-header. Con xdist, el -v bufferea el output por worker hasta que termina un test, -q tiene output instantáneo y muestra la salida de inmediato.

El resultado

Corrida real del CI después del push:

✓ lint              in 1m6s
✓ test (1)          in 6m46s
✓ test (2)          in 6m44s
✓ test (3)          in 6m57s
✓ test (4)          in 6m57s
✓ coverage          in 10s
✓ build-and-deploy  in 1m53s

Timeline del test step del shard 1:

16:31:44  inicio del step
16:32:57  [pytest-split] Running group 1/4   ← 1m13s adentro
16:33:25  ........... [ 15%]                  ← primer punto a 1m41s
16:34:18  ........... [ 45%]
16:37:04  ........... [ 91%]
16:37:47  ........... [100%]  472 passed in 5m21s

Tiempo al primer output: 1m13s vs 2m37s antes.
Más o menos a la mitad.

CI total: 10m16s vs ~20m del baseline antes de cualquier optimización.

Otras cosas que probe y que definitivamente no ayudaron

Precompile de pyc (python -m compileall). Medición local: 13.0s en frío vs 12.6s en caliente.
pytest-xdist --dist worksteal está bueno cuando cada worker tiene un costo de setup parecido. Cuando el setup es ~20s y los tests son mayormente rápidos, el impuesto de startup por worker se come la ganancia de paralelismo.
filelock para serializar entre procesos. No me serializaba bien los workers en mi setup. Me cambié a advisory locks de PG.
El flag -v. Causaba 2 minutos de buffering de output bajo xdist sin beneficio en performance.

Qué sí ayudaría a futuro

Mejorar el conftest. El from app.main import app es el costo más grande en mi caso. La app importa cada router, cada modelo, cada service al arranque. Partirla (lazy router registration, o romper el import monolítico) bajaría a 20s de startup.
Una segunda pasada en los shards. pytest-split balancea por duración. Si un shard consistentemente va 30s atrás, re-balancea:

   pytest --splits 4 --group 1 --store-durations

comitea un .test_durations nuevo contra el que los futuros runs
se balancean.

Sacar coverage del hot path. Coverage solo agregó ~5s en ARM en nuestro benchmark, pero a ~5s × 4 shards = 20s ahorrados. Trade-off: o lo aceptas en el job de tests o agregas un job de coverage no-paralelo aparte. Nosotros lo dejamos en el path.

Lecciones

Mide antes de optimizar. Varias horas de trabajo en xdist, template DBs y BuildKit fueron útiles, pero el verdadero unlock vino de un step diagnóstico de 30 segundos que me dijo que el cuello de botella era el startup de pytest, no nada de lo que llevaba atacando.
El pytest más rápido es uno que no inicias dos veces. Cada invocación de pytest paga un costo de startup fijo. Con un conftest pesado, ese costo domina todo lo demás. Más paralelismo = más startups = más costo. Menos shards más grandes le ganan a más shards chiquitos pasado un umbral.
pytest-xdist no es gratis. Funciona bien cuando el costo por test >> el costo de startup. Cuando el startup es 20s y los tests son de 500ms, la ecuación se invierte.
Recursos por worker necesitan aislamiento por worker. El bug sutil fue que los background workers abrían su propio AsyncSessionLocal apuntando a la DB equivocada. El fix no estaba en la aplicación — estaba en el conftest de tests, alineando las env vars antes de que la app importara nada.
PostgreSQL tiene las primitivas. Advisory locks para sincronizar entre procesos, CREATE DATABASE ... TEMPLATE para bootstrap de schema. Las dos me salvaron de inventar mecanismos más débiles encima.
Los BuildKit cache mounts siguen sub-utilizados. Dos líneas en un Dockerfile (--mount=type=cache para los cachés de apt y uv/pip) bajaron los docker builds repetidos de ~40s a ~10s, pero solo después de cambiarse del builder legacy de Docker vía setup-buildx-action.

Código completo disponible en Github:

elchesco / improve-ci-times

improve-ci-times

Code companion — backend CI optimisation post

Stand-alone, copy-pasteable files for every code block in docs/blog-backend-ci-optimization.md.

Each folder maps to one round of the blog narrative:

00-starting-point/   the test job, Dockerfile, conftest before any work
01-uv/               drop pip for uv (Dockerfile + CI snippet)
02-buildkit/         BuildKit cache mounts + setup-buildx + --push
03-xdist-traps/      per-worker DB + DATABASE_URL alignment
04-template-db/      Postgres template DB + pg_advisory_lock
                     (plus the filelock dead-end as documentation)
05-diagnostic/       the measurement step that broke the assumption
06-final/            final shape — 4 matrix shards, no xdist, cumulative
                     Dockerfile + complete conftest

Notes

The xdist code (03, 04) is still present in 06-final/conftest.py for local pytest -n N runs even though the CI dropped xdist in favour of serial matrix shards.
04-template-db/filelock-attempt-DEAD-END.py is kept around…

View on GitHub

Bajándole todos los minutos posibles al CI del backend con mas de 1000 tests

Franchesco Romero — Tue, 26 May 2026 05:11:47 +0000

Esta es la historia de muchas horas de trabajo en un hoyo continuo tratando de elegir optimizaciones entre package managers, caches paralelismo, optimizaciones de PostgreSQL, advisory locks, y el golpe de realidad de darme cuenta que el cuello de botella no era nada de lo que había estado optimizando, si no algo que no había analizado.

El punto de partida

El codebase: un backend FastAPI (~50 routers, ~45 modelos SQLAlchemy)
con 1826 tests, desplegado vía GitHub Actions a AWS ECS Fargate en
arm64. El CI corre en un self-hosted spot runner (4× concurrency,
Graviton).

En un inicio comenzamos con un paralelismo tradicional, nada del otro mundo, solo dos shards vía pytest-split.

# .github/workflows/deploy-backend.yml — inicial
- run: cd backend && pip install --cache-dir "$RUNNER_TEMP/pip-cache" -r requirements-dev.txt

- name: Tests (shard ${{ matrix.shard }}/2)
  run: |
    cd backend
    pytest tests/ \
      --splits 2 --group ${{ matrix.shard }} \
      --cov=app --cov-report= \
      -v

docker build estándar. Y usando pip para todo.

# backend/Dockerfile — inicial
FROM python:3.11-slim AS base
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq-dev gcc curl \
    && rm -rf /var/lib/apt/lists/*
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

Intento no. 1: instalar dependencias más rápido con uv

# Pin vía la imagen multi-stage oficial para que el binario sea reproducible
COPY --from=ghcr.io/astral-sh/uv:0.5.11 /uv /uvx /usr/local/bin/
RUN uv pip install --system --no-cache-dir -r requirements.txt

requirements.txt y requirements-dev.txt quedan exactamente iguales, uv pip los lee nativo. No hay que migrar forzosamente a pyproject.toml.

Y en CI, le implementamos la action correspondiente:

- uses: astral-sh/setup-uv@v6
  with:
    version: "0.5.11"
    enable-cache: true
    cache-suffix: "shard-${{ matrix.shard }}"
- run: cd backend && uv pip install --system -r requirements-dev.txt

La comparativa, en números:

$ time uv pip install -r requirements.txt
...
uv pip install -r requirements.txt  1.23s user 1.59s system 51% cpu 5.509 total

5.5s contra ~60s con pip y casi 80s en el runner.

Intento no. 2: BuildKit cache mounts en el Dockerfile

El layer cache de Docker solo ayuda cuando el COPY no invalida las
layers de abajo. Cualquier cambio en requirements.txt re-construye
todo lo que sigue. Los BuildKit cache mounts ayudan a persistir el contenido entre builds sin importar la invalidación de layers:

# backend/Dockerfile — con cache mounts
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update \
    && apt-get upgrade -y \
    && apt-get install -y --no-install-recommends \
        libpq-dev gcc curl

COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv pip install --system -r requirements.txt

Algo importante a mencionar:

Quitar el rm -rf /var/lib/apt/lists. Ya que servía para reducir el tamaño de la imagen, pero con cache mounts BuildKit es dueño de esos paths y los limpia entre builds.
sharing=locked serializa lecturas concurrentes. Sin eso, dos builds en paralelo en el mismo runner pueden corromper el caché.

El runner que en este caso es self-hosted trae el builder legacy de Docker por default, y el primer push después del commit de cache mounts se murió con:

the --mount option requires BuildKit. Refer to
https://docs.docker.com/go/buildkit/ to learn how to build images with
BuildKit enabled

Lo arreglamos, de lo más fácil: instalar buildx y alias de docker build a docker buildx build:

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
    install: true

El install: true es la opción crítica. Sin eso, docker build sigue usando el builder legacy.

Buildx no carga al daemon local por default, así que el step de
docker push que ya teníamos también dejó de funcionar. Cambio a
--push directo:

- run: |
    cd backend
    docker build \
      --cache-from $IMAGE:latest \
      --cache-to type=inline \
      -t $IMAGE:sha-$TAG \
      -t $IMAGE:latest \
      --push \
      .

El --cache-to type=inline mete la metadata del layer cache dentro
de la imagen, cojn estoel --cache-from del siguiente build lo jala de regreso el ECR.

El primer build todavía paga el costo de instalación de las dependencias y paquetes; los builds siguientes con los mismos requirements se lo brincan. Pasando de ~40s a ~10s en cache hits.

Intento no. 3: la trampa de `pytest-xdist`

El instinto, pensar que entre mas shards, podemos ahorrarnos mas tiempo, es decir 2 shards × 4 workers = 8 procesos en paralelo.

# backend/requirements-dev.txt
pytest-xdist==3.6.1

# .github/workflows/deploy-backend.yml
pytest tests/ \
  --splits 2 --group ${{ matrix.shard }} \
  -n 4 --dist worksteal \
  --cov=app --cov-report= \
  -v

Aquí es donde empieza el dilema.

Trampa 1: `DROP SCHEMA` entre workers

El conftest remueve y recrea el schema al inicio de cada session:

@pytest_asyncio.fixture(scope="session", autouse=True)
async def setup_db():
    async with test_engine.begin() as conn:
        await conn.execute(sa.text("DROP SCHEMA public CASCADE"))
        await conn.execute(sa.text("CREATE SCHEMA public"))
    async with test_engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)

scope="session" significa una vez por session de pytest. Con
pytest-xdist, cada worker es su propia session.

Los cuatro workers apuntando a la misma DB myapp_test se la pasan removiendo el schema de los demás a media corrida.

Fix: una DB por worker, con sufijo de PYTEST_XDIST_WORKER:

def _suffix_dburl(url: str, worker: str) -> str:
    if "?" in url:
        url_part, _, query = url.partition("?")
        query = f"?{query}"
    else:
        url_part, query = url, ""
    if "/" not in url_part.split("@", 1)[-1]:
        return url
    prefix, dbname = url_part.rsplit("/", 1)
    return f"{prefix}/{dbname}_{worker}{query}"

_XDIST_WORKER = os.environ.get("PYTEST_XDIST_WORKER")
if _XDIST_WORKER:
    for key in ("DATABASE_URL", "TEST_DATABASE_URL"):
        if val := os.environ.get(key):
            os.environ[key] = _suffix_dburl(val, _XDIST_WORKER)

El worker gw0 agarra myapp_test_gw0, gw1 agarra _gw1, y así de manera secuencial.

Trampa 2: `max_locks_per_transaction`

Primera corrida con -n auto (10 workers en el runner self-hosted):

================== 31 passed, 11 warnings, 8 errors in 14.73s ==================

DROP SCHEMA CASCADE sobre ~50 tablas toma un relation-level lock por cada una.

10 workers × 50 = 500 locks.

El default de PostgreSQL para max_locks_per_transaction es 64

Como lo arreglamos, bajamos el limite/cap a 4 workers por shard en vez de auto. 4 × 2 shards = 8 procesos paralelos.

Trampa 3: la divergencia del `DATABASE_URL`

Después de limitar a los workers, un test empezó a fallar en CI:

test_comp_expiry_worker_skips_stripe_managed
  sqlalchemy.exc.ProgrammingError: relation "subscriptions" does not
  exist

¿Por qué? El test invoca un background worker:

async def test_comp_expiry_worker_skips_stripe_managed(client, db, admin):
    member = await _seed_user(db, tier="TEST")
    sub = await _seed_sub(db, member, tier="TEST", ...)
    await db.commit()

    from app.workers.comp_expiry_worker import expire_comp_subscriptions
    await expire_comp_subscriptions()  # ← abre su propio AsyncSessionLocal

Fix: alinear DATABASE_URL con TEST_DATABASE_URL antes de que
app.main importe lo que sea:

# backend/tests/conftest.py — top del archivo, antes de importar app.main
_test_db = os.environ.get("TEST_DATABASE_URL")
if _test_db:
    os.environ["DATABASE_URL"] = _test_db

_XDIST_WORKER = os.environ.get("PYTEST_XDIST_WORKER")
if _XDIST_WORKER:
    for key in ("DATABASE_URL", "TEST_DATABASE_URL"):
        if val := os.environ.get(key):
            os.environ[key] = _suffix_dburl(val, _XDIST_WORKER)

from app.main import app  # ← engine construido con la URL correcta desde el inicio

Intento no. 4: template database de PostgreSQL

Cada worker todavía usa un DROP SCHEMA + CREATE TABLE × 50 al
inicio de la session.
En el runner ARM eso son ~5 segundos por worker.

PostgreSQL tiene un truco: CREATE DATABASE ... TEMPLATE
clona una DB vía copia a nivel de archivo en ~100ms en lugar de
ejecutar todo el SQL.

Construyes el schema una vez en una DB template dedicada, y luego cada worker la clona:

# backend/tests/conftest.py
TEMPLATE_DB_NAME = "myapp_test_template"
_TEMPLATE_LOCK_ID = 7321456789012345  # int arbitrario 

async def _ensure_template_db(admin_url: str, template_url: str) -> None:
    admin_engine = create_async_engine(
        admin_url, isolation_level="AUTOCOMMIT", poolclass=NullPool
    )
    try:
        async with admin_engine.connect() as conn:
            exists = (await conn.execute(
                sa.text("SELECT 1 FROM pg_database WHERE datname = :n"),
                {"n": TEMPLATE_DB_NAME},
            )).scalar_one_or_none()
            if not exists:
                await conn.execute(
                    sa.text(f'CREATE DATABASE "{TEMPLATE_DB_NAME}"')
                )
    finally:
        await admin_engine.dispose()

    tmpl_engine = create_async_engine(template_url, poolclass=NullPool)
    try:
        async with tmpl_engine.connect() as conn:
            has_schema = (await conn.execute(sa.text(
                "SELECT 1 FROM information_schema.tables "
                "WHERE table_schema = 'public' AND table_name = 'users' "
                "LIMIT 1"
            ))).scalar_one_or_none()
        if not has_schema:
            async with tmpl_engine.begin() as conn:
                await conn.run_sync(Base.metadata.create_all)
    finally:
        await tmpl_engine.dispose()


async def _clone_template_to(admin_url: str, dbname: str) -> None:
    admin_engine = create_async_engine(
        admin_url, isolation_level="AUTOCOMMIT", poolclass=NullPool
    )
    try:
        async with admin_engine.connect() as conn:
            # Matar conexiones stale para que el DROP no se bloquee
            await conn.execute(sa.text(
                "SELECT pg_terminate_backend(pid) FROM pg_stat_activity "
                "WHERE datname = :n AND pid <> pg_backend_pid()"
            ), {"n": dbname})
            await conn.execute(sa.text(f'DROP DATABASE IF EXISTS "{dbname}"'))
            await conn.execute(sa.text(
                f'CREATE DATABASE "{dbname}" TEMPLATE "{TEMPLATE_DB_NAME}"'
            ))
    finally:
        await admin_engine.dispose()

Trampa 4: `filelock` se cuelga

Los workers se pelean por crear el template. El primer intento usaba
filelock:

# No hagas esto
import filelock
lock = filelock.FileLock("/tmp/myapp_test_template.lock", timeout=120)
await asyncio.to_thread(lock.acquire)

Los workers consistentemente llegan a el timeout de 120s.

Con un cambio a un advisory lock de PostgreSQL, se soluciona. Es el mismo recurso compartido que ya necesitamos, se auto libera al cerrar la conexión (así que un worker que truene no puede dejar el lock huérfano como pasa con file locks):

async def _setup_db_via_template() -> None:
    split = _split_db_url(TEST_DATABASE_URL)
    if split is None:
        return
    prefix, dbname = split
    admin_url = f"{prefix}/postgres"
    template_url = f"{prefix}/{TEMPLATE_DB_NAME}"

    admin_engine = create_async_engine(
        admin_url, isolation_level="AUTOCOMMIT", poolclass=NullPool
    )
    try:
        async with admin_engine.connect() as conn:
            # Bloquea hasta conseguirlo; se auto-libera al cerrar la conexión
            await conn.execute(
                sa.text("SELECT pg_advisory_lock(:id)"),
                {"id": _TEMPLATE_LOCK_ID},
            )
            try:
                await _ensure_template_db(admin_url, template_url)
            finally:
                await conn.execute(
                    sa.text("SELECT pg_advisory_unlock(:id)"),
                    {"id": _TEMPLATE_LOCK_ID},
                )
    finally:
        await admin_engine.dispose()

    await _clone_template_to(admin_url, dbname)

El primer worker que agarra el lock construye el template (~5s); los demás esperan y luego clonan en ~100ms cada uno.

Después de todo esto — DBs por worker, alineación de DATABASE_URL,
template clones, advisory locks — corriendo un smoke local de 7
archivos:

88 passed, 5 warnings in 12.28s

Bajó de ~2 minutos con el setup roto inicial de xdist.

Intento no. 5: la medición que rompió el supuesto

El wall time por shard seguía como en 7 minutos.
El CI total en 11m una mejora modesta sobre el baseline, no la bajada dramática que sugería el smoke local.

Hora de medir en serio. Agregué un step diagnóstico que corre una vez
y reporta tiempos:

- name: Diagnose pytest startup cost
  if: matrix.shard == 1
  run: |
    cd backend
    echo "::group::A — solo collection de pytest, sin coverage"
    time pytest tests/ --co -q --no-header --no-cov
    echo "::endgroup::"
    echo "::group::B — solo collection de pytest CON coverage"
    time pytest tests/ --co -q --no-header --cov=app --cov-report=
    echo "::endgroup::"
    echo "::group::C — corrida chiquita serial, sin coverage, sin xdist"
    time pytest tests/test_critical.py -q --no-header --no-cov
    echo "::endgroup::"

Los resultados en el runner ARM self-hosted fueron:

A — solo collection, sin coverage          real    0m18.909s
B — solo collection CON coverage           real    0m23.810s
C — corrida chica serial, sin nada         real    0m21.481s

La observación clave, hacer collection de 1826 tests y
correr un solo archivo chico sin coverage tardan lo mismo.

O sea, el costo no es la collection. No es coverage (solo 5s de
diferencia).
No es la ejecución de los tests. Es el startup de pytest + el import del conftest.
Específicamente el from app.main import app en el conftest que jala ~45 modelos, ~50 routers, middleware, settings — todo de un jalón. Veinte segundos de cold-import en este runner.
Cada vez.

Con xdist, cada uno de los 4 workers paga este costo de 20s
independiente. Spawn en paralelo, pero el runner solo tiene ciertos
cores; los cold imports de modelos pydantic y mappers de SQLAlchemy se pelean por CPU.

Ahí estaban los ~80s perdidos.

Round 6: soltar `xdist`, irse a 4 shards

Si cada proceso de pytest usa 20s fijos de startup, la optimización
más barata es usarlo menos veces.
2 shards × 4 workers de xdist = 10 startups de pytest (2 controllers + 8 workers).
4 shards × 1 proceso serial = 4 startups de pytest.

test:
  runs-on: ${{ inputs.runner || 'self-hosted' }}
  needs: lint
  strategy:
    fail-fast: false
    matrix:
      shard: [1, 2, 3, 4]
  services:
    postgres:
      image: postgres:15
      env: { POSTGRES_DB: myapp_test, POSTGRES_USER: appuser, POSTGRES_PASSWORD: testpass }
      options: >-
        --health-cmd pg_isready --health-interval 10s
        --health-timeout 5s --health-retries 5
      ports: ["5432"]
  steps:
    - uses: actions/checkout@v5
    - uses: actions/setup-python@v6
      with: { python-version: "3.11" }
    - uses: astral-sh/setup-uv@v6
      with:
        version: "0.5.11"
        enable-cache: true
        cache-suffix: "shard-${{ matrix.shard }}"
    - run: cd backend && uv pip install --system -r requirements-dev.txt
    - name: Tests (shard ${{ matrix.shard }}/4)
      env:
        DATABASE_URL: postgresql://someappuser:sometestpass@localhost:${{ job.services.postgres.ports[5432] }}/myapp_test
        TEST_DATABASE_URL: postgresql+asyncpg://someappuser:sometestpass@localhost:${{ job.services.postgres.ports[5432] }}/myapp_test
        SECRET_KEY: ci-test-secret-key-32bytes-minimum-length
        ENV: test
        COVERAGE_FILE: .coverage.${{ matrix.shard }}
      run: |
        cd backend
        pytest tests/ \
          --splits 4 --group ${{ matrix.shard }} \
          --cov=app --cov-report= \
          -q --no-header

Cada shard corre ~450 tests en serial con un solo proceso depytest.

Sin fan-out de xdist, sin re-import de conftest por worker, sin contención de CPU en los cold imports.

El runner self-hosted anuncia 4x de concurrencia disponible, así que los cuatro shards corren en paralelo.

El coverage se extiende a cuatro archivos:

coverage:
  needs: test
  steps:
    - uses: actions/checkout@v5
    - uses: actions/setup-python@v6
      with: { python-version: "3.11" }
    - uses: astral-sh/setup-uv@v6
      with: { version: "0.5.11" }
    - run: uv pip install --system coverage==7.6.1
    - uses: actions/download-artifact@v5
      with:
        pattern: coverage-*
        path: backend/
        merge-multiple: true
    - run: |
        cd backend
        coverage combine .coverage.1 .coverage.2 .coverage.3 .coverage.4
        coverage report --fail-under=60

El resultado

Corrida real del CI después del push:

✓ lint              in 1m6s
✓ test (1)          in 6m46s
✓ test (2)          in 6m44s
✓ test (3)          in 6m57s
✓ test (4)          in 6m57s
✓ coverage          in 10s
✓ build-and-deploy  in 1m53s

Timeline del test step del shard 1:

16:31:44  inicio del step
16:32:57  [pytest-split] Running group 1/4   ← 1m13s adentro
16:33:25  ........... [ 15%]                  ← primer punto a 1m41s
16:34:18  ........... [ 45%]
16:37:04  ........... [ 91%]
16:37:47  ........... [100%]  472 passed in 5m21s

Tiempo al primer output: 1m13s vs 2m37s antes.
Más o menos a la mitad.

CI total: 10m16s vs ~20m del baseline antes de cualquier optimización.

Otras cosas que probe y que definitivamente no ayudaron

Precompile de pyc (python -m compileall). Medición local: 13.0s en frío vs 12.6s en caliente.
pytest-xdist --dist worksteal está bueno cuando cada worker tiene un costo de setup parecido. Cuando el setup es ~20s y los tests son mayormente rápidos, el impuesto de startup por worker se come la ganancia de paralelismo.
filelock para serializar entre procesos. No me serializaba bien los workers en mi setup. Me cambié a advisory locks de PG.
El flag -v. Causaba 2 minutos de buffering de output bajo xdist sin beneficio en performance.

Qué sí ayudaría a futuro

Mejorar el conftest. El from app.main import app es el costo más grande en mi caso. La app importa cada router, cada modelo, cada service al arranque. Partirla (lazy router registration, o romper el import monolítico) bajaría a 20s de startup.
Una segunda pasada en los shards. pytest-split balancea por duración. Si un shard consistentemente va 30s atrás, re-balancea:

   pytest --splits 4 --group 1 --store-durations

comitea un .test_durations nuevo contra el que los futuros runs
se balancean.

Sacar coverage del hot path. Coverage solo agregó ~5s en ARM en nuestro benchmark, pero a ~5s × 4 shards = 20s ahorrados. Trade-off: o lo aceptas en el job de tests o agregas un job de coverage no-paralelo aparte. Nosotros lo dejamos en el path.

Lecciones

Mide antes de optimizar. Varias horas de trabajo en xdist, template DBs y BuildKit fueron útiles, pero el verdadero unlock vino de un step diagnóstico de 30 segundos que me dijo que el cuello de botella era el startup de pytest, no nada de lo que llevaba atacando.
El pytest más rápido es uno que no inicias dos veces. Cada invocación de pytest paga un costo de startup fijo. Con un conftest pesado, ese costo domina todo lo demás. Más paralelismo = más startups = más costo. Menos shards más grandes le ganan a más shards chiquitos pasado un umbral.
pytest-xdist no es gratis. Funciona bien cuando el costo por test >> el costo de startup. Cuando el startup es 20s y los tests son de 500ms, la ecuación se invierte.
Recursos por worker necesitan aislamiento por worker. El bug sutil fue que los background workers abrían su propio AsyncSessionLocal apuntando a la DB equivocada. El fix no estaba en la aplicación — estaba en el conftest de tests, alineando las env vars antes de que la app importara nada.
PostgreSQL tiene las primitivas. Advisory locks para sincronizar entre procesos, CREATE DATABASE ... TEMPLATE para bootstrap de schema. Las dos me salvaron de inventar mecanismos más débiles encima.
Los BuildKit cache mounts siguen sub-utilizados. Dos líneas en un Dockerfile (--mount=type=cache para los cachés de apt y uv/pip) bajaron los docker builds repetidos de ~40s a ~10s, pero solo después de cambiarse del builder legacy de Docker vía setup-buildx-action.

Pros y Cons de las arquitecturas multi-región

Franchesco Romero — Thu, 02 Apr 2026 22:07:40 +0000

Pros y Cons de las arquitecturas multi-región - Speaker Deck

speakerdeck.com

Los retos reales de ir multi-región

Antes de hablar de soluciones, hay que nombrar los retos con claridad porque es donde más se subestima el esfuerzo. El primero es elegir la solución tecnológica correcta — no todas las cargas de trabajo necesitan multi-región y no todos los servicios de AWS están disponibles igual en todas las regiones. El segundo es el manejo de fallos a escala: no basta con tener recursos en dos regiones si no has pensado cómo se comporta cada componente ante una falla. El tercero es la cercanía a los usuarios, que no siempre es puramente técnica — hay leyes, regulaciones y requisitos de soberanía de datos que dictan dónde puede vivir tu información.

Ignorar cualquiera de estos puntos al inicio garantiza una conversación mucho más difícil después.

Tolerancia a fallos: el modelo mental que todo lo rige

El concepto clave aquí es el dominio de error (fault domain). Cada componente de tu arquitectura pertenece a un dominio que define su política de falla: puede ser redundante (se replica), ignorable (su caída no afecta el sistema), o en cascada (si cae, arrastra a quien depende de él — el temido SPOF).

El problema clásico es una arquitectura donde la base de datos es un dominio en cascada dentro de una sola AZ, en una sola región. Si esa AZ tiene problemas, caes completo. La estrategia multi-región resuelve esto añadiendo un nivel más en la jerarquía de dominios, pero también introduce nuevas preguntas sobre consistencia y latencia de replicación que hay que responder explícitamente.

Las capas de una arquitectura multi-región

Pensar en capas ayuda a no perderse. Cada capa tiene sus propias decisiones y sus propios servicios.

Capa de redes. El CDN entrega contenido global con acceso seguro y rápido — CloudFront es el componente natural aquí en AWS. El DNS, específicamente Route 53, es quien realmente orquesta el tráfico entre regiones: puedes rutear por latencia, por failover, por geolocalización o con políticas ponderadas. Una buena estrategia de DNS hace más diferencia de lo que la gente espera — es literalmente el primer punto de decisión que toca cada request de usuario. Las redes internas entre regiones deben estar interconectadas y planificadas desde el inicio, no como un afterthought.

Capa de cómputo. Los servicios deben ser modulares, organizados por dominio de negocio y escalables bajo demanda. La elección entre Lambda, EC2, ECS o Kubernetes depende del caso de uso — no hay respuesta genérica, y lo que sí aplica siempre es que la capa de cómputo debe poder replicarse o levantarse en otra región sin fricción manual.

Capa de aplicación. Aquí hay un principio que marca la diferencia: la aplicación debe ser agnóstica a la región. Eso implica configuración externalizada, procesos sin estado (stateless) y secretos administrables. Un ejemplo concreto: leer el region_name desde una variable en lugar de hardcodearlo en el código. Suena básico y sin embargo es donde se rompen más arquitecturas multi-región en la práctica.

Capa de datos. Esta es la más compleja. Antes de elegir un servicio hay que identificar los patrones de acceso, el tipo de almacenamiento (bloque, archivo u objeto), el costo de replicación y dónde están los usuarios. AWS tiene soporte de replicación cross-region en DynamoDB, RDS Aurora, RDS estándar, S3, ElastiCache y DocumentDB. Cada uno tiene sus propias implicaciones de consistencia eventual vs. consistencia fuerte que hay que entender antes de decidir.

Capa de seguridad, identidad y acceso. IAM es global, lo cual simplifica la gestión de usuarios, roles y grupos. KMS permite crear llaves con capacidad multi-región. Secrets Manager puede replicar secretos en regiones secundarias — y aquí hay un detalle importante de Terraform: cuando configuras un aws_secretsmanager_secret con un bloque replica, la región secundaria se sincroniza automáticamente. Parece trivial hasta que lo necesitas en un failover real.

Monitoreo: no es opcional, es parte de la arquitectura

Una arquitectura multi-región sin observabilidad centralizada es básicamente una caja negra distribuida. CloudWatch, Config, GuardDuty y CloudTrail son servicios regionales, pero servicios como Security Hub y CloudTrail soportan agregados multi-región, lo que permite tener una vista unificada de eventos de seguridad sin tener que revisar consola por consola.

Hay un punto importante aquí: una estrategia de monitoreo requiere varias iteraciones. No sale perfecta a la primera. Herramientas como Amazon DevOps Guru ayudan a identificar comportamientos anómalos, sugerir mejoras de configuración y alertar sobre fallos críticos — complementan bien el stack base de observabilidad.

Despliegue: IaC o no escala

En arquitecturas multi-región, el despliegue manual no es una opción viable a largo plazo. Infraestructura como código (Terraform, CDK, CloudFormation) no es solo una buena práctica — es lo que permite recrear un entorno completo en otra región en minutos en lugar de días. El control de cambios debe ser granular: por cuenta, por ambiente y por región. IAM debe seguir el principio de mínimo privilegio, y los fallos deben estar controlados — es decir, un error en el despliegue de una región no debe tumbar las otras.

Un tip práctico: las nuevas regiones también funcionan muy bien como sandbox para validar nuevas funcionalidades o para simular desastres antes de que lleguen solos.

Lo que realmente hay que considerar antes de empezar

Multi-región no es gratis ni en costo ni en complejidad operacional. El operational overhead es real: cada recurso que existe en una región ahora existe en dos o más, con todo lo que eso implica en mantenimiento, monitoreo y actualizaciones. Los costos de transferencia de datos entre regiones también se acumulan rápido si no se modelan desde el inicio.

Antes de empezar, vale la pena hacer un ejercicio de planeación con una matriz de prioridad, esfuerzo, complejidad y dependencias — algo similar al Método Eisenhower. No todo tiene que regionalizarse al mismo tiempo ni con la misma urgencia. Siempre hay componentes que son candidatos naturales para regionalizarse primero (típicamente los más críticos y con menor complejidad de replicación) y otros que pueden esperar.

Un Well Architected Review es un buen punto de partida para hacer ese inventario con una metodología estructurada.

La arquitectura evoluciona

El estado final de una arquitectura multi-región en AWS se ve algo así: el usuario llega a Route 53, que rutea al CloudFront más cercano, que a su vez dirige el tráfico a la región correspondiente — donde viven el API Gateway, las Lambdas y la base de datos Aurora replicada. Todo gestionado por certificados en ACM y con tráfico distribuido por políticas de latencia o failover en DNS.

Llegar ahí no pasa de un día para otro. Llega por iteraciones, con IaC como columna vertebral y con una estrategia de DNS que desde el primer día esté pensada para escalar.

Multi-región no es un problema de servicios, es un problema de diseño. Los servicios de AWS están listos. La pregunta es si tu arquitectura, tu código y tus procesos también lo están.

Multi-Stage Continuous Delivery

Franchesco Romero — Thu, 02 Apr 2026 21:59:47 +0000

Multi-Stage Continuous Delivery - Speaker Deck

speakerdeck.com

El problema con los pipelines tradicionales

El concepto de Multi-Stage CD es sencillo: llevas código a prod en varias iteraciones y a través de diferentes ambientes — dev, staging, prod — con fases bien definidas: build, prepare, deploy, test, notify, rollback. Suena limpio. Y en papel, lo es.

El problema es la realidad. Según el State of DevOps Report 2020, el 95% del tiempo se va en mantenimiento de pipelines, el 80% en tareas manuales, y el 90% en remediación también manual. Nadie escribe esas métricas en su README, pero todos las vivimos.

Los retos concretos son tres y son los de siempre: la disponibilidad de ambientes (el clásico "no le muevan a dev que estoy probando algo"), satisfacer dependencias externas correctamente — JS, Python, AWS, lo que sea — y los ambientes con candado cuando hay un bug en prod y todo se paraliza. A eso le sumas llegada lenta a producción, más de siete herramientas involucradas en el proceso, y pipelines distintos para web, API y mobile que cada quien personalizó a su manera. El resultado es un Frankenstein difícil de mantener para cualquier persona del equipo.

Lo que realmente se necesita no es magia: capacidad de poner ambientes en cuarentena, dependencias siempre disponibles y seguras, configuración que realmente funcione, y despliegues validados con tests, métricas de performance y SLOs/SLIs bien definidos.

Keptn: un control plane para gobernarlos a todos

La solución que propongo es Keptn — y el título de esta sección es intencional. Keptn es una plataforma open source de orquestamiento que automatiza la configuración y provee en un solo control plane todo lo que normalmente está disperso: monitoreo, despliegue, remediación y resiliencia.

Lo que lo hace diferente es su enfoque declarativo y orientado a GitOps. Defines tus ambientes y estrategias en un archivo shipyard.yaml y Keptn se encarga de la orquestación basada en eventos. No necesitas escribir la lógica de coordinación entre herramientas — eso ya está resuelto.

Desde el punto de vista de plataforma, Keptn entrega progressive delivery, automatización de SRE, auto-remediación y rollback, y una configuración codificable e independiente de herramientas. Pero la parte más importante: mantiene conectividad con las herramientas que ya tienes — JMeter, Argo, Jenkins, Helm, lo que ya está corriendo en tu stack.

Un beneficio que no es obvio a primera vista: los pipelines tradicionales dejan de ser necesarios. Keptn reemplaza esa necesidad con fases dedicadas y orquestamiento event-driven. Tienes estrategias out-of-the-box como Blue/Green y Canary, más observabilidad integrada en el proceso con auditabilidad y trazabilidad completas.

Cómo funciona por dentro

El modelo mental es el siguiente: Keptn expone servicios a los cuales las herramientas se suscriben por medio de integraciones. Los eventos de Keptn se traducen a llamadas API hacia y desde esas herramientas.

En la práctica: Keptn crea un evento y lo distribuye a cualquier servicio que esté escuchando — por ejemplo, sh.keptn.event.hello-world.triggered. El Job Executor Service (JES) detecta el evento, busca la configuración en el YAML correspondiente y ejecuta el contenedor. Una vez que termina, el JES envía de vuelta un par de eventos .started y .finished. Keptn los recibe, sabe que la tarea está completa y avanza en la secuencia. Simple, trazable, predecible.

El ecosistema de integraciones es amplio. Para despliegue: Argo, Jenkins, CircleCI. Para observabilidad: Prometheus, Grafana, Splunk. Para testing: JMeter, Selenium, Artillery. Para notificaciones: Slack, webhooks, Tekton. Para automatización: Ansible, webhooks, AWS Lambda. La idea es clara — Keptn maneja la orquestación, las tareas y la ejecución; nosotros decidimos las herramientas.

Por qué esto importa frente a pipelines tradicionales

La comparación es directa. Los pipelines tradicionales sufren de falta de separación de responsabilidades, código lleno de dependencias y personalizaciones ad hoc, y dificultad para incorporar herramientas específicas sin romper todo. Keptn resuelve esto con fases dedicadas y orquestamiento basado en eventos, interoperabilidad a través de abstracciones bien definidas, y flexibilidad real para cambiar herramientas sin reescribir la lógica de entrega.

Próximos pasos: quality gates y progressive delivery

Una vez que el flujo básico está corriendo, los casos de uso avanzados son los que realmente cambian el juego. Los Quality Gates basados en SLI/SLO permiten que un despliegue sólo avance si cumple criterios medibles — por ejemplo, que el porcentaje de éxito de probes sea mayor al 95%, o que la duración de respuesta sea menor a 200ms. El score total determina si el pipeline pasa o emite una advertencia.

El Progressive Delivery lleva esto un paso más lejos: defines un flujo que va de dev a hardening a production, con estrategias blue/green en los ambientes de mayor criticidad y remediación automatizada en prod. Keptn evalúa quality gates entre cada etapa y sólo promueve si los números lo justifican.

El punto de todo esto no es adoptar una herramienta más por el gusto de hacerlo. Es reconocer que los pipelines monolíticos tienen un techo bajo, y que un modelo orientado a eventos con separación clara de responsabilidades escala mucho mejor — tanto en complejidad técnica como en tamaño de equipo.

Si quieres profundizar, el punto de partida es keptn.sh y los recursos de la comunidad en keptn.sh/resources/slides.

Optimización de costos para transacciones de alto volumen

Franchesco Romero — Thu, 02 Apr 2026 21:51:48 +0000

Optimización de costos para transacciones de alto volumen - Speaker Deck

speakerdeck.com

Optimización de Costos para Transacciones de Alto Volumen en AWS

Cuando se habla de optimización de costos en AWS, la conversación suele ir a los mismos lugares de siempre: Reserved Instances, Savings Plans, apagar recursos que no usas. Todo eso está bien y deberías hacerlo, pero hay un nivel más profundo que la mayoría de los equipos no toca — las decisiones de arquitectura y tecnología que generan costos innecesarios a escala sin que nadie se dé cuenta. Este post va sobre eso.

La economía oculta de las API calls

En arquitecturas serverless, cada llamada API tiene un costo. Eso parece obvio, pero las implicaciones no siempre son visibles cuando estás diseñando el sistema.

El patrón más común que genera costo silencioso es el polling. Imagina una aplicación que consulta un endpoint REST cada 5 segundos para verificar si hay nuevas órdenes en DynamoDB. A volumen bajo nadie lo nota. A volumen alto, estás pagando por miles de requests a API Gateway y Lambda que en su mayoría regresan vacío. La corrección es dejar de preguntar y empezar a escuchar: DynamoDB Streams detecta los cambios en la tabla y los envía a EventBridge, que filtra y transforma el evento antes de disparar el downstream — SNS, Step Functions, WebSockets. Cero polling, costo proporcional al trabajo real.

Otro patrón costoso es usar Lambda para cada operación que pasa por API Gateway. Si tienes un frontend enviando datos JSON que necesitan ser validados y escritos en DynamoDB, el reflejo natural es meter una Lambda en el medio. El problema es que cada invocación tiene costo. API Gateway tiene Mapping Templates que pueden hacer validaciones y transformaciones de request sin necesidad de invocar ninguna función. Para operaciones simples y de alto volumen, eliminar esa Lambda puede significar cientos de miles de invocaciones menos por mes.

El tercer caso tiene que ver con los límites internos de AWS. Cuando una aplicación escribe a DynamoDB a alta velocidad y alcanza el límite de Write Capacity Units, AWS aplica backoff exponencial y genera reintentos automáticos — que también cuestan. Meter SQS como buffer entre la aplicación y DynamoDB nivela el throughput y elimina esos reintentos, convirtiendo un patrón de escritura caótico en uno predecible y controlable.

Data transfer: el costo que nadie presupuesta

La transferencia de datos en AWS tiene una particularidad: es casi invisible en el diseño inicial y muy visible en la factura a fin de mes.

El ejemplo más costoso y fácil de corregir es usar NAT Gateway para que instancias en subnets privadas accedan a S3. NAT Gateway cobra por procesamiento de datos — a $0.045 por GB, 5TB al mes son $225 adicionales que no agregan ningún valor técnico. La solución es un VPC Endpoint para S3: el tráfico fluye directamente dentro de la red de AWS sin pasar por NAT, sin costo por transferencia. Es una de las optimizaciones con mejor ratio esfuerzo/impacto que existen.

Para APIs con alto tráfico de lectura, CloudFront delante de API Gateway puede eliminar la gran mayoría de invocaciones a Lambda. Si configuras CloudFront para cachear respuestas comunes por 5 minutos, todo ese tráfico repetido deja de llegar al backend. Para catálogos de productos, configuraciones, datos de referencia — el impacto puede ser dramático.

El caso de GenAI agrega una dimensión nueva. Si tienes un chatbot en AWS que manda cada query a un modelo externo como OpenAI, estás pagando transferencia de datos de salida en cada request. Mover el modelo a Amazon Bedrock o SageMaker dentro de AWS no solo elimina esa transferencia — también te da más control sobre latencia, disponibilidad y costos por token.

La economía del almacenamiento

El formato de compresión que usas para tus datos puede parecer un detalle técnico menor. En cargas de análisis a escala, no lo es. GZIP es el default en muchos pipelines de Redshift, EMR y Glue, pero tiene latencia de descompresión alta y peor ratio de compresión comparado con alternativas más modernas. Zstandard en nivel 3 ofrece mayor eficiencia tanto de almacenamiento como de procesamiento, con reducciones de más de un 30% en tamaño. Para 50TB de logs de transacciones, ese 30% es dinero real.

El zero-copy data sharing es otro concepto que vale la pena entender. El patrón ineficiente es copiar datos entre cuentas de AWS para que cada equipo tenga su propia copia en S3. Cada copia es storage adicional, cada sincronización es transferencia. Con AWS Lake Formation y Glue Catalog Cross-Account, puedes dar acceso a las mismas tablas registradas a múltiples cuentas sin mover un solo byte. Los datos viven en un lugar, el acceso se gestiona con permisos.

Computación selectiva: elegir bien el tipo de recurso

Aquí hay una distinción que muchos equipos no hacen: no todos los workloads tienen el mismo cuello de botella. Algunos son CPU-intensivos, otros son memory-bound, otros son IO-bound. Elegir la familia de instancia equivocada significa pagar por recursos que no estás usando.

Un ejemplo concreto: una base de datos MySQL en RDS con instancias t3.medium que tiene la RAM llena y hace swapping a disco. El problema no es CPU — es memoria. La solución no es subir a una instancia con más CPU, es cambiar a una familia memory-optimized. Las instancias R6g con Graviton2 ofrecen 50% más memoria por dólar que T3. Para Elasticsearch con alto uso de IOPS donde EBS gp3 ya es el cuello de botella, instancias I4i con almacenamiento NVMe local reducen la latencia de consultas en un 60%.

En Lambda, la relación memoria-CPU tiene una implicación de costos contraintuitiva. Con 128MB de RAM, una función de procesamiento de imágenes puede tardar 6 segundos. Con 1024MB tiene acceso a una vCPU completa y la misma operación tarda 0.8 segundos — 7 veces más rápida. Lambda Power Tuning existe para encontrar el punto óptimo entre costo por ejecución y tiempo de ejecución, y el resultado frecuentemente sorprende: más memoria puede ser más barato.

En Kubernetes, el costo escala con el número de nodos, y el número de nodos escala con el número de pods. Si cada microservicio tiene su propio pod con límites de CPU y memoria dedicados, terminas con mucha capacidad reservada que en promedio está subutilizada. Consolidar servicios relacionados en pods multi-tenant reduce el número total de nodos necesarios y mejora la utilización del clúster.

Estrategias de bases de datos

Aurora tiene una característica que justifica su adopción para cargas intensivas en I/O: Aurora I/O-Optimized elimina el cobro por operaciones de lectura y escritura, cambiando el modelo de precio a uno más predecible basado en capacidad. Si tienes un workload con miles de IOPS, la diferencia puede ser sustancial. Combinado con auto-tiering para mover datos históricos a almacenamiento más barato y Aurora Backtrack para reducir snapshots innecesarios, el costo total de una instancia de 5TB puede bajar considerablemente.

Para logs de transacciones en PostgreSQL que crecen a millones de registros con el tiempo, la solución no es escalar la instancia — es particionar los datos por tiempo. En lugar de una tabla gigante donde las consultas escanean todo el historial, particiones mensuales o diarias limitan el scope de cada query al período relevante. Amazon Timestream también es una alternativa cuando el patrón de acceso es fundamentalmente time-series.

Con DynamoDB a escala, TTL es una herramienta de costo que se subestima. Los ítems expirados se eliminan automáticamente sin consumir Write Capacity Units, lo que mantiene la tabla limpia sin operaciones de borrado explícitas. DAX como capa de caché elimina lecturas repetidas a la tabla principal y DynamoDB Streams permite reaccionar a cambios sin polling — ambos ya cubiertos en la sección de API calls.

Los anti-patterns que hay que evitar

Tan importante como saber qué optimizar es saber qué no hacer. Over-engineering en arquitecturas event-centric es frecuente: agregar capas de EventBridge, SNS y SQS a flujos que podrían ser síncronos simples, creando complejidad operacional por ahorros marginales que nunca se materializan.

El mito de que serverless siempre es más económico que servidores es exactamente eso: un mito. Para cargas con throughput constante y predecible, un servicio administrado de contenedores o incluso instancias reservadas pueden salir más baratos que pagar por invocación a escala. El modelo correcto depende del patrón de tráfico.

Los logs sin filtrar son otro agujero silencioso. Loggear todo en CloudWatch Logs a nivel DEBUG en producción, sin retention policies, sin filtros, genera costos de ingesta y almacenamiento que crecen con el tráfico. Filtrar a nivel del source, definir retention apropiado y usar Log Insights solo cuando se necesita mantiene eso bajo control.

La conclusión más importante es también la más sencilla: la optimización no es un proyecto con fecha de inicio y fin, es una práctica continua. Las estrategias no convencionales que van más allá de Reserved Instances y right-sizing pueden aportar entre un 15-30% adicional de ahorro. Pero solo si el equipo tiene cultura de cost awareness integrada desde el diseño, no como una corrección posterior.

Optimizando Cargas de Trabajo Serverless Técnicas para mejorar Rendimiento y Eficiencia

Franchesco Romero — Thu, 02 Apr 2026 21:19:45 +0000

Optimizando Cargas de Trabajo en Lambda - Speaker Deck

speakerdeck.com

Este post va sobre las técnicas que realmente mueven la aguja cuando estás buscando rendimiento y eficiencia en Lambda.

Cómo está construido lo que estás ejecutando

Lambda tiene una arquitectura en capas que vale la pena entender antes de optimizar cualquier cosa: tu función vive dentro de un Language Runtime, que a su vez corre en un Execution Environment, administrado por el Lambda Service sobre un Compute Substrate. Cada capa tiene implicaciones en cómo se comporta tu función al arrancar y durante la ejecución.

Dos mecanismos que se aprovechan bien una vez que entiendes esto son las Layers y las Extensions. Las capas te permiten separar tu código de función de sus dependencias y recursos compartidos — librerías, SDKs, utilerías comunes — y reutilizarlos en múltiples funciones sin empaquetar lo mismo en cada deployment. Las extensiones, por su parte, se integran en el ciclo de vida de la invocación para conectar Lambda con herramientas de monitoreo, seguridad y observabilidad, corriendo en paralelo al runtime sin modificar el código de tu función.

El problema de los Cold Starts

Si hay un tema que aparece en todas las conversaciones sobre Lambda es este. Un cold start ocurre cuando AWS necesita provisionar un nuevo contexto de ejecución — descarga el código, levanta el entorno, inicializa el runtime, y luego ejecuta tu función. Esto pasa con cambios de código, durante scale-up, en rebalanceos de AZs, o después de fallos.

El impacto varía bastante por runtime. Python y JavaScript tienen cold starts en el rango de 200-500ms. Java y Docker pueden llegar fácilmente al segundo y medio. No es lo mismo si tienes una API interactiva donde el usuario espera la respuesta, que un pipeline batch asíncrono donde nadie nota 800ms extra.

La estrategia más simple para mitigarlo es el warmup con eventos de CloudWatch o EventBridge que disparan la función cada X minutos para mantenerla activa. Funciona, pero tiene sus trade-offs: es periódico, no puedes controlar qué instancias específicas se calientan, y a escala puede tener un costo no despreciable. Haz los números: una sola función ejecutándose cada 5 minutos cuesta alrededor de $0.18 al mes. Diez funciones: $14.58 más costos de CloudWatch. No es dramático, pero tampoco es gratis.

La alternativa más robusta es Provisioned Concurrency: le dices a Lambda cuántos entornos de ejecución quieres inicializados y listos en todo momento. Por cada unidad de simultaneidad aprovisionada se mantienen mínimo dos entornos en AZs separadas, lo que también da alta disponibilidad. El contra es que pagas por esa capacidad aunque no la uses, y hay restricciones importantes: no funciona con $LATEST ni con Lambda@Edge. Úsalo con inteligencia — tiene más sentido en runtimes de inicio lento como Java, y puedes combinarlo con Application Auto Scaling para ajustar la capacidad según patrones de tráfico.

Para Java específicamente, SnapStart es un game changer: toma una snapshot del estado inicializado de la función y la restaura en invocaciones posteriores, logrando hasta 10x mejora en tiempo de arranque sin cambios en el código. Disponible desde la consola, SAM y CDK.

Vale mencionar también LLRT (Low Latency Runtime) — un runtime JavaScript liviano escrito en Rust que AWS Labs lanzó como experimental. Ofrece inicio hasta 10x más rápido y costo hasta 2x menor comparado con el runtime de Node.js estándar. Si estás en JavaScript y los cold starts te están afectando, vale la pena explorarlo.

Right-sizing y optimización de costos

Más memoria no siempre significa más costo — en Lambda, memoria y CPU están acoplados, así que a veces asignar más RAM resulta en ejecuciones más rápidas que al final cuestan lo mismo o menos. El problema es que nadie sabe exactamente cuánta memoria necesita una función sin medirlo.

Para esto existe AWS Lambda Power Tuning, una State Machine de Step Functions que ejecuta tu función con diferentes configuraciones de memoria, mide duración y costo, y te da una visualización clara del trade-off. La diferencia entre la configuración óptima para costo (1536MB en el ejemplo de la presentación) vs. la óptima para velocidad (3008MB) puede ser significativa, y depende completamente de tu workload específico.

Otros recursos útiles para right-sizing son AWS Compute Optimizer, Lambda Insights, y DevOps Guru, que pueden darte recomendaciones basadas en patrones de uso histórico.

Si tu workload tolera migrar a arm64 (Graviton2), el ahorro en precio/performance es aproximadamente un 34% frente a x86. La migración no es siempre trivial — lenguajes compilados y algunos containers requieren adaptaciones — pero el beneficio es real y verificable con Lambda Power Tuning comparando ambas arquitecturas. Los Compute Savings Plans también aplican a Lambda y pueden dar hasta un 17% adicional de ahorro sobre demanda.

Optimizaciones que están en tu control

Hay cosas que AWS optimiza por ti (descarga del código, setup del entorno) y cosas que dependen de ti (init code y handler code). La mayor palanca que tienes está en mantener tus funciones ligeras: dependencias mínimas, frameworks más pequeños, sin código muerto, y empaquetado en un único archivo minificado. El tamaño del ZIP afecta directamente cuánto tarda Lambda en descargar y cargar tu función.

Lazy-loading es otra práctica que marca diferencia: en lugar de importar todo al inicio del módulo, carga las dependencias solo cuando realmente se necesitan. El código de la presentación lo ilustra bien tanto en JavaScript como en Python — inicializas el cliente de DynamoDB o S3 dentro del handler, condicionado a si ya está inicializado, y lo reutilizas en invocaciones posteriores dentro del mismo contexto de ejecución.

Para bases de datos relacionales, si estás llamando RDS desde Lambda, RDS Proxy resuelve el problema de agotamiento de conexiones que ocurre cuando Lambda escala agresivamente. Agrupación de conexiones, mayor disponibilidad y caché de queries — sin cambios en el código de la función.

Si tu función sirve respuestas que no cambian con cada invocación, configurar caché a nivel de API Gateway o CloudFront puede eliminar completamente la invocación de Lambda para esas peticiones. Para algunos patrones esto es la optimización más impactante de todas.

Métricas que realmente importan

Medir promedios de latencia es engañoso. Lo que importa es el percentil p95 o p99 — el rendimiento que experimentan el 5% o el 1% más lento de tus usuarios. Un promedio de 200ms con un p99 de 4 segundos es una función con problemas serios que el promedio oculta.

AWS X-Ray es la herramienta para esto: tracing end-to-end de requests, service map de tu aplicación, y visibilidad sobre exactamente dónde se producen los cuellos de botella. Un Tracing: Active en tu template de SAM o CDK y ya tienes trazas automáticas de Lambda y los servicios downstream.

El punto que más se subestima

Lambda no debería ser el default para absolutamente todo. Hay operaciones donde otros servicios hacen el trabajo mejor y más barato sin invocar ninguna función. Orquestación compleja de workflows: Step Functions. Filtrado de mensajes antes de procesarlos: SNS con filter policies. Scheduling de tareas: EventBridge Scheduler. Integrar Lambda innecesariamente en esos flujos agrega latencia y costo sin valor real.

Optimizar Lambda no es una sola cosa — es la suma de decisiones en configuración, código, arquitectura y monitoreo. El punto de partida es medir con X-Ray, ajustar con Lambda Power Tuning, y construir con las restricciones del caso de uso en mente, no con el toolset que conoces mejor.

DEV Community: Franchesco Romero

Pooling contra una t3.micro, el día que se reventó...RDS Proxy es la salida?

TL;DR

El pool, y la cuenta escondida adentro de él

El día que se reventó

Mitigaciones que no son dimensionar

El hilo trampa

El techo de verdad: el autoescalado está atado a las conexiones

RDS Proxy: la válvula de escape, y la trampa de asyncpg

La economía del proxy

Lo que te diría

500 portadas distintas de un solo modelo de $0.04: arte de portada con IA, consistente con la marca, en un generador económico

Arquitectura

Fase 0, el bug del paso directo

Fase 1, un estilo de la casa es un envoltorio de prompt más un prompt negativo

Fase 2, nunca dejes que el modelo escriba texto; superpón el logo tú mismo

Fase 3, Core fusiona sujetos; diseña alrededor de eso

El callejón sin salida que vale la pena documentar: fusión cálido + frío

Fases 4–6, diseñar la variedad, porque la semilla no lo va a hacer

La economía

La trampa de región

Lo que un modelo económico no puede hacer (medido, no adivinado)

Lo que te diría

SEO en 2026, parte 2: la captura rankea — ahora haz que convierta

TL;DR

El punto de partida

Fase 1: la trampa del CTA solo-en-la-SPA

Fase 2: un CTA construido con los datos de la propia página

Fase 3: editable sin re despliegue

Fase 4: el espejo en la SPA, anónimo vs autenticado

Fase 5: el despliegue que des indexa tu página

Fase 6: recuperación del lado del cliente para la ventana de propagación

El resultado

Lo que NO ayudó

Lecciones

SEO en 2026, cuando la mitad de tu tráfico llega por ChatGPT

SEO en 2026, cuando la mitad de tu tráfico llega por ChatGPT

TL;DR

El punto de partida

elchesco / seo-evolution-2026

Code companion — SEO evolution 2026 post

Code companion — SEO evolution 2026 post

Suggested reading order

Notes

Fase 1: JSON-LD de schema.org + hreflang en el envoltorio PageMeta

Fase 2: llms.txt + política explícita de rastreadores de IA

Fase 3: mapa de sitio dinámico

Fase 4: IndexNow al publicar

Fase 5: monitoreo de usuarios reales con Web Vitals

Fase 6: capturas de HTML por ruta sin Puppeteer

El resultado

Lo que NO ayudó

Qué sí ayudaría a futuro (en orden de palanca)

Lecciones

Cuatro intentos para que una tarea programada se ejecute exactamente una vez: una evolución

TL;DR

elchesco / fast-api-locking-evolution

Four attempts to make a scheduled job run exactly once: an evolution

Code companion — locking evolution post

Suggested reading order

Notes

El incidente

Intento 1: bloqueo por ciclo

Intento 2: centinela adentro de la tarea

Intento 3: claim de worker_runs

Cómo se ve la secuencia con las tres capas

¿Qué pasa si el trabajo falla a la mitad?

En este punto todo funciona. ¿Por qué seguir?

Intento 4: separar el "cuándo" del "dónde"

Qué se simplifica

Lo que NO ayudó

Lecciones

Coordinar deploys de frontend y backend sin orquestado, usando Github Actions

El Setup

elchesco / github-actions-combined-deploy-with-no-orchestrator

Coordinating frontend and backend deploys without an orchestrator:

Code companion — frontend/backend deploy coordination post

Suggested reading order

Notes

TL;DR

Fase 2: `llms.txt` + política explícita de rastreadores de IA

Intento 3: claim de `worker_runs`

Intento no. 1: instalar dependencias más rápido con `uv`

Intento no. 3: la trampa de `pytest-xdist`

Trampa 1: `DROP SCHEMA` entre workers

Trampa 2: `max_locks_per_transaction`

Trampa 3: la divergencia del `DATABASE_URL`

Trampa 4: `filelock` se cuelga

Round 6: soltar `xdist`, irse a 4 shards

Intento no. 3: la trampa de `pytest-xdist`

Trampa 1: `DROP SCHEMA` entre workers

Trampa 2: `max_locks_per_transaction`

Trampa 3: la divergencia del `DATABASE_URL`

Trampa 4: `filelock` se cuelga

Round 6: soltar `xdist`, irse a 4 shards