Actualizar Airflow deja de ser una tarea rutinaria en cuanto tus DAGs participan en ingresos, informes regulatorios, SLA internos o integraciones que sostienen operaciones críticas. En ese contexto, cambiar de versión no es un detalle de plataforma. Es una decisión de riesgo operativo. Si el scheduler degrada, si un provider deja de comportarse como esperas o si un script heredado rompe tras una migración de metadatos, el coste aparece muy rápido en forma de reprocesos, tiempo senior consumido en diagnóstico y menos confianza en la plataforma.
Por eso conviene leer Airflow 3 con más cuidado que una simple actualización de paquetes. Lo que cambia no es solo la compatibilidad de algunas dependencias. También cambian las fronteras entre componentes, la forma recomendada de escribir tareas y el margen real que tiene el código heredado para seguir funcionando sin sorpresas. Esta guía ordena la migración desde un criterio operativo: qué revisar primero, dónde suele concentrarse el riesgo y qué evidencias deberías exigir antes de mover carga real. El objetivo no es llegar antes a Airflow 3. Es salir del cambio con una base más gobernable y con una reversión que no dependa de la improvisación.
El problema real está en el acoplamiento heredado, no en actualizar dependencias
Muchas migraciones de Airflow se complican por un error de diagnóstico bastante común. El equipo mira la versión de Python, revisa requirements.txt y asume que el riesgo está localizado en la instalación de paquetes. Después descubre que el problema estaba en otro sitio: DAGs que importan módulos internos, operadores propios que usan objetos no públicos, automatizaciones que escriben directamente en la base de metadatos o despliegues que no contemplan cambios de configuración y de esquema.
En producción, esas dependencias ocultas son más peligrosas que una incompatibilidad explícita. Una incompatibilidad visible se detecta pronto y suele tener un responsable claro. El acoplamiento heredado, en cambio, aparece tarde. El entorno arranca, varios DAGs cargan sin errores y la sensación inicial es que la migración ha salido bien. El problema llega cuando entra carga real, cuando toca reintentar tareas históricas o cuando un provider ejerce una ruta del código que nadie había probado durante la ventana de cambio.
Casi siempre, los bloqueos serios se agrupan en tres frentes. El primero es la compatibilidad efectiva del código de DAGs, plugins y extensiones, sobre todo cuando dependen de APIs internas o de patrones antiguos. El segundo es la frontera arquitectónica, porque Airflow 3 refuerza una separación más estricta entre ejecución de tareas y acceso a metadatos. El tercero es la reversión: sin copia de seguridad probada, sin criterios de parada y sin una forma limpia de volver atrás, cualquier incidencia cuesta más de lo necesario.
La consecuencia práctica es sencilla. Si uno de esos tres frentes queda fuera del plan, puedes completar la migración y, aun así, empeorar la operación. El sistema parece actualizado, pero la plataforma queda más frágil, más opaca y más dependiente de unas pocas personas que entienden los atajos heredados.
Airflow 3 endurece las fronteras entre ejecución, metadatos e integraciones
La lectura útil de Airflow 3 no es que "trae funciones nuevas". La señal importante es que refuerza límites que en muchos despliegues históricos estaban difusos. En términos operativos, esto implica que la ejecución de tareas no debería depender del acceso directo a la base de metadatos, y que una integración crítica no debería descansar en comportamientos internos que no forman parte de una interfaz soportada.
Ese cambio importa por una razón muy concreta. Cuanto más depende tu operación de detalles internos, más cara resulta cada migración futura y más difícil es gobernar el sistema con previsibilidad. Airflow 3 empuja en la dirección contraria. El Task SDK gana peso como camino recomendado para escribir tareas alineadas con la arquitectura que el proyecto quiere estabilizar. El servidor API pasa a ser una frontera más clara para automatización e integración. Y el procesador de DAGs separado cambia dónde aparecen algunos cuellos de botella y cómo conviene observarlos.
Nada de esto obliga a reescribir todos los DAGs de inmediato. Sí obliga a distinguir con disciplina qué forma parte de una interfaz pública y qué solo ha funcionado hasta ahora porque el acoplamiento heredado todavía no había cobrado factura.
| Patrón heredado | Por qué se vuelve frágil en Airflow 3 | Enfoque más estable |
|---|---|---|
| Scripts que leen o modifican tablas de metadatos directamente | Dependen del esquema y de comportamientos internos, y eso los vuelve vulnerables tras airflow db migrate o cambios de contrato implícitos | Mover la automatización a interfaces soportadas y reducir el acceso directo a la base |
| Operadores, hooks o plugins que importan módulos internos | Pueden romperse con cambios de estructura o con contratos que nunca fueron públicos | Reescribir contra APIs públicas y revisar dependencias antes del corte |
| Lógica de negocio pesada dentro del archivo del DAG | Aumenta el tiempo de carga, complica las pruebas y mezcla definición del flujo con ejecución | Extraer lógica a módulos mantenibles y adoptar el Task SDK donde reduzca riesgo |
También conviene poner en contexto las capacidades más visibles de la rama 3.x, como el versionado de DAGs o las mejoras en reprocesos históricos. Son útiles, pero rara vez justifican por sí solas una migración precipitada. Si tu plataforma es crítica, la razón para migrar no debería ser "tener lo nuevo", sino reducir deuda operativa y acercarte a una arquitectura más gobernable.
El orden del cambio define la estabilidad del primer mes
En una plataforma de orquestación, el orden importa más que la velocidad. Lo que protege la primera semana tras el cambio no es terminar antes, sino tomar decisiones en una secuencia que mantenga reversible cada paso importante.
-
Fija una referencia operativa en Airflow 2.x.
Antes de tocar nada, necesitas saber cómo se comporta tu entorno cuando está sano. Eso incluye tiempos de carga de DAGs, tareas en cola, latencia desde que una tarea entra en cola hasta que arranca, tasa de fallos y cualquier métrica que ya uses para vigilar el scheduler y los ejecutores. Sin esa referencia, cualquier discusión posterior sobre degradación se convierte en opinión. -
Cierra la compatibilidad de Python, de los
providersy del entorno de ejecución.
El riesgo no está solo enapache-airflow. También está en losprovidersque conectan con tus sistemas externos, en bibliotecas del sistema, en imágenes base y en cualquier restricción del entorno donde despliegas. Si tu plataforma ya estaba ajustada en dependencias, aquí es donde la migración se vuelve frágil. Lo que buscas en esta fase es retirar incertidumbre antes de acercarte a producción. -
Haz copia de seguridad de la base de metadatos y actualiza la configuración de forma explícita.
La documentación oficial insiste en dos pasos que conviene tomarse literalmente: copia de seguridad antes de la migración de la base de datos y actualización de configuración conairflow config updatepara absorber opciones obsoletas o renombradas. Una reversión sin copia restaurable no es una reversión. Es una esperanza. Y, en una base de metadatos crítica, eso no es un plan aceptable. -
Ejecuta una revisión estática del código de DAGs y extensiones.
Airflow recomienda apoyarse en reglas deruffpara detectar patrones incompatibles. No sustituye las pruebas, pero sí elimina una clase muy común de fallos antes de que lleguen al scheduler: importaciones rotas, uso de APIs desaconsejadas y deuda que pasa inadvertida hasta que la plataforma intenta cargarlo todo. -
Aísla el acceso directo a metadatos y las dependencias de componentes internos.
Aquí es donde suele estar el trabajo que de verdad reduce el riesgo. No hace falta reescribir toda la plataforma de una vez, pero sí localizar los scripts, plugins y operadores que dependen de SQL directo sobre metadatos, de estados manipulados a mano o de módulos internos. Cuanto antes saques ese código del camino crítico, más predecible será el cambio. -
Ensaya en preproducción con datos y presión representativos.
Que el entorno arranque no basta. En producción, lo que rompe el día a día vive en detalles que no aparecen en una prueba superficial: serialización, reintentos,pools,sensors,callbacks, concurrencia y compatibilidad real de losproviderscon sistemas externos. Si esos caminos no se ejercitan antes del corte, la migración queda validada solo en teoría. -
Diseña el corte y la reversión como un procedimiento, no como un deseo.
Antes de mover carga real, deberían estar definidos los criterios de parada, la ventana de restauración, el responsable de decidir la vuelta atrás y las señales que deben mantenerse en verde durante las primeras horas. La migración segura no es la que nunca falla. Es la que, si falla, lo hace dentro de límites controlados y con una salida clara.
Este orden no es burocracia. Es una manera de contener el coste del cambio. Cada hora senior dedicada a diagnosticar una incidencia evitable en Airflow compite con la hoja de ruta del equipo, consume margen de entrega y reduce confianza en la plataforma. Por eso merece la pena invertir antes en claridad.
El código que nadie toca suele concentrar el riesgo más caro
Cuando un equipo quiere estimar la incertidumbre real de la migración, no hace falta inventar un marco de análisis complejo. Suele bastar con localizar qué código vive fuera del camino habitual de revisión y, aun así, toca el corazón de la plataforma.
La primera superficie a inventariar son los operadores, hooks y plugins propios. En muchas organizaciones, ese código encapsula años de soluciones puntuales, integraciones urgentes y decisiones tomadas para resolver incidentes concretos. Mientras funciona, pasa desapercibido. Pero si importa módulos internos, manipula estados de tareas de manera implícita o depende de objetos no públicos, merece prioridad inmediata.
La segunda superficie son los DAGs que mezclan definición de flujo con lógica de negocio pesada. El problema aquí no es solo estético. Cuando un archivo de DAG hace demasiado, aumentan los tiempos de carga, se complica el aislamiento de errores y se vuelve más difícil separar qué pertenece a la orquestación y qué debería vivir en código de aplicación o en bibliotecas compartidas. En Airflow 3, esa claridad importa más que antes.
La tercera superficie son los scripts externos que consultan o modifican metadatos directamente para lanzar reprocesos, alterar estados o generar informes. Suelen ser invisibles para el proceso normal de revisión porque no viven junto a los DAGs y, a menudo, tampoco tienen pruebas suficientes. Son especialmente peligrosos porque afectan a la plataforma desde fuera y suelen fallar cuando más presión operativa hay.
No conviene confundir código antiguo con código estable. En Airflow, muchas veces solo significa que nadie quiere tocarlo porque el coste de entenderlo parece demasiado alto. Precisamente por eso es donde una migración se encarece. Si inventarias estas superficies y las ordenas por criticidad de negocio, el plan deja de ser difuso. Lo que parecía una migración grande se convierte en un conjunto de riesgos concretos, con responsables y con criterios de validación.
Antes del corte, estas validaciones deben estar demostradas
Antes de mover carga real o convertir el nuevo entorno en el principal, estas comprobaciones deberían estar cerradas con evidencia. Cuando Airflow gobierna procesos de producto, finanzas o cumplimiento, "parece que funciona" no es una señal suficiente.
| Área | Pregunta que debe quedar resuelta | Señal de que aún no está listo |
|---|---|---|
Compatibilidad de DAGs y providers | ¿Los DAGs cargan sin errores y los providers críticos siguen soportados en tu combinación de versiones? | Importaciones rotas, tareas que fallan al arrancar o dependencias bloqueadas |
| Metadatos y esquema | ¿Existe una copia restaurable y probada antes de ejecutar airflow db migrate? | La migración de base de datos no tiene una ruta de retorno verificada |
| Código propio | ¿Plugins, hooks y operadores han dejado de depender de componentes internos o de SQL directo sobre metadatos? | El código "funciona" solo porque aún no se ha ejercitado la ruta afectada |
Adopción del Task SDK | ¿Está claro qué piezas conviene mover ya y cuáles pueden esperar sin aumentar el riesgo? | Se mezclan patrones nuevos y heredados sin criterio técnico |
| Integraciones críticas | ¿Se han probado conexiones y efectos laterales con los sistemas que más cuesta romper? | El entorno arranca, pero los fallos aparecen al escribir en sistemas externos |
| Observabilidad | ¿Hay una referencia previa de tiempos de carga, colas, latencia de arranque y tasa de fallos? | No puedes comparar el antes y el después con datos fiables |
| Reversión | ¿Puedes volver a 2.x o detener el cambio sin perder control operativo? | El plan asume, de hecho, que la migración es irreversible |
Si esta tabla no puede cerrarse con evidencias, el problema no se resuelve con una ventana de mantenimiento más larga ni con más optimismo. Lo que falta es reducir acoplamiento, aislar mejor el cambio y definir una reversión real.
Dudas que conviene resolver antes de comprometer el cambio
¿Hay que migrar todos los DAGs al Task SDK de inmediato?
No. Forzarlo suele ser una decisión cara y, en equipos pequeños, a menudo contraproducente. La prioridad debería ser otra: identificar qué piezas dependen de componentes internos o de acceso directo a metadatos y retirar primero ese acoplamiento. El Task SDK merece prioridad en desarrollos nuevos y en refactorizaciones donde realmente reduzca riesgo. Los flujos estables que no bloquean la migración pueden esperar si eso evita una reescritura innecesaria.
¿Tiene sentido un despliegue blue/green?
A menudo sí, sobre todo cuando la carga es crítica y el coste de un fallo es alto. El despliegue blue/green reduce el alcance del impacto y mejora el control del cambio. Pero no sustituye la validación. Si ambos entornos comparten restricciones relevantes, como metadatos mal aislados o sistemas externos con efectos laterales sensibles, la sensación de seguridad puede ser mayor que la seguridad real. Ganas control sobre el cambio, no inmunidad frente a los errores.
¿Qué cambia si Airflow corre en un servicio gestionado?
El criterio técnico es el mismo, pero el calendario y el margen de maniobra pueden no serlo. Si dependes de un servicio gestionado, conviene validar primero el soporte efectivo de Airflow 3, la compatibilidad de los providers, las restricciones sobre plugins o imágenes y el nivel de control que te deja el proveedor sobre la migración de metadatos. Un servicio gestionado puede simplificar la infraestructura, pero no elimina la deuda del código ni garantiza que tus DAGs estén preparados.
¿Basta con que el scheduler arranque y cargue los DAGs?
No. Eso solo demuestra que una parte del sistema sigue en pie. Los fallos caros suelen aparecer después, cuando entra concurrencia real, cuando aumentan las colas, cuando hay que reintentar tareas, cuando actúan los callbacks o cuando los providers empiezan a interactuar con sistemas externos. En Airflow, la diferencia entre una migración aparentemente correcta y una migración realmente estable suele estar en esa capa operativa.
Fuentes primarias y documentación oficial
Lecturas relacionadas
- Plataforma de datos para analytics: confianza operativa y velocidad de decisión
- MLOps en producción: del prototipo a un sistema gobernable
- Entrenamiento y evaluación de modelos a escala: rigor antes que cómputo
- BigQuery en GCP paso a paso: alta, IAM y credenciales JSON
- Consultoría de ingeniería de datos: plataformas y pipelines
Migrar ahora solo compensa cuando el coste actual ya es visible
Si Airflow está en el camino crítico del negocio y hoy ya dependes de scripts contra metadatos, operadores acoplados a componentes internos, reprocesos manuales o cambios que nadie quiere tocar por miedo a romper algo, Airflow 3 merece prioridad. No por novedad, sino porque te obliga a corregir una arquitectura que ya te está costando dinero, tiempo senior y margen de entrega.
Si, en cambio, tu plataforma es estable, la deuda está contenida y no existe una presión operativa o regulatoria inmediata, puedes esperar y preparar mejor el terreno. En ese escenario, lo inteligente no es correr hacia la nueva versión, sino inventariar acoplamientos, fijar observabilidad y dejar lista una reversión real. La decisión correcta no es migrar antes. Es migrar cuando el cambio te devuelve control sobre la plataforma, en lugar de añadir otra capa de incertidumbre.
