Políticas como código

No Airframe, as regras da plataforma são código: um conjunto de regras testadas, o pacote de políticas, verifica cada mudança no Terraform, no arquivo de pipeline e nos Dockerfiles declarados de um produto antes que ela possa ser integrada, e verifica o plano de novo antes de qualquer aplicação. As pessoas aprovam para que serve uma mudança; as regras verificam como ela é feita. Esta página explica o que as regras olham, o que seus dois vereditos fazem, e as lacunas que ainda estão abertas.

O que é o pacote de políticas

O pacote de políticas é um conjunto de regras escritas em Rego, a linguagem do Open Policy Agent, guardado no repositório control-plane. Uma ferramenta chamada Conftest as roda contra uma mudança. Cada regra olha uma coisa e diz se ela é permitida, por exemplo:

nenhum recurso pode ser concedido a allUsers, o que o tornaria público;
ninguém pode receber os papéis amplos owner ou editor;
todo recurso com rótulos tem o conjunto completo de rótulos da plataforma, que o ligam ao seu produto para custo e auditoria;
todo recurso regional fica em us-central1, a única região da plataforma;
o arquivo de pipeline de um produto inclui só os componentes de pipeline da própria plataforma, e nenhum dos seus jobs implanta;
um Dockerfile só constrói a partir das imagens base da plataforma, fixadas.

Onde ele roda

As mesmas regras rodam em quatro lugares, então quem contribui encontra a mesma resposta em todos:

Em um notebook, pelo airframe validate, sem credenciais, antes de abrir um merge request.
No pipeline do merge request, sobre o código Terraform e o arquivo de pipeline, em um job que o repositório não pode remover. A partir da versão da plataforma 2026.10.01-1, ele também roda as regras de Dockerfile em todo merge request que muda um Dockerfile listado em .airframe/images.yaml e chamado Dockerfile, Dockerfile.*, *.Dockerfile ou *.dockerfile.
Nas execuções do executor, na aprovação de um merge request.
Sobre o plano, na main, no job policy:<root> da raiz antes de cada apply: o apply precisa que esse job passe. O plano mostra os valores reais que o código sozinho pode deixar sem resolver, então é aqui que as regras veem tudo.

As regras de custo são a única exceção: elas precisam de preços, então rodam no executor e decidem a verificação de status “Airframe cost”. A página do controle de aprovação e do executor explica isso.

Uma validação que um produto não pode desligar

O arquivo de pipeline de um produto é da equipe para mudar, então as verificações importantes não vivem nele. As políticas de execução de pipeline do GitLab, guardadas no repositório security-policies, injetam jobs em cada pipeline:

a verificação de integridade do controle de aprovação, em cada pipeline do grupo do GitLab;
a validação, incluindo o pacote de políticas, e a evidência de compilação e testes, em cada pipeline do repositório de um produto.

O GitLab não deixa o próprio arquivo de pipeline de um repositório remover ou substituir um job injetado.

Recusar e alertar

Uma regra dá um de dois vereditos:

Recusar (deny) para a mudança. O job falha, e o GitLab só integra um merge request quando seu pipeline termina bem. Na main, uma recusa sobre o plano para o apply.
Alertar (warn) relata algo para olhar, como um recurso que um produto declara por conta própria em vez de usar um módulo do golden path. Hoje um alerta aparece no log do job e não segura nada. O design pede a aprovação da plataforma e uma entrada em um registro de exceções para cada alerta; essa parte ainda não foi construída.

Uma regra nova de recusa costuma passar sua primeira versão como alerta, para que as equipes corrijam o que ela recusaria antes que ela comece a recusar.

Mensagens escritas para agir

Uma regra que falha nomeia o recurso que julgou e o que há de errado com ele, e muitas também dizem o que fazer no lugar. Um bucket de armazenamento concedido a allUsers é recusado com o conselho de expô-lo pela borda da plataforma atrás do login único. Um job que declara o ambiente prod é orientado a implantar pelo componente tf-apply da plataforma. As mensagens são escritas para quem as lê em seguida, uma pessoa ou um agente de código, então o ciclo é curto: mudar, validar, ler, corrigir, validar de novo.

Como uma regra é testada

Cada regra deveria vir com um caso que ela precisa aceitar e um que precisa recusar, e o job policy:test do pipeline de control-plane roda todos os testes a cada mudança no pacote. O GitLab só integra uma mudança no pacote quando esse job passa. Que cada regra nova traga seus próprios testes é uma convenção mantida na revisão, não algo que um job verifica.

O que roda onde

airframe validate roda a validação que não precisa de credenciais: 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 do Terraform, o arquivo de pipeline e os Dockerfiles declarados. Ele não roda as verificações do catálogo, o controle de aprovação, os testes da aplicação, o plano nem seu preço; esses precisam da plataforma e ficam no pipeline. Ele lê o pacote a partir da cópia de control-plane de onde foi instalado, não da versão da plataforma que o produto usa.

Lacunas conhecidas

Estas estão abertas hoje, e os registros da própria plataforma as listam:

Um alerta não segura nada, como dito acima.
Um Dockerfile listado em .airframe/images.yaml com outro nome, como Containerfile, só é verificado quando o merge request também muda outro arquivo que a validação observa.
Um recurso sem nenhum atributo labels passa pela regra de rótulos, que verifica os rótulos que um recurso declara.
airframe validate não roda testes de módulos, nem a revisão da especificação da API, nem a verificação de compatibilidade da API, embora as instruções da plataforma as nomeiem.

Onde fica

No repositório control-plane:

No repositório security-policies:

.gitlab/security-policies/policy.yml: o que é injetado, e as políticas de aprovação