Well-ArchitectedComunidade
Nível de dificuldade: Básico (2 de 5)
Terragrunt stacks reduzem provisionamento de ambiente AWS de dias para 30 minutos
Em números
- 2 a 3 dias era o tempo que um DevOps gastava copiando pastas de outro time para montar um ambiente AWS do zero
- 30 minutos é o tempo atual, a maior parte consumida pelo EKS criando o control plane
- 70+ engenheiros de DevOps espalhados em times de domínio, cada um com seu próprio Terraform copiado de alguém
- 4 meses foi o prazo em que Mher Poghosyan projetou e construiu sozinho módulos, stacks, contratos, CI e documentação da plataforma
O problema
A empresa onde Mher Poghosyan trabalha tinha mais de setenta engenheiros de DevOps distribuídos em times de domínio, cada um cuidando do próprio Terraform. Na prática, a maior parte desse código tinha nascido como cópia do repositório de outro time, com nomes trocados e um valor ou outro ajustado manualmente.
Isso funcionou até parar de funcionar, como relata o post publicado na DEV Community. Três sintomas apareceram juntos:
- Drift entre cópias: dois ambientes supostamente idênticos acabavam com layout de subnet, tags e IAM diferentes
- Módulos à deriva: era comum apontar para
ref=mainem vez de uma tag fixa, então uma mudança num módulo compartilhado chegava à produção no próximoplansem ninguém revisar - Bootstrap manual: criar bucket de state, credenciais de CI e delegação de DNS virava um checklist que só existia na cabeça de alguém
- Review inútil: quando cada ambiente é formado por milhares de linhas copiadas, ninguém lê o diff de verdade
O ponto de virada não foi um incidente único, mas o acúmulo de retrabalho: todo ambiente novo custava dois a três dias de um engenheiro sênior caçando o único valor que tinha sido diferente da última vez.
A arquitetura
A solução descrita por Poghosyan organiza o repositório em quatro camadas, cada uma com uma responsabilidade fechada:
| Camada | O que contém | Quem edita |
|---|---|---|
| Live repository | Apenas valores e uma tag de release fixa | Time de domínio |
| Stack | Composição de units em um produto (ex.: team-environment) | Time de plataforma |
| Units | Um módulo cada, mais o contrato de entradas/saídas | Time de plataforma |
| Modules | Terraform puro, versões fixadas do terraform-aws-modules | Time de plataforma |
Nota: a fonte confirma explicitamente que o live repository pertence aos times de domínio. A atribuição das demais camadas a um "time de plataforma" é leitura do artigo a partir da arquitetura descrita, não uma afirmação direta da fonte.
O fluxo, do pedido do time até o recurso provisionado na AWS, segue estes passos:
- O time de domínio escreve cerca de quinze linhas em um arquivo
terragrunt.stack.hclcom valores comoteam,environment,cidr,zone_nameekubernetes_version - Abre um pull request no próprio
live repository, que não contém lógica, só valores e uma versão fixada do catálogo - A CI roda
terragrunt stack generate, que expande o stack em units, e depoisterragrunt stack run plan, que executa as units na ordem de dependência declarada nos contratos - Cada unit resolve suas dependências (por exemplo, a unit
ekslêvpc_ideprivate_subnet_idsda unitnetwork) e aplica o módulo Terraform correspondente, já fixado em versão exata - Depois do merge e da aprovação do ambiente protegido no GitHub, a CI assume um papel de apply via OIDC e executa a criação real: account baseline, VPC, DNS e cluster EKS com Karpenter
- O ambiente fica pronto em cerca de trinta minutos, a maior parte do tempo gasta pelo EKS subindo o control plane
A fonte trata a integração com GitOps como próximo passo da plataforma, ainda não implementado no fluxo de criação atual: o autor escreve que o próximo item do roteiro é "handing every new cluster over to GitOps right after creation".
No repositório de referência que o autor publicou, github.com/devopsmher/terragrunt-platform, esse fluxo inteiro aparece como um stack chamado team-environment, com o exemplo de uso mostrando exatamente os campos que um time preenche: catalog, version, team, environment, cidr, zone_name, kubernetes_version, github_repository e state_bucket.
Os serviços envolvidos
A pilha combina Terragrunt sobre Terraform com serviços gerenciados da AWS e integração via GitHub Actions:
- Terragrunt stacks: o recurso
terragrunt stack generateeterragrunt stack run planfazem a expansão de stack em units e a execução em ordem de dependência, sem um gerador customizado - Amazon EKS com Karpenter: a unit
eksprovisiona cluster, node group de sistema e Karpenter configurado com interruption handling, cobrindo o caso de uso de autoscaling de nós - VPC e subnets: a unit
networkentregavpc_id,private_subnet_idseintra_subnet_idscomo saídas consumidas por outras units - IAM via OIDC: a unit
account-baselinecria dois papéis por conta, consumidos pelo GitHub Actions através de troca de token OIDC, sem chave de acesso de longa duração armazenada na CI - Amazon S3: além de armazenar o state do Terraform, o bucket também guarda o
.tflockusado pelo locking nativo do S3, liberando o papel de plan para escrever o lock sem precisar de permissão de apply - DNS: a unit de DNS depende de uma delegação de zona feita manualmente pelo time pai a cada novo ambiente. Esse passo é diferente do bootstrap (que acontece uma única vez por conta); é o bootstrap, e não a delegação de DNS, que o autor cita como "o único passo manual" que decidiu manter explícito em vez de automatizar
Módulos são, na definição do autor, "thin wrappers" sobre módulos já conhecidos do terraform-aws-modules, fixados em versão exata, com defaults da empresa por cima: tags, layout de subnet e regras de acesso.
Trade-offs
O maior trade-off de design foi colocar contrato antes de módulo, o que toca diretamente o pilar de excelência operacional do Well-Architected Framework. Cada unit declara no topo do arquivo quais valores recebe, quais saídas entrega e de quais outras units depende, como no comentário que abre a unit eks no repositório de referência.
Isso custa tempo de design adiantado, mas paga de volta em dois pontos que a fonte destaca:
- Falha cedo: um stack que esquece um valor falha no momento da geração (
terragrunt stack generate), não vinte minutos dentro de umapplyque já começou a criar recursos - Mocks só para planejamento:
mock_outputs_allowed_terraform_commandslibera mocks apenas parainit,validateeplan; nunca paraapply, porque permitir mock no apply transformaria uma dependência ausente em ambiente quebrado
O segundo trade-off relevante toca segurança: nenhuma chave da AWS vive na CI. A troca por papéis OIDC de curta duração reduz superfície de ataque, mas introduz um acoplamento novo entre o GitHub Actions e a configuração de trust de cada conta, que precisa ser mantida corretamente em todas as contas gerenciadas.
| Papel | Quando é assumido | O que pode fazer |
|---|---|---|
| Plan role | Pull requests do live repository do time | Leitura, mais escrita do .tflock via locking nativo do S3 |
| Apply role | Jobs rodando no ambiente protegido do GitHub (ex.: payments-dev) | Aplicar mudanças, condicionado a aprovação manual |
Um detalhe que o autor sublinha e que vale para quem desenha pipeline parecido: confiar num environment do GitHub, em vez de confiar numa branch, impede que um workflow editado dentro do próprio pull request consiga assumir o papel de apply, porque o job nunca passa pelas regras de proteção daquele ambiente.
O custo de disciplina aparece também na versão: toda mudança no catálogo (módulos, units e stacks) sai sob uma única tag semver, e um script de CI rejeita qualquer coisa que não esteja fixada: branch, ref ausente ou range de versão em módulo de registry. Isso impacta o pilar de confiabilidade, eliminando a classe de incidente em que "ninguém mudou nada, mas o plan está diferente".
Custo estimado
A fonte não publica valores de fatura da AWS nem custo de instância; o número de custo que ela dá é de esforço de engenharia, não de nuvem. Vale registrar os dois números que ela documenta nesse eixo: o autor diz ter projetado e construído sozinho toda a plataforma (módulos, stacks, contratos, CI e documentação) em menos de quatro meses, e o ganho recorrente por ambiente novo é a diferença entre dois a três dias de trabalho manual e cerca de trinta minutos de espera, a maior parte dela ociosa aguardando o control plane do EKS subir.
Para quem avalia se vale montar algo parecido, o cálculo prático é: multiplicar o tempo economizado por ambiente pelo número de ambientes criados por trimestre, e comparar com o esforço de construir e manter o catálogo de módulos, units e stacks, que não é zero depois do lançamento inicial.
Como adaptar
O quick start documentado pelo autor tem propositalmente só quatro passos, porque a plataforma só é self-service de verdade se um time consegue segui-la sem abrir chamado com o time de plataforma:
- Copiar o diretório de ambiente de exemplo e trocar os valores
- Fazer o bootstrap uma única vez: um administrador aplica o account baseline, que cria o bucket de state e os papéis de CI
- Abrir um pull request: a CI roda o plan; depois de aprovado e mergeado, a CI roda o apply
- Delegar a zona de DNS a partir do domínio pai
O autor é explícito sobre o passo manual de bootstrap em vez de escondê-lo:
Fingir que não existe um problema de ovo e galinha não faz ele desaparecer.
Pretending there is no chicken-and-egg problem does not make it go away.Mher Poghosyan, Senior DevOps & Platform Engineer
Para um arquiteto ou time de SRE que queira replicar o padrão em Terraform puro ou com outra ferramenta de composição, os pontos que a fonte recomenda levar primeiro são: desenhar o contrato de cada unit antes de escrever o módulo, manter stacks finos (composição pura, lógica fica no módulo, onde pode ser testada), fixar versão de tudo incluindo o próprio catálogo interno, e tratar documentação como parte do produto, não como anexo.
O repositório github.com/devopsmher/terragrunt-platform é apresentado como reescrita clean-room do padrão, sem código do projeto original, com todos os módulos passando terraform validate e o stack de exemplo passando validação estrita de inputs, o que o torna um ponto de partida razoável para quem quiser ler o contrato completo da unit eks ou da unit network antes de decidir adaptar a ideia para Terraform puro ou para outra convenção de composição.
Vale notar o limite da experiência: é o relato de uma pessoa sobre uma plataforma interna de uma empresa não nomeada, sem métrica de confiabilidade de longo prazo nem comparação de custo de manutenção do catálogo contra o modelo anterior de cópia. Quem for adotar o padrão deve tratar os números de tempo (dois a três dias contra trinta minutos) como o ganho documentado, e o esforço de quatro meses de construção como o investimento correspondente, sem assumir que a proporção se repete em outro contexto.
Fonte: DEV Community — #aws
Serviços neste textoWell-ArchitectedTerraform
Leve para a sua IA
Decida com o seu assistente, com o contexto deste texto já montado.
1. O que você quer saber
Ver o prompt
Li no AWS Hub: "Terragrunt stacks reduzem provisionamento de ambiente AWS de dias para 30 minutos" (https://awshub.com.br/comunidade/terragrunt-stacks-reduzem-provisionamento-de-ambiente-aws-de-dias-para-30-minuto). Resumo: Um engenheiro de plataforma documentou como contratos entre camadas de Terragrunt, versionamento semver e papéis OIDC eliminaram a cópia de pastas entre times e transformaram a criação de ambientes AWS em self-service. Serviços: Well-Architected, Terraform Minha stack: [descreva em uma linha: serviços, linguagem, volume, região] Isso muda alguma coisa na minha arquitetura? O que eu faria diferente a partir de amanhã?