Reconciliadores
Um reconciliador é um job automático que lê o catálogo e faz uma parte do mundo real corresponder a ele: os projetos na nuvem, os grupos do Google, os repositórios do GitLab ou os painéis. Depois de cada merge no catálogo, uma cadeia de reconciliadores roda em uma ordem fixa, e juntos eles constroem ou mudam tudo o que o catálogo descreve. É assim que um arquivo vira um produto funcionando sem que ninguém crie nada à mão.
O que é um reconciliador
Seção intitulada “O que é um reconciliador”Cada reconciliador é uma raiz do Terraform: um diretório de código Terraform que lê os arquivos do catálogo e declara o que deve existir. O Terraform compara isso com o que realmente existe e faz a diferença: cria o que falta, muda o que difere e remove o que o catálogo não pede mais.
Cada raiz tem sua própria identidade de pipeline, e essa identidade só pode mudar a sua parte da plataforma. A fábrica de projetos do domínio shop/store pode criar projetos nas pastas desse domínio, e nada mais. A raiz que administra as associações do GitLab não pode tocar em um projeto na nuvem. Se uma delas fosse comprometida, o dano ficaria dentro da sua própria parte.
O pipeline do próprio catálogo não tem nenhuma dessas identidades. Na branch main do catálogo, ele verifica os arquivos e inicia os pipelines dos outros repositórios, em ordem; ele não pode criar um projeto sozinho.
A cadeia depois de um merge no catálogo
Seção intitulada “A cadeia depois de um merge no catálogo”Quando um merge request no catálogo é integrado, o pipeline do catálogo na main roda estes passos, cada um esperando o anterior:
- O ciclo de vida roda. Se o merge mudou o status do ciclo de vida de um produto, por exemplo para
retiring, o próprio pipeline do produto aplica essa mudança primeiro, com as identidades do próprio produto. Os serviços de um produto precisam sair antes que algo mais adiante exclua o que eles usam. - landing-zone. Suas raízes criam a pasta de um contexto novo, os grupos do Google e seus membros, e, pela fábrica de projetos do domínio do produto, os dois projetos do produto, suas identidades de plan e de apply, seus lugares para o estado do Terraform e sua saída Ready: um pequeno documento que diz a cada raiz seguinte o que foi feito. Depois, as raízes de rede conectam os projetos que têm faturamento.
- operations. Suas raízes dão às identidades novas o que elas precisam para enviar telemetria, e criam a pasta, os painéis e as regras de alerta do produto no Grafana.
- control-plane. Suas raízes do GitLab criam o repositório do produto, protegem sua branch main, dão à equipe suas associações e permissões de merge, e escrevem o primeiro commit, gerado a partir do template do golden path com os valores da entrada do catálogo.
- landing-zone de novo. Uma segunda passada termina o que precisava dos outros primeiro. Para um produto que está saindo, ela desvincula o faturamento ou exclui os projetos, depois que control-plane e operations retiraram o que tinham concedido às identidades do produto.
Uma nota no merge request do catálogo já integrado acompanha esses passos enquanto rodam, com seus horários e links. Para um produto novo, ela termina quando o produto responde no seu nome de host, ou nomeia o passo que falhou.
Por que a ordem importa
Seção intitulada “Por que a ordem importa”Cada passo usa o que o passo anterior fez. Operations não pode conceder nada a uma identidade que ainda não existe, então roda depois que landing-zone criou as identidades. Control-plane escreve o primeiro commit do repositório a partir da saída Ready, então roda depois que a fábrica de projetos a publicou. E um produto que deixa a plataforma precisa primeiro parar de rodar, depois perder suas concessões, e só então perder seus projetos: por isso o ciclo de vida vem primeiro e a segunda passada de landing-zone vem por último.
A cadeia é rígida com falhas pelo mesmo motivo: cada passo espera seu pipeline terminar, e se um falha, os passos seguintes não rodam. Nada mais adiante age sobre algo que não foi feito.
O que significa “nada derivado é editado à mão”
Seção intitulada “O que significa “nada derivado é editado à mão””Tudo o que um reconciliador cria fica registrado no seu estado do Terraform, e o reconciliador é o único jeito de mudá-lo. As identidades de um projeto, as proteções de um repositório, as associações de uma equipe e um painel são mudados mudando o catálogo, nunca no console do Google Cloud nem nas configurações do GitLab.
É uma regra que tem efeito. Se alguém muda à mão algo derivado, o próximo plano dessa raiz vê a diferença e a desfaria, e um plano agendado de cada raiz a relata como desvio em uma issue. O jeito de mudá-lo de verdade é um merge request no catálogo.
Quando um reconciliador falha
Seção intitulada “Quando um reconciliador falha”Uma falha para a cadeia naquele passo, e a nota de progresso no merge request do catálogo nomeia o job que falhou e o que fazer em seguida. As causas comuns são um erro no catálogo que suas verificações não pegaram, uma cota do Google Cloud, ou um bug em uma raiz.
A correção é um merge request: no catálogo, se a entrada estava errada, ou no repositório da raiz, se a raiz estava. O merge roda a cadeia de novo, e como cada raiz só faz a diferença entre o catálogo e o que existe, rodá-la de novo é seguro: o que já foi feito fica como está. O agendamento diário de cada repositório planeja suas raízes sem aplicá-las, então nada muda até alguém integrar uma correção.
Onde fica
No repositório catalog:
No repositório landing-zone:
- roots/project-factory/: uma fábrica por domínio
- roots/groups/: os grupos do Google
- docs/guides/product-lifecycle.md: os passos em detalhe
No repositório operations:
No repositório control-plane: