O caminho de uma mudança

Toda mudança em um produto do Airframe, uma funcionalidade nova, um banco de dados, um ajuste de configuração, percorre o mesmo caminho até a produção, tenha sido escrita por uma pessoa ou por um agente de código. Esta página percorre esse caminho em nove passos e nomeia a verificação de cada um, para que se veja o que para uma mudança ruim e onde. O exemplo é uma mudança no produto de pedidos da organização de demonstração.

1. Uma pessoa ou um agente de código faz uma mudança

Um desenvolvedor, ou um agente de código trabalhando para ele, muda o repositório do produto em uma branch: a aplicação em apps/, a infraestrutura em infra/, ou o arquivo de pipeline. As skills do platform-skills ensinam a um agente de código onde fica cada tipo de mudança e o que as regras esperam.

2. A validação local

Antes de abrir um merge request, o autor roda airframe validate no notebook. Ele não precisa de credenciais e roda a maior parte da validação do merge request: a formatação e a validação do Terraform, o OpenTofu e o tflint onde estão instalados, e o pacote de políticas sobre as raízes, o arquivo de pipeline e os Dockerfiles declarados. Uma regra que falha nomeia o recurso e, muitas vezes, o que fazer no lugar, então o autor corrige e valida de novo.

3. O pipeline do merge request

O pipeline do merge request roda no runner não confiável da plataforma, uma máquina que não tem nenhuma credencial da nuvem que um job possa usar. O repositório não pode remover os jobs injetados nele:

gate:integrity pergunta ao controle de aprovação se este pipeline pode rodar, e faz falhar um que use uma versão revogada;
a validação, incluindo o pacote de políticas, sobre as raízes e o arquivo de pipeline do produto;
a compilação e os testes da aplicação, com a cobertura de testes que a entrada do catálogo exige;
a detecção de segredos, a análise de dependências e a análise estática do GitLab.

Uma recusa ou um teste que falha faz o pipeline falhar, e o GitLab não integra até ele passar.

4. Os responsáveis aprovam, depois o controle

Alguém que não escreveu a mudança a aprova: uma pessoa nomeada do catálogo, nunca um papel. Quais pessoas contam depende do que a mudança toca, segundo o modelo de responsáveis do catálogo: a equipe para infra/, a equipe ou a equipe da plataforma para o arquivo de pipeline.

Quando elas aprovaram, o GitLab chama o controle de aprovação. O controle verifica as aprovações no último commit, adiciona a sua, vinculada àquele commit, e inicia o executor. Um commit novo enviado depois zera as aprovações e o ciclo começa de novo.

5. Os planos do executor e a verificação de custo

O executor roda no runner confiável e verifica de novo que o commit é o aprovado. Depois, com as identidades do próprio produto:

planeja cada raiz do Terraform do produto com a identidade de plan, que não pode mudar nada, e publica os planos no merge request para quem revisa;
coloca preço nos planos com o Infracost, e o controle define a verificação de status “Airframe cost”, que falha quando o total ou qualquer raiz sozinha passa do orçamento mensal do produto;
faz o construtor confiável construir as imagens de contêiner do commit;
implanta uma prévia da mudança com a identidade de não produção, no seu próprio nome de host, destruída quando o merge request é integrado ou fechado, ou quando seu tempo acaba.

6. O merge

O GitLab só integra quando o pipeline passou, as pessoas certas e o controle aprovaram o último commit, e a verificação de custo passou. (A aprovação do controle é exigida em cada repositório que a política de aprovação nomeia, que hoje são todos menos o security-policies; um repositório de produto criado depois entra nessa lista com dois merge requests, como explica a página do controle.) Cada merge é só fast-forward, então o que foi aprovado e testado é exatamente o que chega à main.

7. O pipeline da main aplica

Na branch main protegida, o pipeline roda no runner confiável, cada raiz com sua própria identidade de apply, que só um job deste repositório em uma branch protegida e no ambiente certo pode obter. Primeiro, gate:integrity confirma que este commit é o último de um merge request integrado. Depois, para cada raiz, plan:<root> a planeja de novo contra a infraestrutura real, policy:<root> roda o pacote de políticas sobre o plano, e apply:<root> a aplica só se isso passou. Um plano que as regras de custo do executor recusaram também para aqui.

8. Imagens construídas, atestadas e promovidas

As imagens foram construídas na aprovação, pelo construtor confiável, a partir do commit aprovado. Antes que uma identidade separada assine o atestado de compilação, o executor confere o próprio registro do Cloud Build sobre a compilação. Na main, deploy:promote faz copiar as imagens por digest para o registro de produção, o que adiciona um segundo atestado. A produção espera esse passo.

9. Produção

Os serviços do produto rodam no Cloud Run. Todo serviço implantado pelo módulo de Cloud Run do golden path adere à política de Binary Authorization do seu projeto, que no projeto de produção de um produto com faturamento só admite uma imagem com os dois atestados. Nada ainda obriga um serviço a aderir: um implantado sem esse módulo roda sem a verificação, uma lacuna que a página de zero privilégio permanente também menciona.

A mudança está em produção. Se algo falhou no caminho, o passo que falhou diz por quê, e a correção é outro merge request pelo mesmo caminho.

Onde fica

No repositório control-plane: