Airframe

Por qué Airframe

Una vista previa para cada merge request

Los revisores deberían poder probar un cambio, no solo leerlo. Una vez que las personas correctas aprueban el merge request de un producto, la plataforma despliega una vista previa del producto en un nombre de host propio, con una base de datos propia, y la destruye en el merge, en el cierre o cuando se acaba su tiempo.

Cómo un merge request recibe su vista previa

  1. El cambio se aprueba

    El pipeline propio de un merge request ejecuta código que nadie revisó todavía, así que no tiene ninguna credencial de la nube y no despliega nada. Cuando la compuerta de aprobación aprueba el merge request de un producto, inicia las ejecuciones del ejecutor para ese commit exacto: los planes, la construcción de imágenes y la vista previa. Un producto cuyo estado en el catálogo es retiring no recibe vista previa, porque no sirve nada.

  2. El ejecutor la despliega

    La ejecución de la vista previa espera hasta 25 minutos la construcción del último commit del merge request, y se detiene si la construcción falló. Luego, con la identidad de aplicación de no producción del producto, planifica la raíz infra/eph del producto, pasa el paquete de políticas sobre el plan, le pone precio y lo aplica. La identidad de producción nunca se usa, así que una vista previa no puede tocar producción.

  3. Su propio nombre de host, sus propios datos

    La vista previa responde en <product>-eph-<iid>.<domain>.<journey>.projectairframe.dev, donde <iid> es el número del merge request, detrás del inicio de sesión único para el grupo de usuarios del producto. El enrutador de vistas previas del producto lee el número en el nombre de host y reenvía a los servicios de esa vista previa, que aceptan llamadas solo del enrutador. Por defecto, la base de datos es un sidecar de PostgreSQL en la misma revisión de Cloud Run, con datos iniciales que carga al arrancar desde los archivos del propio producto.

  4. Los revisores prueban el cambio

    El ejecutor publica una nota en el merge request con la dirección de la vista previa, su precio y cuándo vence. Los revisores la abren en un navegador, donde las cookies, las redirecciones y los enlaces funcionan como en producción, y cada señal lleva su entorno, que para una vista previa es eph-<iid>, para que los paneles del producto puedan mostrarla por separado: el golden path lo fija en el servicio de la vista previa; la puerta de enlace OTLP lo toma como la etiqueta env, y el agente de la plataforma y la puerta de enlace de registros lo derivan del nombre del servicio. Un nuevo push restablece las aprobaciones, y la siguiente aprobación aplica la misma vista previa con el nuevo commit.

  5. Desaparece en el merge, en el cierre o al vencer su tiempo de vida

    Cuando el merge request se integra o se cierra, la compuerta de aprobación inicia la ejecución de destrucción del ejecutor, que verifica por sí misma el estado del merge request, destruye la vista previa y publica una nota. Una vista previa también vence preview_ttl_hours después de su último apply, 72 salvo que la entrada del catálogo diga otra cosa. Un recolector diario destruye las vencidas y las que dejó atrás una notificación perdida o una destrucción que falló.

Un ejemplo práctico

Se aprueba el merge request 42 del producto invoicing, en el dominio billing del recorrido settle, y su entrada deja la configuración de vistas previas en sus valores por defecto. Una vista previa necesita que los proyectos del producto tengan facturación, y hoy ningún producto de la demo la tiene, así que esto es lo que pasaría; las vistas previas funcionaron en los ensayos de la plataforma en septiembre de 2026.

  • La compuerta de aprobación aprueba el commit e inicia para él los planes, la construcción de imágenes y la vista previa del ejecutor
  • Una vez que la construcción pasó, la ejecución de la vista previa planifica infra/eph con la identidad de aplicación de no producción de invoicing, verifica el plan con el paquete de políticas, le pone precio y lo aplica
  • La nota del merge request da la dirección, invoicing-eph-42.billing.settle.projectairframe.dev, el precio de la vista previa y su vencimiento, 72 horas después del apply
  • La base de datos es un sidecar de PostgreSQL que carga sus datos iniciales al arrancar; los registros, las métricas y las trazas de la vista previa llevan env eph-42
  • Un push restablece las aprobaciones; la siguiente aprobación aplica la misma vista previa con el nuevo commit y un nuevo vencimiento
  • El merge request se integra: la ejecución de destrucción elimina la vista previa, conserva su estado de Terraform vacío como registro y publica una nota

Qué lo hace cierto

Solo un cambio aprobado recibe una vista previa, y nunca con la identidad de producción.
La compuerta de aprobación inicia la ejecución de la vista previa del ejecutor solo cuando aprueba el merge request de un producto, y no para un producto en estado retiring; la ejecución aplica la raíz infra/eph del producto con la identidad de aplicación de no producción, después de que el paquete de políticas verificó el plan. El pipeline propio del merge request no tiene ninguna credencial de la nube. Como solo un cambio aprobado recibe una vista previa, alguien que solo puede abrir merge requests no puede inflar la factura.
Cada vista previa tiene su propio nombre de host, detrás del inicio de sesión único, y ninguna otra entrada.
El certificado y el registro comodín del dominio cubren cada nombre de host <product>-eph-<iid>, así que no se emite nada por vista previa. El módulo preview-substrate del golden path le da a cada producto un enrutador en su proyecto de no producción, detrás de IAP para el grupo de usuarios del producto; el enrutador lee el número del merge request en el nombre de host, y cada servicio de vista previa nombra al enrutador como su único invocador.
Una vista previa se destruye cuando su merge request termina.
La compuerta de aprobación se entera del merge o del cierre por el webhook de GitLab e inicia la ejecución de destrucción del ejecutor, que verifica por sí misma el estado del merge request y destruye con la misma identidad de no producción. El registro de cada vista previa lleva un bloqueo, así que un apply y una destrucción nunca corren a la vez, y un merge request cerrado y reabierto inicia una nueva generación, así que una destrucción tardía no puede eliminar la nueva vista previa.
Una vista previa vencida u olvidada se recoge.
preview:collect, un job del pipeline programado diario de control-plane, lista las vistas previas que según los registros del ejecutor siguen en pie, revisa el estado y el vencimiento de cada merge request, y destruye las integradas, las cerradas y las que pasaron su preview_ttl_hours (72 por defecto, como máximo 168, contadas desde el último apply), con una nota en cada merge request.
Una vista previa casi no cuesta nada mientras está inactiva, y nunca bloquea un merge.
El enrutador y los servicios de la vista previa bajan a cero, y la base de datos sidecar por defecto vive en la propia revisión del servicio, con unos 512 MiB más de memoria mientras corre; el módulo de Cloud Run del golden path ejecuta el servicio de una vista previa con una instancia como máximo. Una instancia compartida de Cloud SQL, cuando la entrada la elige, solo se puede aplicar una vez que el proyecto de no producción del producto está en la red compartida de la plataforma, y entonces cuesta unos USD 9 al mes por producto. El ejecutor le pone precio al plan de cada vista previa y lo muestra en la nota, y la verificación de costo que detiene un merge deja fuera las vistas previas.