AWS HubAWS HubSão Paulo operando · 2 eventos no mundo

Well-ArchitectedComunidade

Nível de dificuldade: Básico (2 de 5)

Terragrunt stacks reduzem provisionamento de ambiente AWS de dias para 30 minutos

Por AWS Hub9 min de leitura

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=main em vez de uma tag fixa, então uma mudança num módulo compartilhado chegava à produção no próximo plan sem 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:

CamadaO que contémQuem edita
Live repositoryApenas valores e uma tag de release fixaTime de domínio
StackComposição de units em um produto (ex.: team-environment)Time de plataforma
UnitsUm módulo cada, mais o contrato de entradas/saídasTime de plataforma
ModulesTerraform puro, versões fixadas do terraform-aws-modulesTime 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:

  1. O time de domínio escreve cerca de quinze linhas em um arquivo terragrunt.stack.hcl com valores como team, environment, cidr, zone_name e kubernetes_version
  2. 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
  3. A CI roda terragrunt stack generate, que expande o stack em units, e depois terragrunt stack run plan, que executa as units na ordem de dependência declarada nos contratos
  4. Cada unit resolve suas dependências (por exemplo, a unit eks lê vpc_id e private_subnet_ids da unit network) e aplica o módulo Terraform correspondente, já fixado em versão exata
  5. 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
  6. 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 generate e terragrunt stack run plan fazem 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 eks provisiona 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 network entrega vpc_id, private_subnet_ids e intra_subnet_ids como saídas consumidas por outras units
  • IAM via OIDC: a unit account-baseline cria 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 .tflock usado 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 um apply que já começou a criar recursos
  • Mocks só para planejamento: mock_outputs_allowed_terraform_commands libera mocks apenas para init, validate e plan; nunca para apply, 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.

PapelQuando é assumidoO que pode fazer
Plan rolePull requests do live repository do timeLeitura, mais escrita do .tflock via locking nativo do S3
Apply roleJobs 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:

  1. Copiar o diretório de ambiente de exemplo e trocar os valores
  2. Fazer o bootstrap uma única vez: um administrador aplica o account baseline, que cria o bucket de state e os papéis de CI
  3. Abrir um pull request: a CI roda o plan; depois de aprovado e mergeado, a CI roda o apply
  4. 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ã?

Newsletter semanal

A semana da AWS, em português

Os lançamentos que importam, o que chegou à região São Paulo e o melhor tutorial da semana. Toda sexta, gratuita.