O bootstrap

O bootstrap é a lista curta de coisas que uma pessoa cria à mão para colocar o Airframe em funcionamento, antes que exista algum pipeline capaz de criá-las. Cada passo faz algo de que o próximo precisa, e cada um deixa um registro escrito, para que o começo da plataforma possa ser auditado como tudo o que veio depois. Esta página percorre os catorze passos em ordem e explica por que nenhum deles pode esperar um reconciliador.

A regra, e o registro

A primeira vez que algo é criado à mão é a última: um passo posterior coloca esse algo sob gestão, quase sempre importando-o em uma raiz do Terraform. O runbook é o docs/bootstrap.md do landing-zone. O registro dele é o docs/bootstrap-log.md, uma linha por passo: a data, a conta usada, o que foi criado (identificadores, nunca valores secretos), onde cada segredo fica guardado (pelo nome no Secret Manager) e o commit que o colocou sob gestão. Onde o runbook e o registro não batem, o registro está certo e o runbook é corrigido.

O registro também anota onde a prática se afastou do plano. O runbook pede chaves de segurança como único segundo fator nas contas de administração; as primeiras linhas do registro dizem que a verificação em duas etapas foi exigida de todos e que a exigência de chaves de segurança ficou para depois. O bootstrap do Airframe foi feito em 2026-09-04 e 2026-09-05.

Duas contas de administração fazem o trabalho: uma conta do Workspace com Organization Administrator, e a conta do GitLab dona do grupo de primeiro nível. As duas são usadas só aqui e em procedimentos excepcionais, e no resto do tempo ficam desconectadas.

Nos consoles, antes de qualquer código rodar

Condições prévias. A organização, a conta de faturamento, o grupo do GitLab, o stack do Grafana Cloud e o domínio já existem, como listam os pré-requisitos. Eles são o lugar onde o código roda, então nenhum código pode criá-los. Os identificadores deles são a primeira linha do registro.
Contas de administração e grupos, no console de administração do Workspace. Cria as contas de administração, o grupo da plataforma e o grupo de emergência. Um reconciliador precisa de uma identidade para rodar, e essas contas são onde a identidade começa. Os grupos são importados depois pela raiz de grupos do landing-zone.
Papéis para a janela de bootstrap, pela linha de comando. A conta de administração recebe papéis no nível da organização que vencem em catorze dias. As primeiras aplicações precisam de papéis que nenhuma identidade de pipeline tem ainda. Faltavam quatro papéis na lista do runbook, descobertos por aplicações que falharam, e o ADR-0002 do landing-zone registra o conjunto completo.
Cota de faturamento e orçamento, no console do Cloud. Um pedido para aumentar a cota de projetos da conta de faturamento, e um orçamento na conta. O Google recebe o pedido por um formulário, e o Airframe pediu no primeiro dia. O orçamento é importado pela raiz de pastas no passo 7.
O primeiro projeto e o bucket de estado, pela linha de comando. Um projeto de execução e um bucket para o estado do Terraform. O Terraform precisa de um lugar para guardar o estado antes que a primeira raiz possa rodar. A raiz de pastas assume o projeto no passo 7, e a raiz de estado assume o bucket no passo 8, adicionando a chave de criptografia dele.
O dono no GitLab e um token de bootstrap. A conta dona do grupo e um token de acesso pessoal que vence em catorze dias. O GitLab.com não cria um administrador para você, e a primeira aplicação da raiz do GitLab precisa de uma credencial. O token é revogado no passo 14.

De um notebook, dentro da janela

Estes passos são aplicações do Terraform a partir do notebook de um mantenedor, porque ainda não existe nenhum runner. O estado deles fica no bucket de estado da plataforma, e o registro anota o commit que cada um aplicou.

A raiz do GitLab, roots/gitlab do control-plane, com o token de bootstrap: os grupos, os repositórios da plataforma e suas proteções, os papéis personalizados, as contas de serviço e as políticas de segurança, escritas mas ainda não vinculadas ao grupo.
Pastas, políticas e os projetos da plataforma, roots/folders, roots/organisation e a fábrica de projetos da plataforma, no landing-zone: as pastas, as políticas da organização e as políticas de negação, e os projetos da própria plataforma.
Estado e identidade, roots/state e roots/wif: os buckets de estado com suas chaves de criptografia, e o provedor de federação de identidade de carga de trabalho com as vinculações das raízes da plataforma e do executor.
A rede e os runners, a primeira versão da raiz de rede, e depois o runner confiável. Registrar um runner no GitLab gera um token de autenticação, que uma pessoa guarda no Secret Manager: esse é o segundo token feito à mão, e o do runner não confiável é o terceiro. O passo termina quando um pipeline na main do control-plane roda um job no runner confiável e obtém uma credencial de curta duração.

A partir daí, as raízes são aplicadas por pipeline. Três continuam sendo aplicadas de um notebook, com uma concessão de tempo limitado que outro membro do grupo da plataforma aprova: organisation, audit e wif. Elas precisam de papéis no nível da organização ou de administração do IAM que nenhuma identidade de pipeline tem, e o wif, que dá os papéis a todas as outras identidades, faria do pipeline dele o mais poderoso da plataforma (ADR-0002 e ADR-0008 do landing-zone).

Por pipeline, e as últimas mãos

Todas as outras raízes, cada uma por um merge request normal: grupos, a rede completa, os perímetros em modo de teste, as concessões, as primeiras entradas do catálogo, as raízes do operations, o executor e o controle de aprovação. A raiz de auditoria é a exceção: ela foi aplicada de um notebook dentro da janela, como as outras duas acima. Um papel é atribuído à mão no console de administração do Workspace: Groups Administrator para a identidade da fábrica de grupos, de que a fábrica precisa antes de conseguir rodar. O registro anota isso.
Tokens do Grafana Cloud, no portal do Grafana. As políticas de acesso e seus tokens, e o cliente do login único. O stack gratuito é criado à mão, os escopos de uma política de acesso só mudam no portal, e nenhum valor secreto pode entrar no estado do Terraform: as raízes criam cada segredo pelo nome, e um mantenedor adiciona o valor.
Concessões, e a janela fechada. A raiz pam é aplicada por pipeline e cria as permissões do Privileged Access Manager. Uma concessão é pedida, aprovada por uma segunda pessoa, usada e deixada vencer, como ensaio. Depois, todos os papéis da janela são retirados à mão da conta de administração, que fica só com Organization Administrator. O Airframe fechou a janela em 2026-09-05, treze dias antes do prazo.
Servidores de nomes no registrador. A raiz de rede já criou a zona de DNS pública; uma pessoa configura no registrador, que fica fora do Google Cloud, os servidores de nomes do domínio e o registro de assinatura, e depois confere se o e-mail continua chegando. Quando o controle responde no seu nome de host, a conta de administração do GitLab vincula as políticas de segurança ao grupo a partir de um notebook, por uma segunda aplicação da raiz do GitLab: a política de pipelines do grupo todo injeta o gate:integrity em cada pipeline, e o job falha de forma fechada até o controle servir, então vinculá-las antes pararia o pipeline que implanta o controle.
A renúncia aos privilégios. O token de bootstrap é revogado, a conta de administração do GitLab fica como única Owner do grupo, nenhuma conta de uso diário tem Maintainer ou Owner em lugar nenhum, e a verificação diária de quem tem qual papel na organização roda pela primeira vez. Os pipelines agendados são criados à mão por um mantenedor que pode fazer merge, porque um agendamento roda com as permissões do seu dono. As contas de administração são desconectadas.

Depois do bootstrap

O registro não se fecha. Cada passo posterior feito à mão acrescenta uma linha, como uma aplicação de uma das três raízes a partir de um notebook com uma concessão, ou uma mudança na raiz do GitLab pelo procedimento excepcional: um token de um dia da conta de administração do GitLab, usado de um notebook e revogado em seguida. O runbook também lista o que nunca é feito à mão, como os projetos dos produtos, os repositórios, os grupos e os registros de DNS: precisar fazer uma dessas coisas à mão é registrado como um erro de um reconciliador.

Repetir o bootstrap está projetado: o runbook diz que os passos 1 a 5 podem ser conferidos a olho, que as aplicações seguintes convergem, e o registro nomeia o que uma repetição teria de importar. O runbook prevê uma reconstrução completa em uma segunda organização de teste vazia, e ainda não existe nenhum registro de uma.

Onde fica

No repositório landing-zone: