Airframe

Por que o Airframe

Uma prévia para cada merge request

Os revisores deveriam poder testar uma mudança, não só lê-la. Assim que as pessoas certas aprovam o merge request de um produto, a plataforma implanta uma prévia do produto num nome de host próprio, com um banco de dados próprio, e a destrói no merge, no fechamento ou quando o seu tempo acaba.

Como um merge request ganha a sua prévia

  1. A mudança é aprovada

    O pipeline do próprio merge request executa código que ninguém revisou ainda, então não tem nenhuma credencial da nuvem e não implanta nada. Quando o controle de aprovação aprova o merge request de um produto, ele inicia as execuções do executor para aquele commit exato: os planos, a construção das imagens e a prévia. Um produto cujo status no catálogo é retiring não recebe prévia, já que não serve nada.

  2. O executor a implanta

    A execução da prévia espera até 25 minutos pela construção do último commit do merge request, e para se a construção falhou. Depois, com a identidade de aplicação de não produção do produto, ela planeja a raiz infra/eph do produto, passa o pacote de políticas sobre o plano, calcula o preço e o aplica. A identidade de produção nunca é usada, então uma prévia não pode tocar a produção.

  3. Seu próprio nome de host, seus próprios dados

    A prévia responde em <product>-eph-<iid>.<domain>.<journey>.projectairframe.dev, onde <iid> é o número do merge request, atrás do login único para o grupo de usuários do produto. O roteador de prévias do produto lê o número no nome de host e encaminha para os serviços daquela prévia, que aceitam chamadas só do roteador. Por padrão, o banco de dados é um sidecar de PostgreSQL na mesma revisão do Cloud Run, com dados iniciais carregados na partida a partir dos arquivos do próprio produto.

  4. Os revisores testam a mudança

    O executor publica uma nota no merge request com o endereço da prévia, o seu preço e quando ela expira. Os revisores a abrem num navegador, onde cookies, redirecionamentos e links funcionam como em produção, e cada sinal leva o seu ambiente, que para uma prévia é eph-<iid>, para que os painéis do produto possam mostrá-la à parte: o golden path o define no serviço da prévia; o gateway OTLP o toma como o rótulo env, e o agente da plataforma e o gateway de logs o derivam do nome do serviço. Um novo push zera as aprovações, e a aprovação seguinte aplica a mesma prévia com o novo commit.

  5. Some no merge, no fechamento ou ao fim do seu tempo de vida

    Quando o merge request é integrado ou fechado, o controle de aprovação inicia a execução de destruição do executor, que confere por conta própria o estado do merge request, destrói a prévia e publica uma nota. Uma prévia também expira preview_ttl_hours depois do seu último apply, 72 a menos que a entrada do catálogo diga outra coisa. Um coletor diário destrói as expiradas e as que uma notificação perdida ou uma destruição que falhou deixaram para trás.

Um exemplo prático

O merge request 42 do produto invoicing, no domínio billing da jornada settle, é aprovado, e a sua entrada deixa as configurações de prévia nos valores padrão. Uma prévia precisa que os projetos do produto sejam faturados, e hoje nenhum produto da demo é faturado, então isto é o que aconteceria; as prévias funcionaram nos ensaios da plataforma em setembro de 2026.

  • O controle de aprovação aprova o commit e inicia para ele os planos, a construção das imagens e a prévia do executor
  • Assim que a construção passa, a execução da prévia planeja infra/eph com a identidade de aplicação de não produção do invoicing, confere o plano com o pacote de políticas, calcula o preço e o aplica
  • A nota do merge request dá o endereço, invoicing-eph-42.billing.settle.projectairframe.dev, o preço da prévia e a sua expiração, 72 horas depois do apply
  • O banco de dados é um sidecar de PostgreSQL que carrega os seus dados iniciais na partida; os logs, as métricas e os traces da prévia levam env eph-42
  • Um push zera as aprovações; a aprovação seguinte aplica a mesma prévia com o novo commit e uma nova expiração
  • O merge request é integrado: a execução de destruição remove a prévia, mantém o seu estado do Terraform vazio como registro e publica uma nota

O que torna isso verdade

Só uma mudança aprovada ganha uma prévia, e nunca com a identidade de produção.
O controle de aprovação inicia a execução da prévia do executor só quando aprova o merge request de um produto, e não para um produto com status retiring; a execução aplica a raiz infra/eph do produto com a identidade de aplicação de não produção, depois que o pacote de políticas conferiu o plano. O pipeline do próprio merge request não tem nenhuma credencial da nuvem. Como só uma mudança aprovada ganha uma prévia, alguém que só pode abrir merge requests não consegue inflar a conta.
Cada prévia tem o seu próprio nome de host, atrás do login único, e nenhuma outra entrada.
O certificado e o registro curinga do domínio cobrem todo nome de host <product>-eph-<iid>, então nada é emitido por prévia. O módulo preview-substrate do golden path dá a cada produto um roteador no seu projeto de não produção, atrás do IAP para o grupo de usuários do produto; o roteador lê o número do merge request no nome de host, e cada serviço de prévia nomeia o roteador como o seu único invocador.
Uma prévia é destruída quando o seu merge request termina.
O controle de aprovação fica sabendo do merge ou do fechamento pelo webhook do GitLab e inicia a execução de destruição do executor, que confere por conta própria o estado do merge request e destrói com a mesma identidade de não produção. O registro de cada prévia tem uma trava, então um apply e uma destruição nunca rodam ao mesmo tempo, e um merge request fechado e reaberto inicia uma nova geração, então uma destruição atrasada não consegue remover a nova prévia.
Uma prévia expirada ou esquecida é coletada.
preview:collect, um job do pipeline agendado diário do control-plane, lista as prévias que, segundo os registros do executor, ainda estão de pé, confere o estado e a expiração de cada merge request, e destrói as integradas, as fechadas e as que passaram do seu preview_ttl_hours (72 por padrão, no máximo 168, contadas a partir do último apply), com uma nota em cada merge request.
Uma prévia quase não custa nada enquanto está ociosa, e nunca bloqueia um merge.
O roteador e os serviços da prévia vão a zero, e o banco de dados sidecar padrão vive na própria revisão do serviço, com cerca de 512 MiB a mais de memória enquanto roda; o módulo de Cloud Run do golden path roda o serviço de uma prévia com no máximo uma instância. Uma instância compartilhada de Cloud SQL, quando a entrada a escolhe, só pode ser aplicada depois que o projeto de não produção do produto está na rede compartilhada da plataforma, e então custa cerca de USD 9 por mês por produto. O executor calcula o preço do plano de cada prévia e o mostra na nota, e a verificação de custo que segura um merge deixa as prévias de fora.