Vistas previas: un entorno para cada merge request

Una vista previa es una copia efímera de un producto, desplegada para un merge request para que las personas que revisan un cambio puedan probarlo en un navegador antes del merge. Airframe la despliega solo cuando las personas correctas aprobaron el cambio, le da una dirección propia y la destruye cuando el merge request se integra o se cierra. Esta página explica qué contiene una vista previa, quién la despliega, cuándo desaparece y cuánto cuesta.

Qué recibe un merge request

Un merge request aprobado de un producto recibe tres cosas.

Su propio nombre de host. La dirección es <product>-eph-<iid>.<domain>.<journey>.projectairframe.dev, donde <iid> es el número del merge request. El merge request 42 de un producto llamado invoicing en el dominio billing del recorrido settle estaría en invoicing-eph-42.billing.settle.projectairframe.dev. Como una vista previa tiene un nombre de host y no una ruta bajo otro, las cookies, las redirecciones y los enlaces funcionan como en producción. Como todo nombre de host de un producto, está detrás del inicio de sesión único, y solo entra el grupo de usuarios del producto. El certificado y el registro comodín del dominio ya cubren cada vista previa, así que no se emite nada para cada una.

El enrutador de vistas previas. Cada producto tiene un pequeño servicio en su proyecto de no producción, creado por el módulo preview-substrate del golden path. Lee el número del merge request en el nombre de host y reenvía cada solicitud a los servicios de esa vista previa. Cada servicio de una vista previa acepta llamadas solo del enrutador, así que el nombre de host, con su inicio de sesión, es la única entrada.

Una base de datos. El campo preview_db de la entrada del catálogo elige cómo la obtiene una vista previa:

sidecar, el valor por defecto: un contenedor de PostgreSQL que corre junto al servicio de la vista previa en la misma revisión de Cloud Run, cargado al arrancar con los archivos .airframe/eph/ del producto. No cuesta nada mientras está inactivo y olvida sus datos cuando su instancia desaparece. El módulo de Cloud Run del golden path corre el servicio de una vista previa en una instancia como máximo, porque los datos viven en esa instancia, y el paquete de políticas advierte sobre un servicio con una base de datos así que pueda correr más.
shared: una instancia de Cloud SQL por producto, dimensionada por el campo preview_concurrency de la entrada, en la que cada vista previa recibe una base de datos propia. Necesita que el proyecto de no producción del producto esté en la red compartida de la plataforma; hasta entonces, una vista previa compartida no se puede aplicar.

Lo que contiene una vista previa lo elige el producto, en su raíz de Terraform infra/eph, compuesta con los mismos módulos que producción. El ciclo de vida a su alrededor es de la plataforma.

Quién la despliega, y cuándo

El pipeline del propio merge request nunca despliega una vista previa: ejecuta código que nadie revisó todavía, así que no tiene ninguna credencial de la nube. La vista previa viene del ejecutor, en la aprobación.

Cuando la compuerta de aprobación aprueba el merge request de un producto, inicia las ejecuciones del ejecutor para ese commit: los planes, la compilación de imágenes y la vista previa. La ejecución de la vista previa espera la compilación del último commit del merge request, hasta 25 minutos, y se detiene si la compilación falló. Luego, con la identidad de apply de no producción del producto, planifica infra/eph, pasa el paquete de políticas sobre el plan, le pone precio y lo aplica. Publica una nota en el merge request con la dirección de la vista previa y la hora en que vence.

Un nuevo push reinicia las aprobaciones del merge request. La siguiente aprobación vuelve a aplicar la misma vista previa con el nuevo commit, y así la vista previa sigue al cambio. La identidad de producción nunca se usa, así que una vista previa no puede tocar producción. Un producto cuyo estado en el catálogo es retiring no recibe vista previa, porque no sirve nada.

Cuándo se destruye

Una vista previa se destruye en el primero de tres momentos:

El merge. La compuerta se entera del merge por GitLab e inicia la ejecución de destrucción del ejecutor. El ejecutor comprueba por su cuenta que el merge request esté integrado o cerrado, destruye los recursos de la vista previa con la misma identidad de no producción y publica una nota. El estado de Terraform de la vista previa se conserva, vacío, como registro.
El cierre. Un merge request cerrado se trata de la misma forma.
El tiempo de vida. El campo preview_ttl_hours de la entrada, 72 horas salvo que la entrada diga otra cosa y como máximo 168, contadas desde el último apply de la vista previa.

El tiempo de vida, una notificación perdida y una destrucción que falló los atrapa el recolector: preview:collect, un job del pipeline programado diario del repositorio control-plane. Lista cada vista previa que según los registros del ejecutor sigue en pie, revisa el estado y el vencimiento de cada merge request, y destruye las integradas, las cerradas y las vencidas, con una nota en cada merge request.

Cada vista previa tiene un registro que guarda lo que se aplicó, y un bloqueo, para que un apply y una destrucción nunca corran al mismo tiempo. Un merge request que se cierra y se vuelve a abrir inicia una nueva generación del registro, así que una destrucción tardía no puede borrar la nueva vista previa.

Cuánto cuesta

El enrutador y los servicios de la vista previa bajan a cero, y una base de datos sidecar no cuesta nada mientras está inactiva; un servicio de vista previa en marcha lleva unos 512 MiB más de memoria para su base de datos. Una instancia compartida cuesta unos USD 9 al mes por producto mientras existe.

El ejecutor le pone precio al plan de cada vista previa y muestra la cifra en su nota. La verificación de costo que mantiene cerrado el merge por encima del presupuesto del producto deja fuera la vista previa, así que una vista previa nunca bloquea un cambio. Y como solo un cambio aprobado recibe una vista previa, alguien que solo puede abrir merge requests no puede inflar la factura.

En qué se diferencia una vista previa del sandbox

Un sandbox es una copia opcional y duradera de un producto en la versión de su rama main, con su propia instancia de Cloud SQL y un servicio siempre caliente, en <product>-sandbox.<domain>.<journey>.projectairframe.dev. Otros productos prueban contra él, y cuesta dinero todo el mes. Una vista previa contiene el cambio de un merge request, vive horas o días, y desaparece después del merge.

Ver lo que hace una vista previa

Los registros, las métricas y las trazas de una vista previa llevan la etiqueta de entorno eph-<iid>, para que los paneles del producto la muestren al elegir ese valor. El golden path fija deployment.environment con ese valor en el servicio de la vista previa, y la puerta de enlace OTLP lo toma como env, mientras que el agente de la plataforma y la puerta de enlace de registros lo derivan del nombre del servicio. Las reglas de alerta seleccionan solo producción, así que una vista previa nunca despierta a nadie. Observabilidad explica las etiquetas.

Diseñado, no construido

La prueba de humo (diseñada). El archivo .airframe/preview.yaml del producto nombra una prueba de humo y comandos para ejecutar después de la creación, y todavía nada los ejecuta. Hoy el apply espera a que la nueva revisión esté lista, y la aplicación prepara su propio esquema de base de datos y sus datos iniciales al arrancar.
Los paneles en el merge request (diseñados). La nota enlazaría a los paneles del producto filtrados por la vista previa, y los errores de una vista previa llegarían como comentario en el merge request.
El agente de auditoría (diseñado). Encontraría una vista previa que no tiene registro, o una cuya destrucción falló.

Las vistas previas funcionaron en los ensayos de la plataforma en septiembre de 2026. Una vista previa necesita que los proyectos del producto estén vinculados a facturación, y hoy ningún producto de demostración lo está, así que ninguno tiene una vista previa ahora.

Este sitio web también corre sobre la plataforma, pero no tiene vistas previas: el mantenedor decidió que un merge request al sitio no recibe ninguna.

Dónde está

En el repositorio control-plane:

En el repositorio golden-path: